Skip to main content

​
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

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