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.3is 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¶
- Declare the contract per artefact. Checkpoint: the surface is a file, not a description.
- Write the versioning policy. Checkpoint: each of the four artefacts has a meaning for major.
- Build the compatibility check. Checkpoint: a planted removal fails it.
- Record the matrix. Checkpoint: "who consumes this" is answerable.
- 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.
- Four artefacts, one meaning — major, minor and patch for a library, an API, a schema and an event.
v1.2.3is a tag, not a semantic version; the surface must be declared for the number to mean anything.- Compatibility is a check against the contract, not the test suite — and the matrix makes it possible.
- Deprecation has a clock — announce, warn, support, remove, each dated.
- An agent sees a diff, not a promise — which is why the check runs before the tag, not after the incident.