# Release

> Expert in PyPI package releases for ai-drift including SemVer version bumping, CHANGELOG.md maintenance, git tagging, and automated GitHub Actions publishing. Use when releasing a new version to PyPI or managing package distribution. Use when this capability is needed.

- Skill: `tomevault-io/release-28` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/release-28`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/release-28/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/release-28

---


# 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:
   ```bash
   git add .
   git commit -m "chore: release v{version}"
   ```

8. **Create git tag**: Create an annotated tag for the release:
   ```bash
   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:
    ```bash
    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
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jarosser06) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->