Release

Release workflow for publishing a new version to PyPI via GitHub Actions.

When to Use

• After feature work is complete and committed
• When asked to release, publish, or ship a new version
• When bumping to a new version number

Input

Default: Release without issue tracking.

If argument provided:

• GitHub issue number/URL: Fetch context with scripts/gh_issue_phase.sh get-issue $ARG for the tracked workflow issue to close after release.

Prerequisites

Before releasing:

• All work committed (clean working tree)
• On main branch
• /code-review passed
• /commit-work completed (CHANGELOG updated)

Workflow

┌─────────────────────────┐
│ 1. Ask for version      │
│    Patch/Minor/Major?   │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ 2. Verify clean state   │
│    git status           │
└───────────┬─────────────┘
            │
            ▼
      ┌───────────┐
      │ Clean?    │───No──→ STOP. Commit or stash first.
      └─────┬─────┘
            │Yes
            ▼
┌─────────────────────────┐
│ 3. Run quality checks   │
│    ruff → pytest        │
└───────────┬─────────────┘
            │
            ▼
      ┌───────────┐
      │ All pass? │───No──→ STOP. Fix issues first.
      └─────┬─────┘
            │Yes
            ▼
┌─────────────────────────┐
│ 4. Bump version         │
│    __init__.py +        │
│    pyproject.toml       │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ 5. Update CHANGELOG     │
│    [Unreleased] → [X.Y.Z]
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ 6. Commit + Tag + Push  │
│    (triggers workflow)  │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ 7. Verify release       │
│    PyPI + GitHub release│
└─────────────────────────┘

Step 1: Ask for Version Number

Before doing anything else, ask the user which version number to release:

Use AskUserQuestion with options:

• Patch (X.Y.Z+1): Bug fixes only
• Minor (X.Y+1.0): New features, backward compatible
• Major (X+1.0.0): Breaking changes

Or let them specify a custom version.

Step 2: Verify Clean State

scripts/verify_release_state.sh

Requirements:

• Working tree must be clean (no uncommitted changes)
• Must be on main branch

If not clean: Run /commit first or stash changes.

Step 3: Run Quality Checks

scripts/run_release_checks.sh

All must pass. No exceptions - releases with failing tests are forbidden.

Step 4: Bump Version

Update version in both files:

uv run python scripts/bump_version.py X.Y.Z

Important: Both files must have the same version number.

Version format: Follow SemVer

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

Step 5: Update CHANGELOG

In CHANGELOG.md, convert the Unreleased section to a versioned release:

Before:

## [Unreleased]

### Added
- New feature

After:

## [Unreleased]

## [X.Y.Z] - YYYY-MM-DD

### Added
- New feature

Keep an empty [Unreleased] section at the top for future changes.

Use the deterministic script to promote the changelog:

uv run python scripts/promote_changelog.py X.Y.Z

Step 6: Commit, Tag, and Push

git add agr/__init__.py pyproject.toml CHANGELOG.md
git commit -m "$(cat <<'EOF'
Release vX.Y.Z

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"
scripts/tag_and_push.sh X.Y.Z

Order matters: Push commit first, then tag. This ensures the commit exists on remote before the tag references it.

Important: The tag push triggers the publish workflow which:

1. Runs quality checks
2. Builds and publishes to PyPI
3. Extracts release notes from CHANGELOG.md
4. Creates GitHub release

Step 7: Verify Release

Watch the Workflow

The tag push triggers .github/workflows/publish.yml which:

1. Quality checks: Runs ruff + pytest
2. Build: Creates wheel and sdist
3. Publish: Uploads to PyPI via trusted publishing (OIDC)
4. Release: Creates GitHub release from CHANGELOG.md

# Watch the workflow run to completion
gh run watch --workflow=publish.yml

Verify Everything Succeeded

# Verify GitHub release was created
gh release view vX.Y.Z

# Verify PyPI publication (may take a few minutes)
pip index versions agr

If Workflow Fails

Failure Point	Result	Action
Quality checks	No PyPI, no release	Delete tag (git push --delete origin vX.Y.Z && git tag -d vX.Y.Z), fix issue, re-release
PyPI publish	No release created	Fix PyPI config, delete tag (git push --delete origin vX.Y.Z && git tag -d vX.Y.Z), re-release
Release creation	PyPI has package, no release	Create release manually (see below)

Manual release creation (if only the release step failed):

VERSION="X.Y.Z"
gh release create "v$VERSION" --title "v$VERSION" --notes-file <(
  echo "## What's New in v$VERSION"
  echo ""
  awk -v ver="$VERSION" '/^## \[/ { if (found) exit; if ($0 ~ "\\[" ver "\\]") found=1; next } found { print }' CHANGELOG.md
  echo ""
  echo "---"
  echo ""
  echo "**Full changelog**: https://github.com/kasperjunge/agent-resources/blob/main/CHANGELOG.md"
)

## Step 8: Close GitHub Issue

**If a GitHub issue was provided or is available from prior phases:**

Post release details and close the issue:

```bash
echo "Released as v$VERSION" | scripts/gh_issue_phase.sh post-phase $ISSUE done
scripts/gh_issue_phase.sh close-issue $ISSUE

Red Flags - STOP

• Uncommitted changes → Commit first
• Tests failing → Fix before release
• Not on main branch → Switch to main
• CHANGELOG not updated → Update it
• Skipping quality checks → Never skip

Common Mistakes

Mistake	Fix
Releasing with dirty working tree	Commit or stash first
Skipping tests "we tested earlier"	Run tests immediately before release
Forgetting to push the tag	Push tag separately after commit
Not watching the workflow	Use gh run watch to verify full pipeline
CHANGELOG not updated for version	Add version section before tagging
Only updating __init__.py version	Update both __init__.py and pyproject.toml

No Exceptions

• "We already tested it" → Run tests again now
• "It's just a patch" → Full quality checks required
• "Nobody reads release notes" → CHANGELOG is documentation. Use it.
• "We're in a hurry" → Rushed releases cause incidents