- name
- managing-python-releases
- description
- Manages Python library releases including semantic versioning, changelog maintenance (Keep a Changelog format), release automation with GitHub Actions, and deprecation workflows. Use when planning releases, writing changelogs, automating release pipelines, or communicating breaking changes.
Release Management
Semantic Versioning
MAJOR.MINOR.PATCH (e.g., 1.2.3)
PATCH: Bug fixes, no API changes
MINOR: New features, backward compatible
MAJOR: Breaking changes
Changelog Format (Keep a Changelog)
# Changelog
## [Unreleased]
### Added
- New `batch_encode()` function
## [1.2.0] - 2024-03-15
### Added
- Support for custom formats (#123)
### Fixed
- Edge case at -180 longitude (#145)
### Deprecated
- `old_function()` - use `new_function()` instead
[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/releases/tag/v1.2.0
Categories: Added, Changed, Deprecated, Removed, Fixed, Security
Version in Code
# src/package/__init__.py
__version__ = "1.2.3"
# Or use importlib.metadata
from importlib.metadata import version
__version__ = version("my-package")
GitHub Actions Release (PyPI example)
A tag-triggered workflow builds and publishes to a registry via trusted publishing (no stored token) is the general shape — swap the publish step for whatever registry the project actually uses (PyPI, npm, crates.io, ...):
# .github/workflows/release.yml
on:
push:
tags: ['v*']
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write # create the GitHub release
id-token: write # trusted publishing (no token)
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
- run: uv build
- uses: softprops/action-gh-release@v2
with:
files: dist/*
- uses: pypa/gh-action-pypi-publish@release/v1
Deprecation Process
Warn with stacklevel=2 so the message points at the caller.
import warnings
def old_function():
"""Deprecated: Use new_function() instead."""
warnings.warn(
"old_function() deprecated, will be removed in 2.0.0",
DeprecationWarning,
stacklevel=2,
)
return new_function()