Project challenges / verified progress
Beacon: ship it without fear

The engineering notebook

Give releases meaning

How does a release tell users what changed and what promises now hold?

Loading Vault account...
Release and recover

Step 01 of 06

Understand the idea

A release tells users which version is available and what changed. Clear version numbers and release notes help teams decide whether to upgrade and prepare for features that will be removed later.

CHANGE TO RELEASE01Committyped intent02Versionsemver chosen03TagGit points here04Imagesame version tag05Noteshumans briefed
A release binds human meaning to machine identity. The version, Git tag, image reference and notes should tell the same story from different angles.
Step 01

Key technical ideas

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.'

A train timetable release
# Create and push a semantic version tag to start the release pipeline.
git tag v1.5.0 && git push origin v1.5.0
glab ci list --per-page 1

Riders learn what changed and whether they must act. The version matters because the promise is clear.

Version bumps by promise

ChangeSemVer bumpExample

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

Technical terms used at work

  • Semantic versioning — MAJOR.MINOR.PATCH scheme based on compatibility promises.

  • Conventional commit — Commit message with a typed prefix such as feat: or fix:.

  • Release notes — Human-readable summary of impact, actions and links for a version.

  • Deprecation — Supported for now, warned against, and scheduled for removal.