O que você vai aprender#
- quando uma versão é publicada e como é numerada;
- os passos de um branch de versão até uma versão verificada;
- a regra de que uma tag publicada nunca é movida.
A ideia#
As versões seguem o Versionamento Semântico e o Conventional Commits. Antes da 1.0.0, uma versão menor (v0.N.0) adiciona recursos e pode mudar uma interface pública, e uma versão de correção (v0.N.1) apenas corrige bugs. Uma versão menor é publicada a cada cerca de 90 commits no main, e sempre no fim de uma fase (Protótipo, ALPHA, BETA).
Um pull request carrega uma versão. O seu branch, release/vX.Y.Z, reúne o trabalho da versão como commits pequenos e autocontidos, cada um um Conventional Commit com um cabeçalho de no máximo 100 caracteres. O pull request se chama chore(release): vX.Y.Z updates e é integrado com rebase, então cada commit chega ao main como está e vira uma entrada do changelog. O main é protegido: ninguém faz commit nem push direto nele, e uma mudança só chega a ele por um pull request cujas verificações obrigatórias estão verdes e que está atualizado com o main.
O changelog e as notas da versão são gerados a partir dos commits e têm apenas cinco seções: Added (feat), Changed (uma mudança incompatível de uma interface pública), Removed, Fixed (fix) e Security. Os rodapés (BREAKING CHANGE:, Security:, Translation: not-needed) vão no commit que carrega a mudança.
Os passos#
- Confirme a versão. O mantenedor aprova
vX.Y.Z; a tag é o único passo que precisa de um sim humano. - Portão no branch. As verificações obrigatórias estão verdes na ponta de
release/vX.Y.Z, nenhuma issue com o rótuloci-failureestá aberta, e o portão localtask release:preflightpassa. - Atualize o corpo do pull request com os commits:
task release:pr-body -- vX.Y.Z. Ele lista as cinco seções com um hash com link por entrada. - Prepare o changelog:
task release:prepare -- vX.Y.Zno branch de versão grava a seção doCHANGELOG.mda partir dos commits e faz o commitchore(release): vX.Y.Z. - Atualize as datas da documentação:
npm run last-updatedemsite/, para que cada página mostre a sua data real. - Integre o pull request com rebase quando as verificações estiverem verdes.
- Tag. No
main, avançado até a ponta integrada,task release:tag -- vX.Y.Zconfere que a ponta é o commit da versão, cria a tag anotada e a envia: uma tag por push. - Publique. A tag inicia o
release.yml. Ele cria a versão no GitHub com a seção do changelog como corpo (um corpo vazio falha), constrói os seis arquivos compactados com os seus SBOMs, assina ochecksums.txtcom o cosign, atesta a proveniência da construção e publica a imagem no GHCR e no Docker Hub com as tagsX.Y.Z,X.Yelatest, assinando e atestando os seus digests. - Verifique em até 15 minutos com os comandos de Verifique uma versão, ou
task release:verify -- vX.Y.Z.
Se o push não iniciou nenhuma execução: gh workflow run release.yml -f version=vX.Y.Z. Se o workflow falhou no meio: gh run rerun <id> --failed. Todo job é idempotente.
A regra da tag#
Uma tag publicada nunca é movida, excluída nem reutilizada. Se uma versão está errada, a correção é a próxima versão de correção. Uma execução de recuperação iniciada à mão assina com a identidade de um branch em vez de uma tag, o que a verificação rejeita de propósito: não a afrouxe.
Erros comuns#
- Um cabeçalho de commit com mais de 100 caracteres, ou um tipo ou escopo que a verificação de commits não conhece: o job de commits falha e o cabeçalho precisa ser reescrito antes da integração.
- Uma versão sem uma seção do changelog: o workflow recusa um corpo vazio.
- Enviar para o
main, ou fazer um push forçado em um branch compartilhado. - Usar uma tag mutável para uma imagem: publique e execute o
X.Y.Zfixo.