Gentleman-Programming/release

Quando Usar

Use esta skill ao preparar, publicar ou verificar um lançamento do gentle-pi.

Regras Rígidas

• Não publique gentle-pi no npm a partir de uma máquina local.
• A publicação no npm DEVE passar pelo workflow do GitHub Actions .github/workflows/publish.yml para que proveniência, proteção de ambiente e credenciais de registro sejam controladas pelo GitHub.
• Despache a definição confiável do workflow a partir do main padrão protegido, nunca de uma tag de release. Sua única entrada é a tag de versão anotada exata.
• Use uma árvore de trabalho limpa para commits de release. Não empacote arquivos locais não relacionados ou artefatos temporários.
• Os resultados da revisão são informativos. A entrega do release segue a política comum do repositório e não deve ser bloqueada, autorizada ou reescrita por RDD.
• Nunca infira o alvo da tag de release a partir do HEAD local; use o commit recém-buscado de origin/main e as proteções normais de release do repositório.
• Nunca pule a verificação do pacote. O workflow de publicação executa a verificação novamente, mas a validação local ainda deve passar antes da criação da tag.

Procedimento de Release

1. Inspecione o estado

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

2. Prepare o commit de release

   • Aplique apenas as alterações pretendidas.
   • Atualize a versão no package.json para a próxima versão semântica.
   • Mantenha alterações no lockfile fora, a menos que a resolução de dependências realmente tenha mudado.

3. Verifique localmente

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

   npm pack --dry-run verifica o conteúdo do pacote e scripts de ciclo de vida sem entrar em um caminho de publicação.

4. Faça commit e push

   git add <arquivos-pretendidos>
   git commit -m "<tipo(escopo): alteração pronta para release>"
   git push origin HEAD:main
   git fetch origin main --tags
   

5. Crie e verifique a tag de versão exata

   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 do release>"
   

   Não recrie a tag ou sobrescreva uma versão existente. O alvo da tag vem do commit recém-buscado e imutável de origin/main, não de um branch local ambiente.

6. Publique npm via 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}"
   

   A definição do workflow sempre vem do main padrão protegido. Ela aceita apenas uma tag vSemVer exata, busca a tag anotada remota e o main remoto atual, e exige que o commit da tag, o commit do workflow de despacho, o checkout e a versão do package.json coincidam. Ela consulta novamente a tag remota e o main imediatamente antes da publicação npm, deriva a dist-tag internamente e usa OIDC confiável com proveniência.

   Acompanhe a execução e falhe o release se falhar:

   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. Verifique no npm

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

Tratamento de Falhas

• Uma falha de publicação é tratada através da política comum do repositório. Ela não reabre ou altera uma linhagem de revisão.

• Nunca tente ou repita npm publish localmente. Redespache a partir do main confiável somente quando a mesma tag ainda apontar para o main remoto atual e a falha foi exclusivamente de publicação.

• Se o main remoto avançar, não mova ou recrie a tag existente. Prepare um novo commit/versão de release e crie uma nova tag de versão anotada.

• Se o workflow falhar, inspecione os logs com:

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

• Se a verificação npm estiver temporariamente desatualizada após um workflow bem-sucedido, verifique a versão exata primeiro (npm view gentle-pi@<version> version) antes de assumir que a publicação falhou.

Contrato de Saída

Relate:

• SHA do commit enviado para main.
• Tag de versão exata e seu SHA de commit.
• URL do release no GitHub.
• URL da execução do workflow de publicação e conclusão.
• Versão exata no npm e a dist-tag derivada do workflow (latest, beta ou next).
• Quaisquer acompanhamentos ou avisos restantes.