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

# Versioning

> Semver, build identity, changelog, and release tagging rules for the repository.

# 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

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

`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.

## Read next

* [Release Process](/contributing/release-process)
* [CI/CD](/operations/cicd)