Skip to content

ADR 0004: Versioning strategy ​

  • Status: Accepted
  • Date: 2026-11-18
  • Spec version: 1.0.0

Context ​

The owner expects the business rules to keep changing: prices, schedule offsets, contract wording, who sees what, auto-approve behaviour. The spec already demands that a price change must not alter a signed contract. Without a deliberate approach, each change risks rewriting history, breaking stored data, or silently changing behaviour for existing clients.

Decision ​

Treat "things that change" in eight separate layers, each with its own mechanism (Versioning):

LayerMechanism
Product rulesSpec is versioned (SPEC_VERSION), chaptered, with a changelog and numbered open decisions
Owner-tunable valuesSettings registry in code (type, default, decision link) + append-only, effective-dated setting revisions in D1
Prices and document textVersioned templates (template_version: draft → published → retired), published rows frozen by triggers
Sent or signed documentsFrozen snapshots with a SHA-256 hash; never re-derived from current templates
Shape of stored JSON and queue messages{ schemaVersion, data } envelopes with upgrade chains; job envelopes carry v
Database schemaAppend-only migrations, checked in CI; backward-compatible for one release
HTTP APIoRPC router namespaced v1; breaking change adds v2.<name>
UI componentsbeUI vendored with a lockfile of hashes and upstream dates

History tables (setting, audit_log) and published templates are protected by database triggers, not by convention.

Consequences ​

  • Changing a rule is usually a data change (insert a settings revision, publish a template version), not a deploy.
  • Features must read rules through the registry and write snapshots when they send or sign something. A hard-coded constant that the owner might change is a review failure.
  • A little more ceremony on each schema or settings change; in exchange, "what applied on 3 March?" is always answerable.

Revisit when ​

Settings revisions become heavy to query (cache the resolved value), or the owner needs approvals/review on settings changes (add a draft state like templates have).

Internal documentation. Not for clients.