Bump Version Skill

Update package versions and changelog across the workspace using semantic versioning.

Purpose

Bump package versions in the uv workspace by updating all pyproject.toml files (root workspace, tde, and tda packages) and CHANGELOG.md simultaneously. This ensures all packages maintain version synchronization and changelog is updated for the release.

When to Use

Use this skill when:

• User requests to "bump the version"
• User asks to "update version to patch/minor/major"
• User wants to increment the package version
• Version needs to be updated before a release

Usage

Execute the bump_version.py script from the workspace root with the bump type:

python .claude/skills/bump-version/scripts/bump_version.py <major|minor|patch>

Bump Types

• major: Increment major version (1.0.0 → 2.0.0), reset minor and patch to 0
• minor: Increment minor version (1.0.0 → 1.1.0), reset patch to 0
• patch: Increment patch version (1.0.0 → 1.0.1)

What Gets Updated

The script updates:

1. Root pyproject.toml (workspace) - version field
2. src/tde/pyproject.toml (Tech-Debt Extractor package) - version field
3. src/tda/pyproject.toml (Tech-Debt Agent package) - version field
4. CHANGELOG.md - Creates new version section from [Unreleased] content

All pyproject.toml files are kept in sync with the same version number. The CHANGELOG.md has the [Unreleased] section converted to a dated version section, with a new empty [Unreleased] section added above it.

Examples

Bump patch version (0.1.0 → 0.1.1):

python .claude/skills/bump-version/scripts/bump_version.py patch

Bump minor version (0.1.0 → 0.2.0):

python .claude/skills/bump-version/scripts/bump_version.py minor

Bump major version (0.1.0 → 1.0.0):

python .claude/skills/bump-version/scripts/bump_version.py major

Workflow

1. Before bumping: Ensure CHANGELOG.md has changes documented in the [Unreleased] section

   • Add entries under appropriate categories (Added, Changed, Fixed, etc.)
   • Follow Keep a Changelog format

2. Ask user for bump type: Use AskUserQuestion tool to clarify which version bump to perform

   AskUserQuestion(
       questions=[{
           "question": "Which version bump should be performed?",
           "header": "Version bump",
           "options": [
               {"label": "Patch", "description": "Bug fixes and minor changes (0.1.1 → 0.1.2)"},
               {"label": "Minor", "description": "New features, backward compatible (0.1.1 → 0.2.0)"},
               {"label": "Major", "description": "Breaking changes (0.1.1 → 1.0.0)"}
           ],
           "multiSelect": false
       }]
   )
   

3. Execute script: Run with the user-confirmed bump type

   python .claude/skills/bump-version/scripts/bump_version.py <patch|minor|major>
   

4. Verify changes: Check that all files were updated correctly

   • All three pyproject.toml files should have the new version
   • CHANGELOG.md should have a new dated section for the version
   • New empty [Unreleased] section should be at the top

5. Update changelog with recent changes: After the version bump, automatically update the [Unreleased] section

   • Use git status and git diff --stat to review what changed in the repository
   • Check for new files in .claude/ or other directories
   • Update CHANGELOG.md [Unreleased] section with appropriate entries under categories:
     • Added: New files, features, or functionality
     • Changed: Modifications to existing functionality
     • Removed: Deleted files or removed functionality
   • Document the changes clearly and concisely
   • Example entries:
     • - Claude Code settings configuration (.claude/settings.json)
     • - Reorganized bump-version skill to follow Claude Code structure

6. Provide instructions to user: Display the following instructions for completing the release:

   To complete the version bump:
   
   1. Review the changes:
      git status
      git diff CHANGELOG.md
   
   2. Commit the version bump:
      git add .
      git commit -m "chore: bump version to X.Y.Z"
   
   3. Create a git tag:
      git tag vX.Y.Z
   
   4. Push changes and tag:
      git push origin main
      git push origin vX.Y.Z
   

   Replace X.Y.Z with the actual version number that was bumped to.

Changelog Management

The CHANGELOG.md follows Keep a Changelog format:

• [Unreleased]: Work-in-progress changes (gets converted to version section when bumping)
• Categories: Added, Changed, Deprecated, Removed, Fixed, Security

When bumping a version, the script:

1. Finds the [Unreleased] section
2. Converts it to a dated version section (e.g., ## [0.1.2] - 2025-01-10)
3. Adds a new empty [Unreleased] section at the top

Important: Always document changes in [Unreleased] before bumping. The bump process doesn't add changelog entries—it only converts existing unreleased entries into a versioned section.