From python-package
This skill should be used when the user is choosing a versioning scheme, writing a changelog, preparing a release, configuring Towncrier or python-semantic-release, planning deprecations, managing major version migrations, or setting up version single-source-of-truth. Covers SemVer, CalVer, PEP 440, Keep a Changelog, Towncrier, Conventional Commits, deprecation strategy, pre-release publishing, and release automation.
npx claudepluginhub oborchers/fractional-cto --plugin python-packageThis skill uses the workspace's default tool permissions.
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 trea...
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
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.
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.
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.
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.
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.
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.
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()).
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.
Follow this end-to-end workflow for every release:
towncrier build --version 2.1.0git tag v2.1.0 && git push origin main --tagsrelease eventFor 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.
# 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
When reviewing code for versioning, releases, and changelogs:
MAJOR.MINOR.PATCH) with correct segment bumped for the change type1.0.0a1, not 1.0.0-alpha.1)_version.py, or static in pyproject.toml)CHANGELOG.md follows Keep a Changelog format with entries grouped by Added/Changed/Deprecated/Removed/Fixed/Securitywarnings.warn() with DeprecationWarning, stacklevel=2, the removal version, and the alternativev prefix (v2.1.0) and PEP 440 format for pre-releases (v2.0.0a1)