Writing release notes

How releases work here, and the four conventions that keep the notes worth reading.

What a release is

There is no version number. The pipeline numbers each build, and one build is promoted through six environments, each behind a manual approval. Nothing is released automatically, and there is no production environment yet. See CI/CD.

So "a release" here means a build that reached an environment, not a versioned package. That is why entries are dated by when the change merged — the closest honest thing to a release date — and grouped into a page per year.

When a version scheme arrives, entries can be grouped under versions without changing the page shape.

The four conventions

Add it as you merge	Under the current month, at the top. Reconstructing later loses the intent — which is exactly what happened to everything before this page existed
Reader-visible only	A capability or a behaviour. Pipeline edits, configuration, service-connection names, refactoring and test work belong in the commit, not here
Say what changed for a user	"Buy-X-get-Y counts units, not lines", not "refactored the promotion evaluator". If you cannot express it that way, it probably does not belong here
A behaviour change is a documentation change	If an entry contradicts a page on this site, that page is now wrong. Fix both in the same change

That last one is the one that decays first, and the one that matters most. An entry saying a rule changed, sitting beside a page still describing the old rule, is worse than no entry at all — a reader will believe the page.

The shape of an entry

One row per change, in the current month's table.

Date	Day and abbreviated month — 18 Aug
Type	Added, Changed or Fixed. Nothing else — Removed is a Changed from a reader's point of view
Change	One sentence. Link to the page that explains it, where one exists

Keeping it to one sentence is deliberate. The detail belongs on the page the entry links to; a release note that needs a paragraph is describing something the documentation should already cover.

Starting a new year

Add release-notes/{year}.md, put it above the previous year in the navigation, and leave older years in place. Years are never merged or pruned — an old entry is the only record of when a behaviour changed.