Appearance
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:
| Bump | When | Example |
|---|---|---|
Patch 1.0.x | Wording, clarification, typo; no behaviour change | Adding own_user to the scope list's explanation |
Minor 1.x.0 | New behaviour, new screen or rule, or an open decision answered | Owner answers decision 2: calls need approval |
Major x.0.0 | A rule that changes how existing data is interpreted | Redefining which statuses count as "active client" |
A major bump needs a migration plan written in the changelog entry (what happens to existing rows).
Steps
- Edit the chapter. Keep the chapter id stable. If you add a new chapter, add it to
.vitepress/config.ts, to the table inspec/index.md, and toSpecChapterinapps/web/src/lib/spaces.tsif screens link to it. - 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).
- Add a changelog entry in
spec/changelog.md: version, date, what changed, who asked, impact on existing data. - Bump
SPEC_VERSION. - 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.
- Write an ADR if the change is expensive to reverse (see ADRs).
- 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.