Skip to content

Chapter 23: Versioning, Artefacts and Contracts

A Number That Carries a Promise

A product that changes needs a promise about compatibility — this chapter makes the version that promise, for artefacts and contracts alike.


1. What a Version Promises

The three structures produce artefacts other systems consume: an API, a schema, an event, a library. A version is the only thing that tells a consumer whether an upgrade is safe — and it only tells the truth if it was written before the change, as a policy, and enforced by a check.

Without that, a version number is a date with extra steps.

🎯 What You'll Learn

  • What major, minor and patch mean for four kinds of artefact
  • Why v1.2.3 is a tag convention, not a semantic version
  • The compatibility check that refuses a break before release

Four Artefacts, One Meaning

Artefact major minor patch
library a removed or changed public function a new function a fix
API a removed endpoint, field or status a new endpoint or optional field a fix
schema a removed or renamed column a new nullable column an index, a comment
event a removed or changed field a new optional field a fix

The precision worth keeping: v1.2.3 is a tag-name convention. SemVer is 1.2.3; it means nothing until a public surface is declared (rule 1), and a published version is never modified (rule 3). A tag with a v is fine — as long as everyone knows the v is the tag, not the contract.

✅ What to Check

  • Name your four artefacts. Which of them has a declared public surface?
  • Has a published version ever been modified in place? That is the rule-3 break.

2. Compatibility Is a Check, Not a Virtue

Tests prove that your code works with your code. Compatibility proves that a consumer written against the old surface still works — and only a check that reads the declared contract can tell you that.

The claim How it is verified
"it is backward compatible" nobody removed a field; the contract diff is empty
"the consumer still works" a contract test against the published surface
"we did not break anyone" the compatibility matrix says who consumes what

The compatibility matrix is the part teams skip: who consumes which version, and what the oldest supported is. Without it, "did we break anyone?" is unanswerable, and so is "may we deprecate this?".

The Check, as a shape

for each declared contract:
  diff the published surface against the working tree
  a removal or a rename without a major bump → refuse
  a new required field without a major bump → refuse

for each consumer in the matrix:
  a version below the support floor → report

✅ What to Check

  • Does your compatibility check read the contract, or does it run the tests?
  • Does the matrix exist? If not, "who consumes this" is a guess.

3. Deprecation Has a Clock

Announce, warn, support, remove — each a phase, each with a date. A deprecation without a date is a preference: nobody knows when the breaking change lands, so nobody plans for it.

Phase What happens The evidence
announce consumers are told, and the window is stated the announcement, dated
warn the system emits a warning on use the warning, in the log
support both paths work; the old one is fixed, not extended the matrix shows who still uses it
remove the old path is deleted, with a major bump the bump, and the empty warning

The clock is the point. A deprecation that drifts is indistinguishable from a promise to keep it forever — and consumers plan on the behaviour they observe, not the policy you wrote.

✅ What to Check

  • Take a deprecated thing. When does it end? Is the date written where consumers read it?
  • Has any deprecation been removed on schedule? If none, the policy is decorative.

4. Version Skew

Skew What it looks like The catch
a client older than the contract a request missing a required field the matrix's support floor
a migration ahead of the code a column the running code does not know expand/contract with a phase per deploy
an agent pinned to a stale schema a tool call using a field that was renamed the agent reads the contract, and the check refuses

The third is the new one. An agent pinned to a schema does not notice a rename; it produces a call that is plausible and wrong. So the contract must be readable by the agent — and the tool boundary must refuse a call that does not match it.

The AI Delta

An agent will ship a breaking change as a patch without malice: it sees a diff, not a promise. The compatibility check is the only thing standing between a helpful agent and a consumer outage. A pinned agent, given a stale schema, degrades silently — so skew detection is not optional for machine consumers.

💰 Cost Check: a breaking change shipped as a patch costs every consumer at once, on a Friday. A deprecation without a date costs an indefinite support obligation. A version number that carries no promise costs the trust that makes upgrades routine. The policy and the check cost a file and a gate.

flowchart LR
  C["contract<br/>the declared surface"] --> V["version<br/>major · minor · patch"]
  V --> M["matrix<br/>who consumes what"]
  M --> K{"compatibility check"}
  K -->|"refused"| F["the break stops before release"]
  K -->|"passes"| R["a safe upgrade"]

What this shows: the contract and the version only mean something together, and the matrix is what makes the check possible.

The Delegation Line

The agent bumps versions and drafts the policy. The human declares the public surface and the support floor. The system refuses a removed field without a major, and reports a consumer below the floor.


5. Build the Delivery

Deliverables

Artefact Shape Where it lives
versioning policy what major, minor and patch mean per artefact docs/versioning.md
contract declaration the surface the version promises contracts/<artefact>/
compatibility matrix who consumes which version, and the floor docs/compatibility.yaml
deprecation clock announce · warn · support · remove, dated beside the policy

Decisions

Choice Default What changes if you choose otherwise
one version per repository or per artefact per artefact a consumer consuming a repository cannot tell what changed
where the check runs CI, before the tag release, after the break is built
the support floor one minor cycle, written an indefinite obligation
a deprecation announced with a date a warning nobody plans around

✅ Gates

  • A removed field without a major bump is refused.
  • A consumer below the support floor is reported.
  • A modified published version is refused.

Runbook

  1. Declare the contract per artefact. Checkpoint: the surface is a file, not a description.
  2. Write the versioning policy. Checkpoint: each of the four artefacts has a meaning for major.
  3. Build the compatibility check. Checkpoint: a planted removal fails it.
  4. Record the matrix. Checkpoint: "who consumes this" is answerable.
  5. Run one deprecation to its deadline. Checkpoint: the removal happened on the date.

🎯 Proof

  • A breaking change that fails before release.
  • A deprecation completed on the written date.
  • A skew report that names the stale consumer.

6. 🔑 Chapter Summary

A version is a promise; the contract is what makes it true.

  1. Four artefacts, one meaning — major, minor and patch for a library, an API, a schema and an event.
  2. v1.2.3 is a tag, not a semantic version; the surface must be declared for the number to mean anything.
  3. Compatibility is a check against the contract, not the test suite — and the matrix makes it possible.
  4. Deprecation has a clock — announce, warn, support, remove, each dated.
  5. An agent sees a diff, not a promise — which is why the check runs before the tag, not after the incident.