How changelog entries are written
The fixed vocabulary behind every entry, and how each verb maps to a track and a version part.
Every changelog entry is written to a fixed vocabulary. The verb at the start of a line says what kind of change it was, which decides both the track it belongs to and which part of the version it moves.
The vocabulary
Verb | Track | Version part | Means |
|---|---|---|---|
Released | Services |
| A service, component or body of content goes live |
Re-released | Services |
| An existing service relaunched on a new footing |
Migrated | Services |
| Moved onto a different application or platform |
Deprecated | Services |
| Retired or marked end-of-life |
Added | Services / Stability |
|
|
Upgraded | Stability |
| A version bump; no behaviour change expected |
Fixed | Stability |
| A defect corrected, including failed hardware |
Retrofitted | Stability |
| An existing service brought in line with current standards |
Documentation of | Documentation |
| A wiki or Help Centre page published |
In progress | — |
| Work started but not yet shipped |
Phase N | Phases |
| A phase or subphase begins or completes |
One override: any entry about documentation, the wiki or the Help Centre counts as Documentation whatever verb it starts with.
The two that get confused
Upgraded vs Fixed. Upgraded is planned — a service moves to a newer version because a newer version exists, and nothing was broken. Fixed is reactive — something was not working and now is. Most maintenance is Upgraded; it is the single most common entry in the history.
Added at z vs w. Added is the one verb that can land either side. It counts as a release when it introduces something that did not exist — a new application, or a body of content like games, roms or films. It counts as a change when it extends what is already there: a policy, a probe, extra storage.
Deploying an internal component counts as a release. CrowdSec, Elasticsearch and a secondary DNS are all releases even though nobody browses to them.
Older entries
The changelog carries history predating this vocabulary, written more loosely — Re-released, Rebuild, Deployement, RMA for 2 SSD. Those were rewritten to the verbs above when the wiki's news log was migrated in, so tracks and version numbers are consistent across the whole history.
The substance is unchanged. Only the opening verb and, where the original was ambiguous, the phrasing around it.
Was this helpful?
Your feedback shapes what we write next.