Semantic Versioning & Release Management

Version numbers communicate change to consumers. A major version bump says “things broke, you need to update your code.” A minor bump says “new features, but everything still works.” A patch says “bug fixes, safe to update.” When versioning is inconsistent or meaningless, developers lose trust and stop updating — which is how you end up with dependencies 3 years behind.

---

Semantic Versioning

MAJOR.MINOR.PATCH

1.0.0 → Initial stable release
1.0.1 → Bug fix (patch)
1.1.0 → New feature, backward compatible (minor)
2.0.0 → Breaking change (major)

Pre-release: 2.0.0-alpha.1, 2.0.0-beta.3, 2.0.0-rc.1
Build metadata: 1.0.0+build.123

Change Type	Version Bump	Example
Bug fix	Patch (0.0.X)	Fix null pointer exception
New feature (backward compatible)	Minor (0.X.0)	Add new API endpoint
Breaking change	Major (X.0.0)	Remove deprecated endpoint
Security fix	Patch (0.0.X)	Fix XSS vulnerability
Performance improvement	Patch (0.0.X)	Optimize query (same behavior)
Deprecation notice	Minor (0.X.0)	Mark endpoint as deprecated

---

Automated Changelog

# Conventional Commits → Automated Changelog + Version Bump

# Commit messages:
feat: add order search endpoint          → Minor bump
fix: handle null customer email          → Patch bump
feat!: remove v1 order API               → Major bump
chore: update dependencies               → No bump
docs: update API documentation           → No bump

# Generated CHANGELOG.md:
## [2.0.0] - 2025-03-15
### ⚠ BREAKING CHANGES
- Remove v1 order API (`feat!`)

### Features
- Add order search endpoint

### Bug Fixes
- Handle null customer email

---

Release Branching Strategies

Strategy	How It Works	Best For
Trunk-based	All work on main, release from tags	CI/CD teams, SaaS products
GitFlow	develop → release → main	Packaged software, scheduled releases
Release branches	Branch per release, cherry-pick fixes	Multiple supported versions

Recommended: Trunk-Based + Tags

main ──●──●──●──●──●──●──●──●──●── (continuous)
       │           │              │
       tag v1.0.0  tag v1.1.0    tag v2.0.0

---

Anti-Patterns

Anti-Pattern	Problem	Fix
No versioning	Consumers don’t know what changed	Semantic versioning from v1.0.0
Breaking changes without major bump	Consumers’ code breaks unexpectedly	Major version bump for every breaking change
”Version 47.0.0”	Meaningless numbers, too many major bumps	Only bump major for actual breaking changes
No changelog	Only way to know what changed is reading commits	Automated changelog from conventional commits
Manual version bumps	Forgotten, inconsistent, errors	CI automates bump from commit messages

---

Checklist

• Semantic versioning adopted (MAJOR.MINOR.PATCH)
• Conventional commits enforced (feat, fix, chore, etc.)
• Changelog automated from commit messages
• Version bump automated in CI/CD
• Release tags created automatically
• Breaking changes highlighted in changelog
• Deprecation notices in minor versions before removal
• Release notes published for every version

---

:::note[Source] This guide is derived from operational intelligence at Garnet Grid Consulting. For release management consulting, visit garnetgrid.com. :::