Python Release Manager

Execute a complete pre-release workflow for Python packages using uv and ruff. This command automates version calculation, changelog updates, and tag creation.

Arguments

• $ARGUMENTS - Optional version override (e.g., 1.0.0). If not provided, version is calculated from changelog entries.

Workflow

Execute these 9 steps in order. Fail fast: Stop immediately if any verification step fails.

Step 1: Pre-flight Checks

Run these checks and stop if any fail:

# Check current branch
git branch --show-current

• Must be on `main` branch. If not, stop and report: "Release must be run from the main branch. Currently on: {branch}"

# Check for uncommitted changes
git status --porcelain

• Must have clean working directory. If output is not empty, stop and report: "Working directory has uncommitted changes. Please commit or stash them first."

# Pull latest changes
git pull origin main

• Report any merge conflicts and stop if they occur.

Step 2: Run Tests

Execute the test suite:

uv run pytest

• If tests fail, stop and report the failure output
• If tests pass, report: "All tests passed"

Step 3: Run Linting

Execute linting checks:

uv run ruff check

uv run ruff format --check

• If either command fails, stop and report the issues
• If both pass, report: "Linting and formatting checks passed"

Step 4: Verify Build

Build the package:

uv build

• If build fails, stop and report the error
• If build succeeds, report: "Package builds successfully"

Step 5: Changelog Update Check

All verification checks have passed. Before calculating the version, offer to run the changelog-manager agent to ensure the [Unreleased] section is up-to-date.

Prompt the user:

Would you like to run the changelog-manager to update CHANGELOG.md before proceeding?

>

This will analyze git commits since the last release and suggest new changelog entries.

• "Yes, update changelog first (Recommended)"
• "No, continue with existing changelog"

If user selects "Yes":

Spawn a changelog-manager sub-agent with the prompt: "Analyze commits since the last release and update the CHANGELOG.md [Unreleased] section"

Wait for the agent to complete before proceeding.

If user selects "No":

Continue to Step 6 (Calculate Version) without running the changelog-manager.

Step 6: Calculate Version

#### 6.1 Read CHANGELOG.md

Read CHANGELOG.md and parse its structure. Look for:

• The ## [Unreleased] section and its subsections
• The most recent versioned section (e.g., ## [0.1.0]) to get the current version

#### 6.2 Analyze Change Types

Count entries under [Unreleased] by subsection:

• ### Added - New features
• ### Changed - Changes to existing functionality
• ### Deprecated - Features marked for removal
• ### Removed - Removed features (breaking change)
• ### Fixed - Bug fixes
• ### Security - Security fixes

#### 6.3 Calculate Suggested Version

Apply semantic versioning rules to the current version (MAJOR.MINOR.PATCH):

#### 6.4 Handle Edge Cases

• No unreleased changes: Warn user "No entries found under [Unreleased]. Are you sure you want to release?"
• Missing CHANGELOG.md: Stop and report "CHANGELOG.md not found. Please create one following Keep a Changelog format."
• Version override provided: Use $ARGUMENTS as the version instead of calculating

#### 6.5 User Confirmation

Prompt the user to confirm the version:

Based on changelog analysis: - Found: {count} Added, {count} Changed, {count} Fixed, {count} Removed entries - Current version: {current} - Suggested version: {suggested} ({bump_type} bump)

>

Confirm version or provide override:

• "Confirm {suggested}"
• "Enter different version"

Step 7: Update CHANGELOG.md

#### 7.1 Get Repository URL

Read pyproject.toml and extract the repository URL from [project.urls]:

• Check keys: Repository, repository, Source, source, Homepage, homepage
• Extract the GitHub/GitLab URL

If no repository URL found, warn but continue (comparison links will be omitted).

#### 7.2 Update Changelog Content

Transform the changelog:

Before:

## [Unreleased]

### Added
- New feature X

## [0.1.0] - 2024-01-15

### Added
- Initial release

[Unreleased]: https://github.com/user/repo/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/user/repo/releases/tag/v0.1.0

After (releasing 0.2.0):

## [Unreleased]

## [0.2.0] - {today's date YYYY-MM-DD}

### Added
- New feature X

## [0.1.0] - 2024-01-15

### Added
- Initial release

[Unreleased]: https://github.com/user/repo/compare/v0.2.0...HEAD
[0.2.0]: https://github.com/user/repo/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/user/repo/releases/tag/v0.1.0

#### 7.3 Write Updated CHANGELOG.md

Update CHANGELOG.md with the transformed content.

Step 8: Commit Changelog

Stage and commit the changelog update:

git add CHANGELOG.md

git commit -m "docs: update changelog for v{version}"

git push origin main

Report: "Changelog committed and pushed"

Step 9: Create and Push Tag

Create an annotated tag and push it:

git tag -a v{version} -m "Release v{version}"

git push origin v{version}

#### Final Report

Report success with details:

Release v{version} completed successfully!

- Changelog updated: CHANGELOG.md
- Tag created: v{version}
- Tag URL: {repository_url}/releases/tag/v{version}

Next steps:
- GitHub/GitLab will create a release from the tag
- Publish to PyPI if configured in CI

Error Recovery

If any step fails after Step 6 (version confirmation):

• Report which step failed and the error
• Provide commands to manually complete or rollback:
• git checkout CHANGELOG.md - Revert changelog changes
• git tag -d v{version} - Delete local tag if created
• git push origin :refs/tags/v{version} - Delete remote tag if pushed

Integration Notes

What this component does: Orchestrates a complete Python package release workflow: pre-flight checks (branch, clean working directory), test suite, linting, build verification, changelog analysis, semantic version calculation, changelog update, commit, and tag creation. Capabilities needed: Shell execution (git, uv, ruff commands), file reading/editing (CHANGELOG.md, pyproject.toml), user interaction (version confirmation, changelog update prompt), sub-agent spawning (changelog-manager). Adaptation guidance: The workflow assumes uv for Python package management and ruff for linting. Adapt tool commands if using different tooling. The changelog-manager sub-agent handles changelog entry generation. Sub-agent capabilities: The changelog-manager agent analyzes git history and updates CHANGELOG.md entries. It needs shell execution (git commands), file reading/editing, and user interaction.