Skip to content

Versioning ​

The business rules will keep changing. This page is the contract for how a change is made without rewriting history. Rationale: ADR 0004.

flowchart TD
  Q{What is changing?}
  Q -->|a product rule or behaviour| S[Spec: bump SPEC_VERSION, changelog entry]
  Q -->|a number or switch the owner tunes| ST[Setting: new revision, effectiveFrom, reason]
  Q -->|a price or document wording| T[Template: new version, publish]
  Q -->|a sent quote or signed contract| X[Never changes: it is a snapshot]
  Q -->|shape of a JSON column or queue message| J[schemaVersion + upgrade step]
  Q -->|a table or column| M[New migration, append-only]
  Q -->|an API call's input or output| A[Additive: stay in v1. Breaking: add v2]
  Q -->|a UI component from beUI| U[ui:update, lockfile records it]

1. Versioned JSON ​

Use for any JSON column whose shape may change: lead form answers, snapshot payloads, comment anchors, quote line items.

Store { schemaVersion, data }. Define the schema once with defineVersionedSchema (@shootgrow/domain):

ts
const formAnswers = defineVersionedSchema({
  name: "lead.formAnswers",
  current: 2,
  schema: formAnswersV2, // Zod schema of the latest shape
  upgrades: { 1: (v1) => ({ ...v1, social: [] }) }, // v1 -> v2, pure
});

formAnswers.wrap(input); // write: validates, stamps current version
formAnswers.read(row.answers); // read: upgrades any old version, validates

Rules: versions start at 1 and increase by exactly 1; every version below current needs an upgrade (the definition throws at startup if one is missing); upgrades are pure and never throw on valid old data; a stored version newer than the running code throws, because it means the older build must not touch that row.

To change a shape: bump current, add upgrades[old], keep reading old rows lazily. Rewrite stored rows only if you need to query inside the JSON, and then in a separate migration.

2. Snapshots ​

Use for anything sent or signed: quotes, contracts, crew contracts.

When the owner sends or the client signs, call freezeSnapshot({ kind, templateVersionId, schemaVersion, data }). It returns the data plus a SHA-256 over the canonical JSON (keys sorted), and stores the template version id for audit. Store the whole object on the document row. From then on:

  • The document never reads the live template or live prices.
  • verifySnapshot can prove the stored terms still match their hash.
  • Editing the template only affects documents created afterwards.

Example. A client signs 4 months at £1,000. The owner publishes plan version 2 at £1,200. The signed contract still reads £1,000 from its snapshot; new quotes pick version 2.

3. Effective-dated revisions ​

Use for settings and anything whose "current" value changes over time (crew pay terms, rates).

Append a row; never update one. "What applied at time T?" is resolveEffective(rows, T): the latest effectiveFrom <= T, ties broken by revision. Ledger lines store the rate they used, so past pay never moves.

Settings specifically:

  • The registry (packages/domain/src/settings.ts) defines each key: Zod schema, default, group, label, the open-decision number it answers, and a provisional flag when the spec gave no value.
  • The setting table stores revisions: key, revision, value, effectiveFrom, reason, createdBy. Triggers reject UPDATE/DELETE.
  • Reading: resolve the revision, parseSetting, else getSettingDefault.
  • Writing: insert revision = max + 1, set effectiveFrom (usually now; a future date schedules a change), record a reason, and write an audit_log row in the same batch.
  • Adding a key: add it to the registry with a default. No migration; code works before any row exists.
  • Renaming or changing the meaning of a key: add a new key, read the old one as a fallback for a release, then retire it. Never reuse a key.
  • A changed schema for a key's value: widen the Zod schema compatibly, or add a new key.

4. Templates (plans, quotes, contracts) ​

template_version rows: (kind, key, version) unique, status of draft | published | retired.

StatusEditableUsed for new documents
draftyes, and deletableno
publishedno (trigger)yes: the highest published version for (kind, key)
retirednono

Publishing sets status, content_hash and published_at. A published row may only move to retired. To change wording or a price: copy the published row into a new draft (version + 1), edit, publish. Prices are kind = plan templates, not settings.

5. Database schema ​

Append-only migrations, enforced by bun run db:check and CI. Make each migration backward compatible with the previous build for one release. Details: Database.

6. HTTP API ​

The oRPC router is namespaced: orpc.v1.<router>.<procedure>. The web app and server deploy together, so versioning exists to keep deploys safe and to leave room for other clients later.

  • Additive changes (new procedure, new optional input, new output field) stay in v1.
  • Breaking changes add the new shape under v2.<same name>. Move callers, then delete the v1 procedure in the same change as its last caller.
  • v1.meta.info returns apiVersion and specVersion; the app footer displays them.

7. Background jobs ​

Queue messages are versioned envelopes with idempotency keys. A consumer accepts the current and previous payload version for one release. See Background jobs.

8. UI components ​

beUI source is vendored; packages/ui/beui.lock.json records each component's upstream updated_at and a hash of every file as written. bun run ui:status shows local edits and available updates; ui:update refuses to overwrite edited files without --force.

9. The spec itself ​

SPEC_VERSION (packages/domain/src/spec.ts) names the spec the code was last reconciled with. The app footer shows it. Bump it as described in Changing the spec.

Checklist for a change ​

  • [ ] Is the value something the owner might change? Make it a setting, not a constant.
  • [ ] Does it touch a sent or signed document? It must come from a snapshot.
  • [ ] Does it change a stored JSON shape? Bump the schema version and add an upgrade.
  • [ ] Does it change a table? New migration; compatible with the previous build.
  • [ ] Does it break an API caller? Add v2, do not mutate v1.
  • [ ] Did the spec change? Update the chapter, bump SPEC_VERSION, add a changelog entry.
  • [ ] Is the decision hard to reverse? Write an ADR.

Internal documentation. Not for clients.