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/kajisho5/ffmpeg-skill --skill managing-python-releasesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard guidelines for Python release management, including semantic versioning, changelog maintenance, and GitHub Actions automation. It follows security best practices such as trusted publishing for PyPI. No malicious behavior was detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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()
Release Process
# 1. Update CHANGELOG.md (move Unreleased to version)
# 2. Bump version in the project manifest
# 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 (if automated) or publish manually
Checklist
Before Release:
- [ ] All tests pass
- [ ] CHANGELOG updated
- [ ] Version bumped
- [ ] Documentation current
After Release:
- [ ] Registry shows new version
- [ ] A fresh install actually works (not just that the tag/publish succeeded)
- [ ] GitHub release created
- [ ] Docs updated
Note for this repository (ffmpeg-skill)
CHANGELOG.md here keeps a ## Unreleased section and one ## X.Y.Z section
per version (no dates in the headings since the releases became automatic).
Two real differences from the generic PyPI example:
- Releases are automatic; nothing is cut by hand.
.github/workflows/release.ymlruns on every push tomain: it resolves the next version from the merged PRs' labels (.github/scripts/resolve_version.py), bumpspackage.json, the plugin manifests,server.json,docs/contract.mdanddocs/roadmap.md, moves## Unreleasedinto the new version's section, pushes that commit, tags it, creates the GitHub Release, publishes to npm with provenance, thepluginbranch and the MCP Registry entry. A PR writes its notes under## Unreleasedand never bumps a version, except a major, which is a hand bump in a PR. A version that was tagged but did not reach npm is finished by the workflow'srecoverjob (CONTRIBUTING.md, "Pull requests"), never by a localnpm publish. (The 0.10.0 release was the last one done by hand, before the workflow existed.) - The registry is npm, not PyPI, and there is no
__version__in code —scripts/_contract.py'sskill_version()anddoctor'sversionfield both readpackage.jsondirectly (see this repo's ownconcurrent-branchesandbuild-artifactsskill notes for the related merge-conflict and publish-verification patterns this touches).
Source: wdm0006/python-skills (MIT).
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/kajisho5/ffmpeg-skill/managing-python-releases">View managing-python-releases on skillZs</a>