Release Management

Release management coordinates when and how Python services ship: versioning rules, release trains, change approvals, and communication. Good release hygiene makes rollback credible and stakeholders predictable.

Recipe

Quick-reference recipe card - copy-paste ready.

# Release: orders-api v2026.07.09
 
## Artifacts
- Image: `orders-api:sha-9f2a1bc` (Python 3.14.0)
- Wheel (internal lib): `acme-billing==2.4.0`
 
## Migrations
- alembic `20260709_add_tax_code` (expand, backward compatible)
 
## Rollback
- `kubectl rollout undo` to `sha-7c1b2aa`
- Pause `billing` workers if queue depth > 5k
 
## Stakeholders
- #releases, support macro updated

When to reach for this:

• Multiple squads ship the same platform weekly
• Customer-facing API with SLA commitments
• Shared libraries consumed by many internal services
• Compliance requires change records

Working Example

"""version_bump.py - automate service version metadata for release notes."""
from __future__ import annotations
 
import subprocess
from dataclasses import dataclass
from datetime import date
 
 
@dataclass(frozen=True)
class ReleaseMetadata:
    service: str
    git_sha: str
    python: str
    release_date: date
 
 
def git_short_sha() -> str:
    return subprocess.check_output(["git", "rev-parse", "--short", "HEAD"], text=True).strip()
 
 
def build_release_notes(meta: ReleaseMetadata, changes: list[str]) -> str:
    lines = [
        f"# {meta.service} release {meta.release_date.isoformat()}",
        f"- Git: `{meta.git_sha}`",
        f"- Python: {meta.python}",
        "",
        "## Changes",
    ]
    lines.extend(f"- {c}" for c in changes)
    return "\n".join(lines)
 
 
if __name__ == "__main__":
    meta = ReleaseMetadata("orders-api", git_short_sha(), "3.14.0", date.today())
    print(build_release_notes(meta, ["Add tax code field (nullable)", "Fix Celery retry backoff"]))

What this demonstrates:

• Release notes tie customer-visible changes to git SHA
• Migration risk called out explicitly for operators
• Rollback steps live beside forward deploy instructions
• Automation reduces copy-paste errors in #releases posts

Deep Dive

How It Works

• Release train - Fixed cadence (e.g., Tue/Thu) with cutoff for merge.
• Semver - Libraries use MAJOR.MINOR.PATCH; breaking changes bump major.
• Change management - CAB review for destructive migrations or cross-service flag days.
• Artifact immutability - Build once, promote through environments.
• Communication - Support macros and status templates updated before prod promote.

Release Types

Python Notes

# pyproject.toml - library versioning
[project]
name = "acme-billing"
version = "2.4.0"
requires-python = ">=3.13"

Gotchas

• Floating :latest in prod - Rollback ambiguity. Fix: Immutable tags with SHA; record in deploy annotation.
• Release notes without migration section - Ops surprised by locks. Fix: Alembic revision IDs mandatory in notes.
• Train without cutoff - Last-minute risky merges. Fix: Code freeze 24h before prod with exception process.
• Different Python in worker vs API - Subtle pickle/schema bugs. Fix: Single base image policy per release.
• Skipping stakeholder notification - Support blindsided. Fix: #releases post is a release gate, not optional.

Alternatives

FAQs

Related

• Rollback Strategies - when trains go wrong
• Environments & Config Promotion - promote path
• DORA Metrics - measure delivery health
• CI/CD Pipelines - automation
• Packaging & Publishing - library releases

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.