===========================================
GUÍA COMPLETA DE PUBLICACIÓN EN PyPI
Haka Playwright Engine v1.3.17
===========================================

Esta guía te llevará paso a paso para publicar el framework en PyPI.

===========================================
REQUISITOS PREVIOS
===========================================

1. CUENTA EN PyPI
-----------------
✅ Crea una cuenta en: https://pypi.org/account/register/
✅ Verifica tu email
✅ Habilita 2FA (Two-Factor Authentication) - REQUERIDO

2. CUENTA EN TestPyPI (Opcional pero Recomendado)
--------------------------------------------------
✅ Crea una cuenta en: https://test.pypi.org/account/register/
✅ Verifica tu email
✅ Habilita 2FA

3. TOKENS DE API
----------------
PyPI ya no acepta contraseñas para subir paquetes. Debes usar tokens.

Para PyPI:
1. Ve a: https://pypi.org/manage/account/token/
2. Click en "Add API token"
3. Nombre: "haka-playwright-engine-upload"
4. Scope: "Entire account" (primera vez) o "Project: haka-playwright-engine" (actualizaciones)
5. Copia el token (empieza con "pypi-...")
6. ⚠️ GUÁRDALO EN UN LUGAR SEGURO - Solo se muestra una vez

Para TestPyPI (opcional):
1. Ve a: https://test.pypi.org/manage/account/token/
2. Sigue los mismos pasos

4. INSTALAR HERRAMIENTAS
------------------------
pip install build twine

===========================================
MÉTODO 1: PUBLICACIÓN AUTOMÁTICA (RECOMENDADO)
===========================================

Usa el script automatizado que hemos creado:

python publish_to_pypi.py

El script hará:
1. ✅ Verificar versión (1.3.0)
2. ✅ Verificar dependencias
3. ✅ Limpiar builds anteriores
4. ✅ Construir el paquete
5. ✅ Verificar el paquete con twine
6. ✅ Subir a TestPyPI (opcional)
7. ✅ Subir a PyPI

Cuando te pida el token:
- Username: __token__
- Password: [tu token de PyPI]

===========================================
MÉTODO 2: PUBLICACIÓN MANUAL (PASO A PASO)
===========================================

PASO 1: Verificar Versión
--------------------------
Asegúrate de que la versión 1.3.17 esté en:
- setup.py (línea: version="1.3.17")
- pyproject.toml (línea: version = "1.3.17")
- CHANGELOG.md (sección: ## [1.3.17])

PASO 2: Limpiar Builds Anteriores
----------------------------------
# Windows (PowerShell)
Remove-Item -Recurse -Force build, dist, *.egg-info -ErrorAction SilentlyContinue

# Linux/Mac
rm -rf build dist *.egg-info

PASO 3: Construir el Paquete
-----------------------------
python -m build

Esto creará:
- dist/haka_playwright_engine-1.3.17.tar.gz (source distribution)
- dist/haka_playwright_engine-1.3.17-py3-none-any.whl (wheel)

PASO 4: Verificar el Paquete
-----------------------------
python -m twine check dist/*

Debe mostrar:
✅ Checking dist/haka_playwright_engine-1.3.17.tar.gz: PASSED
✅ Checking dist/haka_playwright_engine-1.3.17-py3-none-any.whl: PASSED

PASO 5: Probar en TestPyPI (Opcional pero Recomendado)
-------------------------------------------------------
python -m twine upload --repository testpypi dist/*

Username: __token__
Password: [tu token de TestPyPI]

Luego prueba la instalación:
pip install --index-url https://test.pypi.org/simple/ haka-playwright-engine==1.3.17

PASO 6: Publicar en PyPI (PRODUCCIÓN)
--------------------------------------
⚠️ ADVERTENCIA: Esta es la subida FINAL. No se puede eliminar después.

python -m twine upload dist/*

Username: __token__
Password: [tu token de PyPI]

PASO 7: Verificar Publicación
------------------------------
1. Ve a: https://pypi.org/project/haka-playwright-engine/
2. Verifica que la versión 1.3.17 aparezca
3. Verifica que la descripción se vea correctamente
4. Verifica que los enlaces funcionen

PASO 8: Probar Instalación
---------------------------
# En un entorno limpio
pip install haka-playwright-engine==1.3.17

# O actualizar
pip install --upgrade haka-playwright-engine

===========================================
CONFIGURACIÓN DE .pypirc (YA CONFIGURADO)
===========================================

✅ Tu archivo .pypirc ya está configurado en:
   C:\Users\felipefarias\.pypirc

✅ Configuración actual:
   - Repositorio: haka-playwright-engine
   - URL: https://upload.pypi.org/legacy/
   - Token: Configurado correctamente

El script de publicación usará automáticamente esta configuración.
No necesitas ingresar credenciales manualmente.

===========================================
TROUBLESHOOTING
===========================================

ERROR: "Invalid or non-existent authentication information"
------------------------------------------------------------
Solución:
- Verifica que estás usando __token__ como username
- Verifica que el token es correcto y no ha expirado
- Verifica que el token tiene los permisos correctos

ERROR: "File already exists"
-----------------------------
Solución:
- No puedes subir la misma versión dos veces
- Incrementa la versión (ej: 1.3.1) y vuelve a intentar
- O usa --skip-existing (no recomendado)

ERROR: "Invalid distribution file"
-----------------------------------
Solución:
- Ejecuta: python -m twine check dist/*
- Verifica que README.md existe y está bien formateado
- Verifica que setup.py y pyproject.toml son válidos

ERROR: "Package name already taken"
------------------------------------
Solución:
- El nombre "haka-playwright-engine" es el nuevo nombre del proyecto
- Si es la primera vez, verifica que tienes permisos
- Si no eres el dueño, usa otro nombre

ERROR: Build falla
-------------------
Solución:
- Verifica que requirements.txt existe
- Verifica que todos los archivos necesarios existen
- Ejecuta: pip install --upgrade build setuptools wheel

===========================================
DESPUÉS DE PUBLICAR
===========================================

1. CREAR TAG EN GIT
-------------------
git tag -a v1.3.17 -m "Release version 1.3.17"
git push origin v1.3.17

2. CREAR RELEASE EN GITHUB
---------------------------
1. Ve a: https://github.com/pipefariashaka/haka-playwright-engine/releases
2. Click en "Create a new release"
3. Tag: v1.3.17
4. Title: "Haka Playwright Engine v1.3.17"
5. Descripción: Copia el contenido de CHANGELOG.md para v1.3.17
6. Adjunta los archivos de dist/ (opcional)
7. Click en "Publish release"

3. ACTUALIZAR DOCUMENTACIÓN
----------------------------
✅ Actualiza README.md con instrucciones de instalación
✅ Actualiza badges de versión
✅ Actualiza enlaces a PyPI

4. ANUNCIAR EL RELEASE
-----------------------
✅ Twitter/X
✅ LinkedIn
✅ Blog de la empresa
✅ Newsletter
✅ Comunidades de Python/Testing

===========================================
CHECKLIST FINAL
===========================================

Antes de publicar, verifica:

[ ] Versión 1.3.17 en setup.py
[ ] Versión 1.3.17 en pyproject.toml
[ ] CHANGELOG.md actualizado
[ ] README.md actualizado
[ ] requirements.txt actualizado
[ ] Todos los tests pasan
[ ] Documentación completa
[ ] Ejemplos funcionan
[ ] MANIFEST.in incluye todos los archivos necesarios
[ ] Token de PyPI listo
[ ] Build exitoso (python -m build)
[ ] Verificación exitosa (twine check)
[ ] Probado en TestPyPI (opcional)

===========================================
COMANDOS RÁPIDOS
===========================================

# Limpiar
rm -rf build dist *.egg-info

# Construir
python -m build

# Verificar
python -m twine check dist/*

# Subir a TestPyPI
python -m twine upload --repository testpypi dist/*

# Subir a PyPI
python -m twine upload dist/*

# Instalar desde PyPI
pip install haka-playwright-engine==1.3.17

# Actualizar
pip install --upgrade haka-playwright-engine

===========================================
RECURSOS ADICIONALES
===========================================

Documentación Oficial:
- PyPI: https://pypi.org/help/
- Packaging: https://packaging.python.org/
- Twine: https://twine.readthedocs.io/
- Build: https://build.pypa.io/

Tutoriales:
- https://packaging.python.org/tutorials/packaging-projects/
- https://realpython.com/pypi-publish-python-package/

Soporte:
- PyPI Support: https://pypi.org/help/#support
- GitHub Issues: https://github.com/pypa/packaging-problems/issues

===========================================
FIN DE LA GUÍA
===========================================

Versión: 1.3.17
Última actualización: 2026-03-02

¡Buena suerte con la publicación! 🚀
