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