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:

When to Bump What

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.

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:

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:

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:

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:

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:

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

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

Anti-Patterns