Política de engenharia de lançamento

Cinco políticas regem como o apothem é lançado.

1. Versionamento semânticoCopy Anchor Link

O projeto é distribuído sob o Versionamento Semântico 2.0. Os números de versão assumem a forma MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD].

As tags candidatas usam o formato vX.Y.Z-rc.N (candidata a lançamento) ou vX.Y.Z-alpha.N / vX.Y.Z-beta.N (acesso antecipado).

2. Tags de lançamentoCopy Anchor Link

Todo lançamento aplica em main uma tag git assinada da forma vMAJOR.MINOR.PATCH. A tag dispara o .github/workflows/release.yml, que compila, assina, gera o SBOM e a procedência SLSA-3, e publica a página do GitHub Release.

Convenções de tags:

• Formato — exatamente vMAJOR.MINOR.PATCH. Sem prefixo release-, sem sufixo -final.
• Anotação — toda tag é uma tag anotada (git tag -a -s) que carrega o resumo das notas de lançamento na mensagem da tag.
• Assinatura — toda tag é assinada com GPG. O fluxo de trabalho de lançamento também produz uma assinatura cosign sem chave do Sigstore para cada artefato e um registro de procedência SLSA-3, ambos anexados à página do GitHub Release.

Modelo de lançamento: aditivoCopy Anchor Link

Os lançamentos são aditivos. Cada lançamento adiciona um commit em main e uma tag; main nunca recebe force-push, e nenhuma tag, GitHub Release ou versão do npm publicada é excluída, movida ou reutilizada. Cada lançamento mantém sua tag, seu GitHub Release e sua versão do npm, e todos permanecem publicados. As versões do npm são imutáveis: um name@version publicado nunca pode ser substituído, e um número despublicado nunca pode ser usado novamente. As instalações fixadas e os builds reproduzíveis dependem de cada tag publicada. Os runbooks de ciclo de lançamento e de recuperação de lançamento seguem ambos este modelo.

A regra de fachada de lançamento do repositório (a seção Release Facade das instruções para contribuidores) estabelece este modelo. Seu requisito de apenas a versão atual, espelhado na regra freshness-facade, abrange o que as superfícies públicas afirmam. Ele não limita quais lançamentos permanecem publicados.

3. Política de descontinuaçãoCopy Anchor Link

A linha de suporte público atual é a versão menor mais recente lançada. Quando o projeto tem várias versões menores públicas, a matriz de versões suportadas do SECURITY.md é a fonte de verdade para quaisquer janelas adicionais de suporte somente para correções críticas.

Cadência de descontinuação:

• Anúncio — um símbolo ou comportamento descontinuado é anunciado na seção ### Deprecated do CHANGELOG.md do lançamento em que a descontinuação ocorre. As notas de lançamento espelham o anúncio de descontinuação.
• Janela de tolerância — os símbolos descontinuados permanecem disponíveis por no mínimo um ciclo menor completo antes da remoção.
• Remoção — a remoção ocorre em um incremento MAJOR. Cada símbolo removido carrega uma linha ### Removed no CHANGELOG.md e uma entrada de guia de migração em Guias práticos.

Pisos de runtimeCopy Anchor Link

O Apothem declara dois pisos de runtime: requires-python = ">=3.10" em pyproject.toml e "engines": {"node": ">=18"} em package.json.

• Todo piso declarado é testado. O piso do Python é executado na matriz quality do CI e no fluxo de trabalho CI Matrix. O fluxo de trabalho npm Shim executa o shim do npm no piso do Node e em cada versão major LTS posterior: ele verifica o erro de pré-requisito ausente, node bin/apothem.mjs --version, uma instalação em modo dry-run em um diretório home isolado e o tarball empacotado via npx. Um runtime que não é testado não é declarado.
• O fim de vida é divulgado. Quando um runtime que ainda é um piso declarado chega ao fim de vida upstream, o guia de instalação informa isso e nomeia as versões a preferir. O Python 3.10 chegou ao fim de vida em 2026-10-01; o Node.js 18 e o 20, em 2025-04-30 e 2026-04-30. Os três continuam sendo pisos suportados.
• Elevar um piso é uma descontinuação. Isso segue a cadência acima: um anúncio em ### Deprecated, pelo menos um ciclo menor completo no qual o piso antigo continua sendo testado, e então o lançamento que o eleva registra a mudança. requires-python, engines.node, as sondagens de versão dos instaladores e as matrizes de CI mudam juntos nesse lançamento.

4. Política de mudanças incompatíveisCopy Anchor Link

Mudanças incompatíveis exigem:

1. Uma issue de RFC — aberta com o rótulo de issue rfcs, descrevendo a mudança incompatível, o caminho de migração e a estratégia de reversão.
2. Uma janela de comentários de 30 dias — a RFC permanece aberta por pelo menos 30 dias antes do merge. Os mantenedores podem estender a janela quando o feedback justificar.
3. Um incremento MAJOR — o lançamento que aplica a mudança incompatível incrementa o componente MAJOR.
4. Um guia de migração — a mudança é entregue com uma entrada em Guias práticos que orienta o operador na migração.

5. Política de reversãoCopy Anchor Link

Se um lançamento apresentar uma regressão que bloqueia a adoção:

1. Reverter — o(s) commit(s) problemático(s) é(são) revertido(s) em main.
2. Lançamento de correção para frente — um lançamento subsequente é feito como vMAJOR.MINOR.PATCH+1, carregando a reversão mais quaisquer correções incrementais. O lançamento defeituoso anterior não é excluído do GitHub Releases, e sua versão do npm permanece publicada (as versões do npm são imutáveis) e é marcada com npm deprecate. Uma anotação ### Yanked no CHANGELOG.md documenta a situação para que os builds reproduzíveis permaneçam ancorados.
3. Comunicação — um aviso de security-advisories (quando for relevante para a segurança) ou uma issue do GitHub fixada para o incidente (quando for relevante para a confiabilidade) acompanha a reversão.

Veja tambémCopy Anchor Link

• CHANGELOG.md — o registro canônico de lançamentos.
• SECURITY.md — a matriz de versões suportadas e os canais de relato.
• cicd-pipeline.md — as classes de verificação de CI que protegem cada lançamento.
• deployment-checklist.md — a varredura de prontidão para produção por lançamento.