Skip to main content

​
Versioning

Switchbord uses deliberate semver release trains, not commit-count or one-PR-one-version numbering.

​
Two version concepts

​
Release version

The root package.json version is the repository release version. Use it for:
  • intentional releases
  • matching semver tags
  • human-readable release history
  • the public changelog
  • GitHub Releases

​
Build version

buildVersion is the runtime deployment identity. Use it for:
  • /health and /ready reporting
  • tracing a deployed artifact back to a commit
  • distinguishing two deployments with the same semver release

​
Current policy

The current release line is 0.12.x. Until alpha, use release-train semver:
  • patch for bug fixes, contract corrections, docs corrections, and release hygiene
  • minor for coherent capability waves such as Campaigns v1, WhatsApp Flows runtime, alpha readiness, or a major integration slice
  • major only when the project is stable enough for 1.0.0 semantics
Do not mint a minor version for every PR. PRs are the delivery unit; semver versions are the curated release narrative.

​
Release invariants

Every release must satisfy all of these:
  1. Root package.json contains the intended semver version.
  2. Root CHANGELOG.md contains ## vX.Y.Z for that same version.
  3. If a public web changelog entry exists at apps/web/content/changelog/vX.Y.Z.mdx, its frontmatter version equals the filename and its date is a real merge/commit date.
  4. Git tag must match exactly at release time: package.json 0.12.1 ↔ tag v0.12.1.
  5. GitHub Release notes are generated from the matching semver tag.
Normal feature/fix PRs after a release do not need to bump package.json unless they intentionally cut a new release train. They do need docs/changelog updates when behavior changes.

​
Back-minting tags

Current historical state is imperfect: early alpha moved faster than the release discipline. Only v0.0.1 was tagged while package.json later advanced to 0.12.1. Before alpha there are two acceptable options:
  • Preferred: start strict matching at the next coherent release train, e.g. v0.13.0, and treat older changelog sections as historical reconstruction.
  • Optional: back-mint missing tags only when the exact release commit is known and stable. Do not create historical tags from guesswork.

​
Helper commands

release:hygiene checks that package.json, CHANGELOG.md, public web changelog entries, and any existing matching tag are coherent.

​
PR authoring rule

If a PR changes user-visible behavior, API contracts, operator docs, setup flows, or deployment/runtime behavior, it must update at least one of:
  • CHANGELOG.md
  • apps/web/content/changelog/*.mdx
  • apps/docs/**
  • planning/** for intentionally internal/operator-only notes
If no docs/changelog update is needed, say why in the PR body.