oborchers/versioning-releases

Follow SemVer Strictly and Automate Every Release

A version number is a contract with every user who pins against your package. Breaking that contract -- shipping a behavioral change in a PATCH bump, removing a function without a deprecation cycle, or publishing a non-PEP-440 tag -- erodes trust and causes silent failures across the dependency graph. The best Python packages (Pydantic, pytest, Django) treat versioning as seriously as they treat their API surface.

Pydantic's v1-to-v2 migration is the most instructive case study: systematic renaming with a model_ prefix, a compatibility namespace (pydantic.v1), an automated codemod (bump-pydantic), and a 12-month support window for v1. That level of discipline is what users expect from a well-maintained package.

SemVer Decision Guide

Use MAJOR.MINOR.PATCH for every Python library. Increment the correct segment based on what changed, not how much code was touched.

| Change Type | Bump | Example | |-------------|------|---------| | Remove public function/class | MAJOR | Delete Client.send() | | Change function signature (required args) | MAJOR | def get(url) becomes def get(url, timeout) | | Change return type or default behavior | MAJOR | Return dict instead of list | | Rename public attribute/method | MAJOR | .json() becomes .model_dump() | | Drop Python version support | MAJOR | Drop Python 3.9 | | Add new public function/class | MINOR | New Client.stream() method | | Add optional parameter with default | MINOR | def get(url, *, timeout=30) | | Deprecate without removing | MINOR | Add deprecation warning | | Fix incorrect behavior | PATCH | Fix off-by-one in pagination | | Internal refactor (no API change) | PATCH | Restructure _internal/ |

The hardest calls are behavioral changes. If parse("2024-01-01") returned a date and now returns a datetime, the signature is identical but downstream code breaks. This is a MAJOR change.

The 0.x Convention

SemVer allows anything to change at 0.y.z. In practice, treat MINOR as "breaking" and PATCH as "non-breaking" during 0.x development. Document this convention in your README. Graduate to 1.0 when the API is stable. FastAPI (0.115.x) and httpx (0.28.x) have stayed at 0.x for years -- if you have significant adoption, either go to 1.0 or explicitly document your 0.x contract.

CalVer: When to Use It

Use CalVer only for tools where "backward compatibility" is meaningless or always maintained: formatters (Black 24.10.0), packaging tools (pip 24.3.1), platforms. For libraries with downstream dependents, always use SemVer.

PEP 440 Compliance

PyPI and pip enforce PEP 440. Non-compliant version strings are rejected.

| Concept | SemVer Syntax | PEP 440 Syntax | |---------|---------------|----------------| | Pre-release alpha | 1.0.0-alpha.1 | 1.0.0a1 | | Pre-release beta | 1.0.0-beta.2 | 1.0.0b2 | | Release candidate | 1.0.0-rc.1 | 1.0.0rc1 | | Post-release | Not defined | 1.0.0.post1 | | Dev release | Not defined | 1.0.0.dev1 |

Ordering: 1.0.0.dev1 < 1.0.0a1 < 1.0.0b1 < 1.0.0rc1 < 1.0.0 < 1.0.0.post1

Pre-releases are never installed by default. Users must pass --pre or pin an exact pre-release version. Always use PEP 440 format for tags: v1.0.0a1, not v1.0.0-alpha.1.

Changelog: Keep a Changelog + Towncrier

Maintain a CHANGELOG.md following the Keep a Changelog format. Group entries by type, write from the user's perspective, and link each version to its diff.

| Section | When to Use | SemVer Signal | |---------|------------|---------------| | Added | New features | MINOR | | Changed | Changes to existing functionality | MINOR or MAJOR | | Deprecated | Features marked for future removal | MINOR | | Removed | Features removed | MAJOR | | Fixed | Bug fixes | PATCH | | Security | Vulnerability fixes | PATCH |

| Bad Entry | Good Entry | |-----------|------------| | "Refactored internal connection pooling module" | "Fixed connection pool not releasing connections on timeout" | | "Updated CI matrix" | (Do not include -- not user-facing) |

Use Towncrier for multi-contributor projects. Each PR adds a news fragment (changes/423.bugfix.md), CI enforces fragment presence, and towncrier build compiles them at release time. No merge conflicts on the changelog. Used by pip, pytest, attrs, Twisted.

Version Single Source of Truth

Define the version in exactly one place. Prefer git-tag-derived versioning for open source.

| Scenario | Approach | |----------|----------| | Open source library | hatch-vcs or setuptools-scm (git tag as source, generates _version.py) | | Internal/private package | Static version in pyproject.toml | | Simple script/tool | __version__ in source |

For runtime access, import from the generated _version.py file (see project-structure skill for the full rationale on why _version.py is preferred over importlib.metadata.version()).

Deprecation Strategy

Never remove a public API without at least one release cycle of deprecation warnings. Include the removal version, the alternative, and a migration link in every warning message.

warnings.warn(
    "old_function() is deprecated since v2.0 and will be removed in v3.0. "
    "Use new_function() instead. "
    "See https://mylib.dev/migration for details.",
    DeprecationWarning,
    stacklevel=2,  # CRITICAL: points warning to the caller's code
)

Always use stacklevel=2. Without it, the warning points to the line inside your library, not the user's code that called the deprecated function. For wrapped or decorated functions, use stacklevel=3 or higher.

| User Base | Minimum Deprecation Period | |-----------|--------------------------| | Small (< 1K downloads/month) | 1 minor version (3+ months) | | Medium (1K-100K downloads/month) | 2 minor versions (6+ months) | | Large (100K+ downloads/month) | 1 full major version (12+ months) |

Test that deprecation warnings fire correctly with pytest.warns(DeprecationWarning, match=...) and that deprecated functions still work until removal.

Release Process

Follow this end-to-end workflow for every release:

1. Compile changelog fragments: towncrier build --version 2.1.0
2. Tag the release: git tag v2.1.0 && git push origin main --tags
3. Create a GitHub Release from the tag
4. CI builds sdist + wheel on the release event
5. Publish to PyPI via trusted publishing (OIDC, no API tokens)

For major versions, publish pre-releases first: v2.0.0a1 (alpha) then v2.0.0b1 (beta) then v2.0.0rc1 (release candidate) then v2.0.0 (stable). Allow 2-4 weeks between stages for ecosystem testing. Pydantic v2 used a 2-month pre-release window.

Reference Configuration

# pyproject.toml -- Towncrier configuration
[tool.towncrier]
package = "my_package"
directory = "changes"
filename = "CHANGELOG.md"
title_format = "## [{version}] - {project_date}"
issue_format = "[#{issue}](https://github.com/org/repo/issues/{issue})"
underlines = ["", "", ""]

[[tool.towncrier.type]]
directory = "feature"
name = "Added"
showcontent = true

[[tool.towncrier.type]]
directory = "bugfix"
name = "Fixed"
showcontent = true

[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecated"
showcontent = true

[[tool.towncrier.type]]
directory = "removal"
name = "Removed"
showcontent = true

[[tool.towncrier.type]]
directory = "change"
name = "Changed"
showcontent = true

[[tool.towncrier.type]]
directory = "security"
name = "Security"
showcontent = true

Review Checklist

When reviewing code for versioning, releases, and changelogs:

• [ ] Version follows SemVer (MAJOR.MINOR.PATCH) with correct segment bumped for the change type
• [ ] All version strings comply with PEP 440 (use 1.0.0a1, not 1.0.0-alpha.1)
• [ ] Version is derived from a single source of truth (git tag via hatch-vcs/setuptools-scm generating _version.py, or static in pyproject.toml)
• [ ] CHANGELOG.md follows Keep a Changelog format with entries grouped by Added/Changed/Deprecated/Removed/Fixed/Security
• [ ] Changelog entries are written from the user's perspective, not the developer's
• [ ] Every PR includes a Towncrier news fragment (or equivalent) for user-facing changes
• [ ] Deprecation warnings use warnings.warn() with DeprecationWarning, stacklevel=2, the removal version, and the alternative
• [ ] Deprecated functions are tested to verify both the warning and continued functionality
• [ ] No public API is removed without at least one release cycle of deprecation warnings
• [ ] Git tags use the v prefix (v2.1.0) and PEP 440 format for pre-releases (v2.0.0a1)
• [ ] Major version releases are preceded by alpha/beta/RC pre-releases on PyPI
• [ ] CI publishes via trusted publishing (OIDC) on the GitHub Release event
• [ ] Migration guides exist for every breaking change, mapping old API to new equivalents