> ## 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

> Semver, identità di build, changelog e regole di tagging delle release per il repository.

# Versionamento

Switchbord utilizza treni di release semver deliberati, non una numerazione basata sul conteggio dei commit o "una PR, una versione".

## Due concetti di versione

### Versione di release

La versione nel `package.json` radice è la versione di release del repository.

Va usata per:

* release intenzionali
* corrispondenza con i tag semver
* cronologia delle release leggibile dagli esseri umani
* il changelog pubblico
* le GitHub Release

### Versione di build

`buildVersion` è l'identità di deployment a runtime.

Va usata per:

* il reporting di `/health` e `/ready`
* ricondurre un artefatto distribuito a un commit
* distinguere due deployment con la stessa release semver

## Politica attuale

La linea di release attuale è `0.12.x`.

Fino all'alpha, utilizzare il semver a treni di release:

* **patch** per correzioni di bug, correzioni di contratto, correzioni alla documentazione e igiene delle release
* **minor** per ondate coerenti di funzionalità come Campaigns v1, il runtime dei WhatsApp Flows, la prontezza per l'alpha o un'importante fetta di integrazione
* **major** solo quando il progetto è sufficientemente stabile per la semantica di `1.0.0`

Non generare una versione minor per ogni PR. Le PR sono l'unità di consegna; le versioni semver sono la narrazione curata delle release.

## Invarianti della release

Ogni release deve soddisfare tutte le seguenti condizioni:

1. Il `package.json` radice contiene la versione semver prevista.
2. Il `CHANGELOG.md` radice contiene `## vX.Y.Z` per quella stessa versione.
3. Se esiste una voce di changelog web pubblico in `apps/web/content/changelog/vX.Y.Z.mdx`, il suo frontmatter `version` corrisponde al nome del file e la sua data è una data reale di merge/commit.
4. Il tag Git deve corrispondere esattamente al momento della release: `package.json` `0.12.1` ↔ tag `v0.12.1`.
5. Le note della GitHub Release vengono generate dal tag semver corrispondente.

Le normali PR di feature/fix successive a una release non devono necessariamente incrementare `package.json`, a meno che non intendano deliberatamente inaugurare un nuovo treno di release. Devono comunque aggiornare la documentazione/changelog quando il comportamento cambia.

## Retro-datazione dei tag

Lo stato storico attuale è imperfetto: la prima fase alpha si è mossa più velocemente della disciplina di release. Solo `v0.0.1` è stato taggato mentre `package.json` è successivamente avanzato a `0.12.1`.

Prima dell'alpha ci sono due opzioni accettabili:

* **Preferita:** iniziare la corrispondenza rigorosa al prossimo treno di release coerente, ad es. `v0.13.0`, e trattare le sezioni più vecchie del changelog come ricostruzione storica.
* **Opzionale:** retro-datare i tag mancanti solo quando il commit esatto della release è noto e stabile. Non creare tag storici basandosi su congetture.

## Comandi di supporto

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

`release:hygiene` verifica che `package.json`, `CHANGELOG.md`, le voci del changelog web pubblico e qualsiasi tag corrispondente esistente siano coerenti.

## Regola per la stesura delle PR

Se una PR modifica un comportamento visibile all'utente, i contratti API, la documentazione per gli operatori, i flussi di setup o il comportamento di deployment/runtime, deve aggiornare almeno uno tra:

* `CHANGELOG.md`
* `apps/web/content/changelog/*.mdx`
* `apps/docs/**`
* `planning/**` per note intenzionalmente interne/solo per operatori

Se non è necessario alcun aggiornamento della documentazione/changelog, spiegare il perché nel corpo della PR.

## Prosegui la lettura

* [Processo di release](/it/contributing/release-process)
* [CI/CD](/it/operations/cicd)