> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versionamento

> Regras de semver, identidade de build, changelog e marcação de releases para o repositório.

# 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 do `package.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 `/health` e `/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`

Não crie uma versão minor para cada PR. PRs são a unidade de entrega; versões semver são a narrativa curada de releases.

## Invariantes de release

Todo release deve satisfazer todos os itens abaixo:

1. O `package.json` raiz contém a versão semver pretendida.
2. O `CHANGELOG.md` raiz contém `## vX.Y.Z` para essa mesma versão.
3. Se existir uma entrada de changelog público na web em `apps/web/content/changelog/vX.Y.Z.mdx`, seu frontmatter `version` é igual ao nome do arquivo e sua data é uma data real de merge/commit.
4. A tag do Git deve corresponder exatamente no momento do release: `package.json` `0.12.1` ↔ tag `v0.12.1`.
5. As notas do GitHub Release são geradas a partir da tag semver correspondente.

PRs normais de feature/correção após um release não precisam incrementar o `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. Apenas `v0.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

```bash theme={null}
pnpm release:hygiene
pnpm release:tag
pnpm release:tag:push
```

`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.md`
* `apps/web/content/changelog/*.mdx`
* `apps/docs/**`
* `planning/**` para notas intencionalmente internas/apenas para operadores

Se nenhuma atualização de docs/changelog for necessária, explique o motivo no corpo do PR.

## Leia a seguir

* [Processo de Release](/pt-BR/contributing/release-process)
* [CI/CD](/pt-BR/operations/cicd)