0092. One version for everything, worked out from the change notes
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: WP16 (release pipeline)
Context
Every change already adds a note to changes/ (CONTRIBUTING.md), and CHANGELOG.md said it would be generated from them once WP16 existed. A release needs a version number and a changelog. The packages, the extension and the CLI are designed and tested together, and a page compiled by one compiler version expects the runtime from the same version.
Decision
- One version. The crates, the npm packages, the extension and the CLI share the version in the root
Cargo.toml([workspace.package]), like changesets' "fixed" mode. - The notes say how big a change is. A note may start with YAML front matter,
bump: major | minor | patch, and nothing else. Quotes, comments, Windows line endings and blank lines before it are fine. Front matter without one validbumpis an error, so a typo never becomes the default. A note without front matter isminor. The release takes the largest bump. Before 1.0 a breaking change raises the minor number, because 1.0 is a choice and not something the counter reaches. From a prerelease, the release is the version the prerelease led to (1.2.0-rc.1 becomes 1.2.0), unless the bump needs a bigger step. - Versioning (
node tools/release/version.ts --write,pnpm release:version) writes the version intoCargo.toml,Cargo.lockand every workspacepackage.json. It moves the notes into a new section ofCHANGELOG.md, grouped as breaking changes, changes and fixes, oldest note first within each group (by when git added it, then by name), and removes them fromchanges/. It does not commit, tag or publish. Without--writeit only prints what it would change. - CHANGELOG.md is generated.
pnpm changelogrewrites its Unreleased section from the notes. Released sections are never changed.
Alternatives considered
| Option | Why not |
|---|---|
| The changesets package | It versions npm packages only, not the Cargo workspace or the extension, and it adds a dependency. The notes already exist in this format. |
| A version per package | Packages that must match would drift apart, and users would have to work out compatible sets. |
| Fail CI when the Unreleased section is stale | Every parallel branch that adds a note would conflict on CHANGELOG.md. It is regenerated at release instead. |
Consequences
- A note that only fixes a bug should say
bump: patch. Otherwise the release counts it as a feature. - The Unreleased section in the repository can lag behind
changes/between releases. The release regenerates it.