Pular para o conteúdo principal

Versões e canal de pré-lançamento

Como o Canopy versiona, etiqueta e publica imagens de contentor. Esta página é a referência para os operadores que precisam de fixar versões em produção e para os contribuidores que preparam versões.

Versionamento​

O Canopy segue o Semantic Versioning. A fonte única de verdade para a versão atual é o ficheiro /VERSION na raiz do repositório.

  • Correção (por exemplo, 1.0.0 → 1.0.1): apenas correções de erros. Sempre seguro de atualizar.
  • Menor (por exemplo, 1.0.0 → 1.1.0): novas funcionalidades. Retrocompatível de acordo com a política de compatibilidade.
  • Principal (por exemplo, 1.x → 2.0.0): alterações de ruptura. As notas de migração são publicadas com a versão.

A versão é incrementada uma vez por PR, não por commit. A entrada no CHANGELOG do PR usa a nova versão como cabeçalho; o version-check.yml de CI rejeita qualquer PR que incremente VERSION sem um cabeçalho ## [<version>] correspondente em CHANGELOG.md.

Etiquetas das imagens de contentor​

Cada push para main e cada etiqueta v*.*.* aciona .github/workflows/docker-publish.yml, que compila e publica imagens multi-arquitetura (amd64 + arm64) no GHCR.

Para uma etiqueta de versão como v1.2.3, as etiquetas publicadas em cada imagem são:

EtiquetaAponta paraEstável?
1.2.3exatamente essa versãosim — fixe esta em produção
1.2correção mais recente em 1.2.xavança com correções
1versão menor mais recente em 1.xavança com versões menores
latestversão não pré-lançamento mais recenteavança com cada versão
sha-<short>commit exatosim — depuração / pré-lançamento

Para pushes para main (sem etiqueta), apenas as etiquetas main e sha-<short> são produzidas — nunca latest, nunca nenhuma etiqueta semver.

Todos os manifestos de imagem publicados são assinados com cosign sem chave OIDC. Os detalhes de verificação e SBOM estão em Cadeia de Fornecimento.

Canal de pré-lançamento​

Para versões menores que alteram a disposição do contentor, imagens base, UIDs predefinidos, nomes de volumes, portas predefinidas ou esquema de uma forma que requer ação do operador, é criado um candidato a lançamento antes da etiqueta final.

Convenções:

  • As etiquetas RC são vX.Y.0-rc.N — nunca numa versão de correção, apenas em versões menores com alterações visíveis pelo operador.
  • A docker/metadata-action do fluxo de publicação está configurada com flavor: latest=auto. Isto exclui automaticamente as etiquetas semver de pré-lançamento de :latest, :X.Y e :X — os RCs são publicados apenas como :X.Y.0-rc.N. Os operadores que fixem em :latest não puxarão acidentalmente um RC.
  • A versão do GitHub para uma etiqueta RC deve ser marcada como pré-lançamento na página de Versões. O fluxo atual github-release.yml cria sempre uma versão não pré-lançamento; o mantenedor activa manualmente a alternância de pré-lançamento após o fluxo ser executado (ou edita a versão via gh release edit vX.Y.0-rc.N --prerelease).

Período de maturação:

  • Um RC permanece disponível durante pelo menos 48 a 72 horas antes da promoção, ou até pelo menos um operador fora do mantenedor reportar uma atualização bem-sucedida — o que for mais longo.
  • Os relatórios de erros contra um RC são publicados como vX.Y.0-rc.N+1 se o problema merecer correção. O RC anterior é mantido no GHCR para reprodutibilidade.

Promoção para final:

  • A etiqueta final vX.Y.0 é criada no mesmo commit que o último RC. O fluxo de publicação reconstrói e reaplica etiquetas às imagens multi-arquitetura; o digest diferirá do RC mesmo que o código-fonte seja idêntico (as entradas de compilação incluem timestamps).
  • As etiquetas :X.Y, :X e :latest passam a apontar para a versão final neste momento.

Preparar uma versão (lista de verificação do mantenedor)​

Para uma correção ou versão menor normal — sem necessidade do canal RC:

  1. Num branch de funcionalidade, incremente VERSION e adicione o cabeçalho ## [<version>] - YYYY-MM-DD correspondente ao CHANGELOG.md.
  2. Execute python scripts/dump_openapi.py se alguma rota ou esquema do backend tiver mudado; faça commit do resultado se este tiver mudado.
  3. Abra o PR. O CI executa lint, testes, verificação de desvio OpenAPI e version-check.yml.
  4. Faça squash-merge para main.
  5. A partir de main: git tag -s v<version> -m "v<version>" (ou git tag v<version> se não houver chave de assinatura configurada), git push origin v<version>.
  6. O fluxo Publish GitHub Release extrai a secção ## [<version>] do CHANGELOG.md e cria uma versão no GitHub.
  7. O fluxo Publish Docker images to GHCR compila, assina e publica as imagens multi-arquitetura.
  8. Verifique com cosign: 
    cosign verify \
      --certificate-identity-regexp 'https://github.com/Rhizo-Tech/canopy/.+' \
      --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
      ghcr.io/rhizo-tech/canopy/backend:<version>

Para uma versão menor que justifique um RC:

  1. O mesmo fluxo PR-e-merge que acima, mas incremente para 1.Y.0-rc.1.
  2. Após o merge, aplique a etiqueta v1.Y.0-rc.1 e faça push. O fluxo de publicação compila e publica as imagens RC (apenas :1.Y.0-rc.1, nunca :latest nem etiquetas curtas — flavor: latest=auto trata disso). O fluxo de versão cria uma versão no GitHub; ative manualmente o pré-lançamento depois via gh release edit v1.Y.0-rc.1 --prerelease ou na interface do GitHub.
  3. Aguarde o período de maturação. Resolva quaisquer problemas reportados com -rc.2, -rc.3 conforme necessário.
  4. Para promover: incremente VERSION para 1.Y.0 num PR final (a entrada do CHANGELOG consolida todas as correções do RC), faça merge, aplique a etiqueta v1.Y.0, faça push. As etiquetas :latest e as etiquetas curtas passam a apontar para a versão promovida.

Fim de vida​

Apenas a linha de versão menor mais recente recebe correções de segurança. Consulte SECURITY.md para a política completa. As linhas menores mais antigas estão em fim de vida e não receberão backports — os operadores em versões mais antigas devem planear atualizações de acordo com a política de compatibilidade.