Versionamento
O Switchbord usa trens de release semver deliberados, e não uma numeração baseada em contagem de commits ou um-PR-uma-versão.Dois conceitos de versão
Versão de release
A versão dopackage.json raiz é a versão de release do repositório.
Use-a para:
- releases intencionais
- correspondência com tags semver
- histórico de release legível por humanos
- o changelog público
- GitHub Releases
Versão de build
buildVersion é a identidade de deployment em runtime.
Use-a para:
- relatórios de
/healthe/ready - rastrear um artefato implantado até um commit
- distinguir dois deployments com a mesma release semver
Política atual
A linha de release atual é0.12.x.
Até a fase alpha, use semver de trem de release:
- patch para correções de bugs, correções de contrato, correções de documentação e higiene de release
- minor para ondas coerentes de capacidade, como Campaigns v1, runtime de WhatsApp Flows, preparação para alpha, ou uma fatia importante de integração
- major apenas quando o projeto estiver estável o suficiente para a semântica de
1.0.0
Invariantes de release
Todo release deve satisfazer todos os itens abaixo:- O
package.jsonraiz contém a versão semver pretendida. - O
CHANGELOG.mdraiz contém## vX.Y.Zpara essa mesma versão. - Se existir uma entrada de changelog público na web em
apps/web/content/changelog/vX.Y.Z.mdx, seu frontmatterversioné igual ao nome do arquivo e sua data é uma data real de merge/commit. - A tag do Git deve corresponder exatamente no momento do release:
package.json0.12.1↔ tagv0.12.1. - As notas do GitHub Release são geradas a partir da tag semver correspondente.
package.json, a menos que intencionalmente iniciem um novo trem de release. Eles precisam de atualizações de docs/changelog quando o comportamento muda.
Marcação retroativa de tags (back-minting)
O estado histórico atual é imperfeito: a fase alpha inicial avançou mais rápido do que a disciplina de release. Apenasv0.0.1 foi marcada com tag enquanto o package.json avançou posteriormente para 0.12.1.
Antes da fase alpha, existem duas opções aceitáveis:
- Preferencial: iniciar a correspondência estrita no próximo trem de release coerente, por exemplo
v0.13.0, e tratar seções antigas do changelog como reconstrução histórica. - Opcional: criar retroativamente tags ausentes apenas quando o commit exato do release for conhecido e estável. Não crie tags históricas por suposição.
Comandos auxiliares
release:hygiene verifica se package.json, CHANGELOG.md, as entradas públicas do changelog na web e qualquer tag correspondente existente estão coerentes.
Regra de autoria de PR
Se um PR altera comportamento visível ao usuário, contratos de API, documentação de operadores, fluxos de configuração, ou comportamento de deployment/runtime, ele deve atualizar pelo menos um dos seguintes:CHANGELOG.mdapps/web/content/changelog/*.mdxapps/docs/**planning/**para notas intencionalmente internas/apenas para operadores