Duolith docs

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 valid bump is an error, so a typo never becomes the default. A note without front matter is minor. 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 into Cargo.toml, Cargo.lock and every workspace package.json. It moves the notes into a new section of CHANGELOG.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 from changes/. It does not commit, tag or publish. Without --write it only prints what it would change.
  • CHANGELOG.md is generated. pnpm changelog rewrites its Unreleased section from the notes. Released sections are never changed.

Alternatives considered

OptionWhy not
The changesets packageIt 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 packagePackages that must match would drift apart, and users would have to work out compatible sets.
Fail CI when the Unreleased section is staleEvery 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.