/pypi-release

name: pypi-release
description: This skill should be used when releasing tunacode-cli to PyPI. It keeps the existing local release checks, then hands the actual PyPI upload to a GitHub Actions workflow that uses the repository's PYPI_API_TOKEN secret.

PyPI Release Automation

Overview

Keep the existing local release gates for tunacode-cli, then hand the actual PyPI upload to GitHub Actions. This keeps the release checks local while moving the credentialed publish step into the repository workflow.

When to Use This Skill

Trigger this skill when the user requests:

• "Release to PyPI"
• "Publish a new version"
• "Create a release"
• "Bump version and release"
• "Push a new version to PyPI"

Core Release Workflow

The skill provides two approaches: **Manual** (REQUIRED) and **Automated** (deprecated - skips critical test step).

Automated Release (NOT RECOMMENDED - Use Manual)

**WARNING: The automated script is currently discouraged because it skips the mandatory manual test step.**

Use the Manual Release workflow below instead to ensure proper testing before release.

~~Execute the full release workflow with a single script:~~

~~```bash uv run python skills/pypi-release/scripts/release.py

~~The script performs these steps automatically:~~
1. ~~Pre-flight checks (git status, branch check, linting, tests)~~
2. ~~Version bump~~
3. ~~Git operations (commit, tag, push)~~
4. ~~GitHub release~~
5. ~~Workflow monitoring~~

**Issue:** The automated script does not include the mandatory manual import test (Step 3) which has caused multiple broken releases. Always use the manual workflow.

### Manual Release (REQUIRED - Step-by-Step)

**This is the ONLY recommended workflow. Follow these steps in order:**

#### Step 1: Pre-flight Checks

Verify the repository is ready for release:

```bash
# Check git status (must be clean)
git status

# Verify on master branch
git branch --show-current

# Run linting
ruff check .

# Run tests
source .venv/bin/activate && pytest tests/ -q

# MANDATORY: Run tmux E2E tool tests (all 6 must pass)
uv run pytest tests/system/cli/test_tmux_tools.py -v -m tmux

**HARD GATE: If the tmux tool tests fail, DO NOT proceed with the release.** These tests verify all 6 tools (bash, read_file, write_file, update_file, discover, web_fetch) work end-to-end in the real TUI. No exceptions.

Step 2: Bump Version

Use the version bumping script:

uv run python skills/pypi-release/scripts/bump_version.py

The script:

• Reads current version from `pyproject.toml`
• Increments the patch number (rightmost digit)
• Updates four files:
• `pyproject.toml:8` (project version)
• `pyproject.toml:175` (hatch script version)
• `src/tunacode/constants.py:12` (APP_VERSION constant)
• `README.md` (version header)

Step 2.5: Update CHANGELOG

**REQUIRED:** Manually update `CHANGELOG.md` with the new version entry.

1. Check commits since last release:

   git log --oneline $(git describe --tags --abbrev=0)..HEAD --no-merges

2. Add entry under `## [Unreleased]`:

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

   ### Added
   - New features

   ### Changed
   - Changes to existing functionality

   ### Fixed
   - Bug fixes

3. Stage the file:

   git add CHANGELOG.md

Step 3: **MANDATORY** - Test the Build Locally

**CRITICAL: You MUST test that tunacode actually works before releasing!**

Test the import and basic functionality:

# Activate venv and test import
source .venv/bin/activate && python -c "from tunacode.ui.main import app; print('✓ Import successful')"

# Optionally test the CLI starts without errors
python -m tunacode.ui.main --help

**If the import fails, DO NOT PROCEED with the release!** Fix the issue first, then re-test.

This step prevents releasing broken packages to PyPI (which cannot be undone).

Step 4: Commit and Push the Release Commit

Commit the version changes and push them to `master`:

# Stage version files (CHANGELOG.md should already be staged from Step 2.5)
git add pyproject.toml src/tunacode/constants.py README.md CHANGELOG.md

# Commit with conventional commit message
git commit -m "chore: bump version to X.Y.Z.W"

# Push to remote
git push origin master

Step 5: Trigger the GitHub Actions Publish Workflow

Run the manual publish workflow after the local checks and release commit have passed:

gh workflow run publish-release.yml --ref master -f version=X.Y.Z.W

This workflow:

• Checks that `pyproject.toml` and `src/tunacode/constants.py` match the requested version
• Builds the distribution artifacts
• Runs `twine check` on the built artifacts
• Publishes to PyPI using the repository `PYPI_API_TOKEN` secret

Step 6: Monitor Workflow

Check the status of the GitHub Actions workflow:

# List recent workflow runs
gh run list --workflow=publish-release.yml --limit 1

# Watch workflow in real-time
gh run watch

# View logs if failed
gh run view <run-id> --log-failed

Troubleshooting

Workflow Failures

If the GitHub Actions workflow fails:

1. **Check workflow status:**

   gh run list --workflow=publish-release.yml --limit 1

2. **View failure logs:**

   gh run view <run-id> --log-failed

3. **Common issues:** See `references/common-issues.md` for detailed troubleshooting

Version Consistency Errors

If the workflow reports version mismatch between the requested version and the code:

1. Verify all four version locations match:

   grep 'version = ' pyproject.toml
   grep 'APP_VERSION' src/tunacode/constants.py
   grep '^## v' README.md | head -1

2. Re-run `bump_version.py` script to sync versions

3. Push the corrected commit and re-run:

   git push origin master
   gh workflow run publish-release.yml --ref master -f version=X.Y.Z.W

Python Version Mismatch

If the workflow fails with Python version errors:

1. Check