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.
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.'
# 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 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 |
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:orfix:.Release notes — Human-readable summary of impact, actions and links for a version.
Deprecation — Supported for now, warned against, and scheduled for removal.
