Gentleman-Programming/release

Cuándo Usarla

Usa esta habilidad al preparar, publicar o verificar un lanzamiento de gentle-pi.

Reglas Estrictas

• No publiques gentle-pi en npm desde una máquina local.
• La publicación en npm DEBE realizarse a través del flujo de trabajo de GitHub Actions .github/workflows/publish.yml para que la proveniencia, la protección del entorno y las credenciales del registro sean controladas por GitHub.
• Despacha la definición del flujo de trabajo confiable desde la rama protegida por defecto main, nunca desde un tag de lanzamiento. Su única entrada del invocador es el tag de versión anotado exacto.
• Usa un árbol de trabajo limpio para los commits de lanzamiento. No empaquetes archivos locales no relacionados o artefactos de trabajo sueltos.
• Los resultados de la revisión son informativos. La entrega del lanzamiento sigue la política ordinaria del repositorio y no debe ser bloqueada, autorizada ni reescrita por RDD.
• Nunca infieras el objetivo del tag de lanzamiento desde el HEAD local; usa el commit recién obtenido de origin/main y las salvaguardas normales del repositorio.
• Nunca omitas la verificación del paquete. El flujo de trabajo de publicación ejecuta la verificación nuevamente, pero la validación local aún debe pasar antes del etiquetado.

Procedimiento de Lanzamiento

1. Inspeccionar el estado

   git status --short
   git fetch origin main --tags
   git log --oneline --decorate --max-count=5 origin/main
   

2. Preparar el commit de lanzamiento

   • Aplica solo los cambios previstos.
   • Actualiza package.json a la siguiente versión semver.
   • Mantén los cambios del archivo de bloqueo fuera a menos que la resolución de dependencias realmente haya cambiado.

3. Verificar localmente

   pnpm test
   node scripts/verify-package-files.mjs
   npm pack --dry-run
   

   npm pack --dry-run verifica el contenido del paquete y los scripts del ciclo de vida sin entrar en la ruta de publicación.

4. Hacer commit y push

   git add <archivos-previstos>
   git commit -m "<tipo(ámbito): cambio listo para lanzamiento>"
   git push origin HEAD:main
   git fetch origin main --tags
   

5. Crear y verificar el tag de versión exacta

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   release_sha="$(git rev-parse 'origin/main^{commit}')"
   
   test "$(git rev-parse 'HEAD^{commit}')" = "${release_sha}"
   test -z "$(git ls-remote --tags origin "refs/tags/${tag}")"
   
   git tag -a "${tag}" "${release_sha}" -m "gentle-pi ${tag}"
   test "$(git rev-parse "${tag}^{commit}")" = "${release_sha}"
   
   git fetch origin main
   test "$(git rev-parse 'origin/main^{commit}')" = "${release_sha}"
   git push origin "refs/tags/${tag}"
   
   git fetch --no-tags origin "refs/tags/${tag}"
   test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "${release_sha}"
   
   gh release create "${tag}" \
     --repo Gentleman-Programming/gentle-pi \
     --verify-tag \
     --title "gentle-pi ${tag}" \
     --notes "<notas del lanzamiento>"
   

   No reetiquetes ni sobrescribas una versión existente. El objetivo del tag proviene del commit inmutable origin/main recién obtenido, no de una rama local del entorno.

6. Publicar npm a través de GitHub Actions

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   gh workflow run publish.yml \
     --repo Gentleman-Programming/gentle-pi \
     --ref main \
     -f tag="${tag}"
   

   La definición del flujo de trabajo siempre proviene de main protegido por defecto. Acepta solo un tag vSemVer exacto, obtiene el tag anotado remoto y el main remoto actual, y requiere que el commit del tag desglosado, el commit del flujo de trabajo al despachar, el checkout y la versión de package.json coincidan. Vuelve a consultar el tag remoto y main inmediatamente antes de la publicación en npm, deriva la etiqueta de distribución internamente y usa OIDC confiable con proveniencia.

   Observa la ejecución y falla el lanzamiento si falla:

   gh run list --repo Gentleman-Programming/gentle-pi --workflow publish.yml --limit 3
   gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
   

7. Verificar npm

   npm view gentle-pi@<versión> version --registry=https://registry.npmjs.org/
   npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
   

Manejo de Fallos

• Un fallo de publicación se maneja a través de la política ordinaria del repositorio. No reabre ni altera una línea de revisión.

• Nunca intentes ni reintentes npm publish localmente. Redespacha desde main confiable solo cuando el mismo tag aún apunte al main remoto actual y el fallo haya sido únicamente de publicación.

• Si main remoto avanza, no muevas ni recrees el tag existente. Prepara un nuevo commit/versión de lanzamiento y crea un nuevo tag de versión anotado.

• Si el flujo de trabajo falla, inspecciona los registros con:

  gh run view <run-id> --repo Gentleman-Programming/gentle-pi --log
  

• Si la verificación de npm está brevemente desactualizada después de un flujo de trabajo exitoso, verifica primero la versión exacta (npm view gentle-pi@<versión> version) antes de asumir que la publicación falló.

Contrato de Salida

Reporta:

• SHA del commit enviado a main.
• Tag de versión exacta y su SHA de commit desglosado.
• URL del lanzamiento en GitHub.
• URL de ejecución del flujo de trabajo de publicación y su conclusión.
• Versión exacta de npm y la etiqueta de distribución derivada del flujo de trabajo (latest, beta o next).
• Cualquier seguimiento o advertencia restante.