Release Skill

Guide the user through the process of releasing a new version of the ai-drift package to PyPI.

Process

1. Determine bump type: Ask the user which type of version bump to perform:

   • major - Breaking changes (e.g., 1.0.0 → 2.0.0)
   • minor - New features, backward compatible (e.g., 0.1.0 → 0.2.0)
   • patch - Bug fixes, backward compatible (e.g., 0.1.1 → 0.1.2)

2. MANDATORY - Run bump-version script: Execute ./scripts/bump-version.sh {bump_type} --no-changelog to:

   • Update version in pyproject.toml
   • Capture the new version number from stdout
   • YOU MUST USE THIS SCRIPT - DO NOT MANUALLY EDIT pyproject.toml

3. Show version change: Display the version change to the user (old → new)

4. Ask for changelog description: Prompt the user to describe the changes in this release.

   IMPORTANT: Only include changes to the actual package code (src/, tests/, scripts/, pyproject.toml, etc.). DO NOT include:

   • Changes to .drift.yaml or .drift_rules.yaml (local config)
   • Changes to .claude/ directory (local config)
   • Changes to documentation files (docs/, README.md, CLAUDE.md)
   • Other local/project configuration changes

   Only include:

   • New features added to the package
   • Bugs fixed in the package code
   • Breaking changes (if major bump)
   • Changes to CLI options or behavior

   Format: Single line or bullet points

5. MANDATORY - Update changelog: Run ./scripts/update-changelog.sh {version} "{description}" to add the entry to CHANGELOG.md

   • YOU MUST USE THIS SCRIPT - DO NOT MANUALLY EDIT CHANGELOG.md

6. Show git diff: Display the changes made by running git diff so the user can review

7. Commit changes: Create a commit with the version bump:

   git add .
   git commit -m "chore: release v{version}"
   

8. Create git tag: Create an annotated tag for the release:

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

9. Confirm push: Ask the user if they want to push the commit and tag now.

10. Push if confirmed: If the user confirms, push both the commit and tags:

    git push && git push --tags
    

11. Inform about automation: Let the user know that pushing the tag will automatically trigger GitHub Actions to:

    • Verify CI tests passed on the tagged commit
    • Build distribution packages (wheel and source)
    • Publish to PyPI using trusted publishing
    • Create a GitHub Release with:
      • Changelog from CHANGELOG.md
      • Installation instructions
      • Distribution files attached
    • They can monitor progress in the Actions tab: https://github.com/jarosser06/drift/actions

12. Manual alternative: Inform that if they prefer to publish manually instead:

    • Wait for the tag push to complete
    • Cancel the GitHub Actions workflow if it starts
    • Run ./distro.sh build --clean
    • Run ./distro.sh push --test for TestPyPI (optional)
    • Run ./distro.sh push for production PyPI

Important Notes

• The version format is MAJOR.MINOR.PATCH (SemVer)
• Tags use the format v{version} (e.g., v0.2.0)
• The bump-version script updates pyproject.toml automatically
• Always verify the git diff before committing
• PyPI does not allow replacing versions - must bump to publish updates
• The PyPI package page will automatically update with new README content
• GitHub Actions uses trusted publishing to PyPI (no tokens needed)
  • Configured at: https://pypi.org/manage/project/ai-drift/settings/publishing/
  • Adds the GitHub Actions workflow as a trusted publisher
• The release workflow will fail if CI tests didn't pass on the tagged commit

Example Flow

User: /release
Assistant: Which type of version bump do you want to perform?
- major (breaking changes)
- minor (new features)
- patch (bug fixes)

User: minor
Assistant: [Runs ./scripts/bump-version.sh minor --no-changelog]
Bumping version: 0.1.1 → 0.2.0

Please describe the changes in this release:

User: Added support for X, fixed bug in Y
Assistant: [Runs ./scripts/update-changelog.sh 0.2.0 "Added support for X, fixed bug in Y"]
[Shows git diff]

Ready to commit and tag? (yes/no)

User: yes
Assistant: [Creates commit and tag]
Do you want to push now? (yes/no)

User: yes
Assistant: [Pushes commit and tags]

Do you want to build and publish to PyPI now? (yes/no)

User: yes
Assistant: [Runs ./distro.sh build --clean]
Do you want to test on TestPyPI first? (yes/no)

User: no
Assistant: [Runs ./distro.sh push]
Release v0.2.0 has been published to PyPI!

You can create a GitHub Release at:
https://github.com/jarosser06/drift/releases/new