managing-python-releases
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.
How do I install this agent skill?
npx skills add https://github.com/wdm0006/python-skills --skill managing-python-releasesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides safe guidelines and automation scripts for Python library release management, including semantic versioning, changelog maintenance, and CI/CD workflows. No security issues were detected.
- Socketwarn
1 alert: gptAnomaly
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
2/2 files flagged
What does this agent skill do?
Python 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
A tag-triggered workflow builds with uv and publishes to PyPI via trusted
publishing (no stored token). The full canonical pipeline — TestPyPI dry run,
GitHub release, and the release runbook — is in AUTOMATION.md.
# .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. Deprecating
parameters, classes, or whole modules — and the migration-guide template — is
covered in MIGRATION.md.
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()
Release Process
# 1. Update CHANGELOG.md (move Unreleased to version)
# 2. Bump version in pyproject.toml and __init__.py
# 3. Commit and tag
git commit -am "Release v1.2.0"
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags
# 4. CI publishes automatically
For detailed workflows, see:
- AUTOMATION.md - Version bump scripts
- MIGRATION.md - Migration guide template
Checklist
Before Release:
- [ ] All tests pass
- [ ] CHANGELOG updated
- [ ] Version bumped
- [ ] Documentation current
After Release:
- [ ] PyPI shows new version
- [ ] pip install works
- [ ] GitHub release created
- [ ] Docs updated
Learn More
This skill is based on the Maintenance section of the Guide to Developing High-Quality Python Libraries by Will McGinnis. See these posts for deeper coverage:
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/wdm0006/python-skills/managing-python-releases">View managing-python-releases on skillZs</a>