Skip to content

Changing the spec ​

The spec (apps/docs/spec) is the source of truth for what the product does. Code follows it. When the owner changes his mind, the spec changes first (or in the same pull request as the code), never silently after.

Version number ​

SPEC_VERSION in packages/domain/src/spec.ts, semantic:

BumpWhenExample
Patch 1.0.xWording, clarification, typo; no behaviour changeAdding own_user to the scope list's explanation
Minor 1.x.0New behaviour, new screen or rule, or an open decision answeredOwner answers decision 2: calls need approval
Major x.0.0A rule that changes how existing data is interpretedRedefining which statuses count as "active client"

A major bump needs a migration plan written in the changelog entry (what happens to existing rows).

Steps ​

  1. Edit the chapter. Keep the chapter id stable. If you add a new chapter, add it to .vitepress/config.ts, to the table in spec/index.md, and to SpecChapter in apps/web/src/lib/spaces.ts if screens link to it.
  2. Update open decisions. Answered a DECIDE? Fill the Answer column with the answer and date. If it is a setting, change the stored value (or the registry default if the old default was simply wrong).
  3. Add a changelog entry in spec/changelog.md: version, date, what changed, who asked, impact on existing data.
  4. Bump SPEC_VERSION.
  5. Find affected code. Search for the chapter id and for the setting keys involved. Update tests that encode the old rule; delete tests that only pinned wording.
  6. Write an ADR if the change is expensive to reverse (see ADRs).
  7. Apply the versioning checklist to the code: settings vs constants, snapshots, schema versions, migrations, API versions.

New ideas ​

An idea that is not part of the change in hand goes on the roadmap, not into the pull request. It becomes spec text only when it is accepted.

Reviewing ​

A pull request that changes behaviour without touching the spec (or one that touches the spec without the code it implies) is incomplete. The PR template asks.

Internal documentation. Not for clients.