Step 01 of 06
Learn the concept
A release is not a zip file with a hopeful name. It is a contract: this version means something, this tag points at these bits, these notes tell humans whether they should care, and this deprecation gives them time to move.
The ideas this is made of
A major version promises a compatibility break
Semantic versioning says MAJOR breaks compatibility, MINOR adds compatible behavior, and PATCH fixes compatible bugs. A rewrite can be a patch if users cannot tell. A one-line API removal can be a major.
Conventional commits make intent parseable
Messages like feat: add canary gate and fix: handle empty target let tooling group changes into notes. feat!: or a BREAKING CHANGE: footer signals a major bump.
Release notes start where users feel the change
A human wants to know what changed, whether action is required, and what risk exists. Good notes group features, fixes, breaking changes and deprecations, then link to details.
Deprecation is a promise with a removal date
A deprecation policy says what is still supported, what warns, and when it disappears. Without dates, deprecated means 'we dislike it but you can probably keep using it forever.'
v2.3.0
Added: weekend express
Fixed: platform 4 typo
Deprecated: paper lookup, removed in v3.0
Action: update printed signs by Nov 1Riders learn what changed and whether they must act. The version matters because the promise is clear.
Version bumps by promise
| Change | SemVer bump | Example |
|---|---|---|
Compatible bug | PATCH | 1.4.2 -> 1.4.3 |
Compatible feature | MINOR | 1.4.2 -> 1.5.0 |
Breaking contract | MAJOR | 1.4.2 -> 2.0.0 |
Deprecation notice | Usually MINOR | Warn before removal |
What these are called on the job
Semantic versioning — MAJOR.MINOR.PATCH scheme based on compatibility promises.
Conventional commit — Commit message with a typed prefix such as
feat:orfix:.Release notes — Human-readable summary of impact, actions and links for a version.
Deprecation — Supported for now, warned against, and scheduled for removal.