michaelsvanbeek/release-management

Release Management Standards

When to Use

• Deciding what version number to assign a change
• Creating a release (tag, branch, changelog entry)
• Writing release notes or changelog entries
• Classifying changes as breaking, functional, or non-functional
• Designing release workflows for a project
• Automating version bumps in CI/CD
• Planning breaking changes or deprecations
• Auditing an existing project for missing version tags, changelogs, or release processes
• Retrofitting semantic versioning and release workflows to an unversioned project

---

Semantic Versioning (SemVer 2.0.0)

Version format: MAJOR.MINOR.PATCH

Given a version 1.4.2:

| Segment | Value | Increment when | |---------|-------|---------------| | MAJOR | 1 | Breaking change — consumers must update their code | | MINOR | 4 | New feature — backward-compatible addition | | PATCH | 2 | Bug fix — backward-compatible correction |

When to Bump What

| Change type | Bump | Example | |-------------|------|---------| | Fix a bug without changing API | PATCH | 1.4.2 → 1.4.3 | | Add a new feature, existing behavior unchanged | MINOR | 1.4.3 → 1.5.0 | | Change or remove existing behavior | MAJOR | 1.5.0 → 2.0.0 | | Add deprecation warning (feature still works) | MINOR | 1.5.0 → 1.6.0 | | Remove deprecated feature | MAJOR | 1.6.0 → 2.0.0 | | Refactor internals without API change | PATCH | 1.4.2 → 1.4.3 | | Update dependencies (no behavior change) | PATCH | 1.4.2 → 1.4.3 | | Update dependencies (new features exposed) | MINOR | 1.4.3 → 1.5.0 | | Documentation-only changes | No bump (or PATCH if versioned docs) | — |

Reset Rules

• When MAJOR increments, MINOR and PATCH reset to 0: 1.5.3 → 2.0.0
• When MINOR increments, PATCH resets to 0: 1.4.3 → 1.5.0

Pre-Release Versions

Use for testing before a stable release:

2.0.0-alpha.1    # early testing, API may change
2.0.0-beta.1     # feature-complete, fixing bugs
2.0.0-rc.1       # release candidate, final validation

Pre-release versions have lower precedence than the release: 2.0.0-alpha.1 < 2.0.0.

Increment the numeric suffix for subsequent pre-releases: 2.0.0-beta.1 → 2.0.0-beta.2.

Build Metadata

Append with + for informational metadata (ignored in version precedence):

1.4.2+build.456
1.4.2+20260320

Version 0.x.y

Major version zero (0.y.z) signals initial development — anything may change at any time. The public API should not be considered stable. Bump to 1.0.0 when the API is stable and used in production.

---

Version Source of Truth

Every project must have one canonical location for its version. Never define the version in multiple places.

| Project type | Version source | How to read | |--------------|---------------|-------------| | Python | pyproject.toml → [project] version | python -c "import importlib.metadata; print(importlib.metadata.version('pkg'))" | | Node.js | package.json → version | node -p "require('./package.json').version" | | Generic | Git tag | git describe --tags --abbrev=0 | | Docker | Image tag | Build-time from git tag or version file |

Git Tags as the Release Record

• Tag every release: git tag -a v1.4.2 -m "Release v1.4.2"
• Use annotated tags (-a), not lightweight tags — annotated tags store author, date, and message.
• Prefix with v: v1.4.2, not 1.4.2.
• Tags are immutable — never delete and re-create a tag. If a release is bad, publish a new PATCH.

---

Release Workflow

Standard Release (Feature or Fix)

main ──────────────────────────────── main
         \                        /
          feat/my-feature ───────    ← development
                                  \
                            PR merge to main
                                  \
                              v1.5.0 tag  ← release

1. Develop on a feature branch (see git-workflow skill for branch naming).
2. Open a PR. CI runs lint + test (see cicd skill).
3. Merge to main.
4. Update changelog (see Changelog section).
5. Bump version in the version source file.
6. Commit: chore(release): v1.5.0
7. Tag: git tag -a v1.5.0 -m "Release v1.5.0"
8. Push: git push origin main --follow-tags
9. CI detects the tag and runs the release pipeline (build, publish, deploy).

Hotfix Release

For urgent fixes to production when main has unreleased changes:

v1.4.0 ──── hotfix/fix-crash ──── v1.4.1

1. Branch from the release tag: git checkout -b hotfix/fix-crash v1.4.0
2. Fix the issue. Add a regression test.
3. Bump PATCH version, update changelog.
4. Tag: git tag -a v1.4.1 -m "Release v1.4.1"
5. Push the hotfix branch and tag.
6. Cherry-pick the fix into main to keep it up to date.

Breaking Change Release

Breaking changes require extra care:

1. Deprecate first — add deprecation warnings in a MINOR release. Document the migration path.
2. Communicate — changelog, README, and (if applicable) migration guide.
3. Remove — in the next MAJOR release, remove the deprecated code.
4. Bump MAJOR — 1.x.y → 2.0.0.

---

Release Notes

Release notes are the primary communication artifact for every release. They must be clear enough for any consumer — developer, operator, or product stakeholder — to understand what changed, what might break, and what they need to do.

Change Classification

Every change in a release falls into one of three tiers. Group and label changes by tier in the release notes:

| Tier | Label | What it covers | Reader action | |------|-------|---------------|---------------| | Breaking | ⚠ BREAKING | Removed APIs, changed behavior, renamed fields, dropped support | Must update code or config before upgrading | | Functional | Features & Fixes | New features, bug fixes, behavior changes that are backward-compatible | Review and adopt at their discretion | | Non-Functional | Internal | Refactors, dependency updates, performance, docs, CI, test changes | No action required — informational only |

Release Notes Template

# v2.0.0 — 2026-03-20

## ⚠ Breaking Changes

Changes that require action from consumers before upgrading.

- **Auth: API key authentication removed** — All endpoints now require OAuth2
  Bearer tokens. API keys are no longer accepted. See [Migration Guide](./docs/migrate-v2.md).
- **Config: `DATABASE_URL` renamed to `APP_DATABASE_URL`** — Update environment
  variables in all deployment environments.

### Migration Guide

Step-by-step instructions for upgrading from v1.x:

1. Replace `X-API-Key` header with `Authorization: Bearer <token>` in all clients.
2. Rename `DATABASE_URL` → `APP_DATABASE_URL` in `.env` and deployment config.
3. Run `python -m myapp.migrate_v2` to update stored data formats.

## Features & Fixes

Backward-compatible additions and corrections.

### Added
- User search endpoint with fuzzy matching (`GET /api/users/search?q=`) (#142)
- Dashboard export to CSV (#156)

### Fixed
- Token refresh no longer fails silently when the session cookie is expired (#138)
- Chart tooltips render correctly in dark mode (#161)

### Deprecated
- `GET /api/users?name=` query parameter — use `/api/users/search?q=` instead.
  Will be removed in v3.0.0.

## Internal

Changes with no user-facing impact. No action required.

- Upgraded FastAPI 0.109 → 0.115
- Added integration tests for payment webhook handler
- Reduced Docker image size from 340MB → 120MB via multi-stage build
- Migrated CI from GitHub Actions to Harness Drone

Deriving Release Notes from Conventional Commits

When using conventional commits (see git-workflow skill), map commit types to release note tiers:

| Commit type | Release note tier | Section | |-------------|-------------------|---------| | feat | Functional | Added | | fix | Functional | Fixed | | BREAKING CHANGE footer or ! suffix | Breaking | ⚠ Breaking Changes | | deprecated in body | Functional | Deprecated | | perf | Non-Functional (or Functional if user-visible) | Internal or Changed | | refactor, build, ci, test, chore | Non-Functional | Internal | | docs | Non-Functional (or Functional if user-facing docs) | Internal |

Writing Rules

• Write from the consumer's perspective — describe what changed for them, not what code changed.
• Breaking changes always come first — they demand immediate attention.
• Every breaking change must include a migration path — what to do, not just what broke.
• Deprecations must state when removal will happen (version or date).
• Link to issues or PRs for traceability: (#142).
• Keep entries to one line unless a migration guide is needed.
• Use imperative mood, present tense: "Add user search" not "Added user search endpoint".

Quality Gate

Before publishing release notes, verify:

| Check | Question | |-------|----------| | Complete | Does every merged PR appear in a tier? | | Categorized | Is each change in the correct tier (breaking / functional / non-functional)? | | Actionable | Does every breaking change have a migration path? | | Traceable | Does every entry link to an issue or PR? | | Consumer-readable | Would someone outside the team understand each entry? |

---

Changelog

Maintain a CHANGELOG.md following the Keep a Changelog format (see git-workflow skill for full template). The changelog is the cumulative history of all release notes.

Changelog Rules

• Group by release version with a date: ## [1.5.0] - 2026-03-20.
• Keep an [Unreleased] section at the top for in-progress changes.
• Use the same three-tier classification (Breaking / Functional / Non-Functional) as release notes.
• Never edit entries for past releases — corrections go in a new release.

---

Release Checklist

Run through before every release:

| Step | Check | |------|-------| | Tests pass | All tests green on the release commit (see testing skill) | | Lint clean | No lint or format violations | | Version bumped | Version source file updated to the new version | | Changelog updated | [Unreleased] entries moved under the new version heading | | No secrets | No credentials, keys, or tokens in the release | | Dependencies audited | pip audit / npm audit clean (see security skill) | | Breaking changes documented | Migration guide written if MAJOR bump | | Tag created | Annotated tag matches the version: v1.5.0 | | CI green on tag | Release pipeline triggered and completed successfully |

---

CI/CD Integration

Tag-Triggered Release Pipeline

Configure CI to build and publish only when a semver tag is pushed (see cicd skill for full pipeline patterns):

---
kind: pipeline
name: release
trigger:
  event: [tag]
  ref: ["refs/tags/v*"]

steps:
  - name: validate-tag
    image: alpine:3.19
    commands:
      - |
        TAG="${DRONE_TAG}"
        if ! echo "$TAG" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$'; then
          echo "ERROR: Tag '$TAG' does not match semver format (vMAJOR.MINOR.PATCH)"
          exit 1
        fi
        echo "Valid semver tag: $TAG"

  - name: test
    image: python:3.12-slim
    commands:
      - pip install pytest
      - pytest -v --tb=short
    depends_on: [validate-tag]

  - name: build-and-publish
    image: plugins/docker
    settings:
      repo: ${DRONE_REPO_OWNER}/my-service
      tags:
        - latest
        - ${DRONE_TAG}
        - ${DRONE_TAG##v}
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password
    depends_on: [test]

Semver-Aware Docker Tags

Tag images with both the v-prefixed tag and the bare version:

| Git tag | Docker tags | |---------|-------------| | v1.5.0 | latest, v1.5.0, 1.5.0 | | v2.0.0-beta.1 | v2.0.0-beta.1, 2.0.0-beta.1 (not latest) |

Never tag pre-releases as latest — only stable releases.

Automated Version Bumping

For projects that derive version from git tags at build time:

# Get the latest version from git tags
VERSION=$(git describe --tags --abbrev=0 | sed 's/^v//')
echo "Building version: $VERSION"

For projects with a version file, use CI to validate that the tag matches the file:

FILE_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
TAG_VERSION="${DRONE_TAG#v}"
if [ "$FILE_VERSION" != "$TAG_VERSION" ]; then
  echo "ERROR: pyproject.toml version ($FILE_VERSION) != tag ($TAG_VERSION)"
  exit 1
fi

---

Release Cadence

| Model | When to use | Trade-offs | |-------|-------------|------------| | Release when ready | Most projects, especially small teams | Simple, flexible, no artificial deadlines | | Scheduled releases | Products with external consumers or SLAs | Predictable for consumers, may delay features | | Continuous delivery | Mature CI/CD, high test confidence | Fastest feedback, requires strong automation |

For most projects, release when ready is the right default. Ship when the feature set is coherent and tests pass.

---

Anti-Patterns

| Anti-pattern | Why it's bad | Do this instead | |--------------|-------------|-----------------| | Bumping MAJOR for every change | Consumers can't trust version stability | Reserve MAJOR for actual breaking changes | | Skipping versions (1.0.0 → 1.5.0) | Confusing, implies missing releases | Increment sequentially | | Tagging without tests passing | Broken releases erode trust | CI must validate before publish | | Manual changelog from memory | Incomplete, error-prone | Derive from conventional commits | | Version in multiple files | Drift between sources | Single source of truth + build-time injection | | Deleting and re-creating tags | Breaks downstream caches and references | Bad release → new PATCH release | | No changelog | Consumers can't assess upgrade risk | Maintain CHANGELOG.md for every release | | v0.x.y forever | Signals instability, discourages adoption | Promote to 1.0.0 when API is stable |