Pypi Release

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