Contract evolution: breaking changes, spec diffs, versioning and deprecation

A radio contest organiser takes logs from hundreds of operators, sent by logging programs each operator updates when they like, and publishes a results file that clubs' scoring spreadsheets read.

At the contest	In the API
operators' programs, updated whenever their owners get round to it	clients you cannot redeploy (step 1)
logs coming in, results going out: two different checks	requests and responses judged in opposite directions (step 2)
the log checker starts accepting a new band: no old log is bounced	a request accepting more (step 3)
a new mandatory box on the log: every old program's log bounces	a newly required request field (step 3)
a new entry category in the results file: a spreadsheet with a fixed list of categories stops	a value the old reader lacks (step 4)
an extra column in the results file that spreadsheets skip	a new response field and a tolerant reader (step 5)
"format 2 is superseded from 1 November"	Deprecation (step 11)
"format 2 logs are refused after 31 March"	Sunset (step 12)

In real terms: before shipping, ask who reads what this change produces, and whether their old code still accepts it.

Breaks down when: a bounced operator gets an email and resends; an old client fails in a user's hands, often with no one to tell.

Contrasting case: a frontend and its API deployed together from one repository, with no other caller: every reader is redeployed with the change.

4.1 ExamHall EXH-3650: the one-step rename

The proctor API renamed flagged to suspicionLevel in one release. Desktop consoles six weeks old failed on every GET /attempts (EXH-3650). Run on the spec after the fact, the diff gate MR !3950 later added would have failed it:

EXH-3650 one-step rename · old console (6 weeks old) throws at 0.flagged · openapi-diff main -> MR: 1 breaking [response.body.scope.add]

MR !3950 adds that gate to CI, base branch first, and replaces the rename with two releases, the second shipped only after the old field's Sunset date:

MR !3950 release 1, both fields sent · old console reads it · new console reads it
MR !3950 release 2, after the Sunset date, flagged removed · old console throws at 0.flagged · new console reads it

Release 2 still breaks any console left on the old build: the Sunset date tells those owners when (step 12), and the gate's failure is expected and signed off for that one release (steps 7, 9).

4.2 Ticketing: four edits, two directions

A box office's app from last month sends { "eventId": "ev-77", "seatType": "wheelchair" } and reads events through a zod schema. Each edit runs against it:

request: `seatType` drops "wheelchair"         · remove-enum-value  · last month's app: its request gets 422
request: optional `promoCode` added            · add-optional-field · last month's app: its request gets 201
response: `venue` removed                      · remove-field       · last month's app: its reader throws
response: optional `accessibleEntrance` added  · add-optional-field · last month's app: reads the response

The two additions are safe: the server still accepts the old request (step 3), and the old reader skips the unknown field (step 5). The removals break in both directions: the server refuses a value it once accepted, and the reader misses a field it requires (steps 3–4).