vtx-release-publish

name	vtx-release-publish
description	Tag, publish to PyPI, and create GitHub release for Vtx with validation and rollback-safe steps
register_cmd	true

Vtx Release + PyPI Publish

Use this skill when the user asks to cut a new Vtx version, tag it, publish to PyPI, and/or create a GitHub release.

Inputs to confirm

• Target version (example: 0.2.1)
• Base range for notes (usually previous tag, example: v0.2.0..HEAD)
• Whether to push main
• Whether to publish to PyPI now
• Whether to create GitHub release now

Versioning requirement

• Vtx's update check only supports strict numeric MAJOR.MINOR.PATCH versions such as 0.2.7 and 0.3.0.
• Do not cut releases with PyPI/PEP 440 prerelease or suffix forms like 0.3.0rc1, 0.3.0b1, 0.3.0.post1, or 0.3.0.dev1 unless the update-check logic is updated first.
• Even though PyPI commonly allows those formats, Vtx releases should continue following plain X.Y.Z so update detection stays correct.

Files to bump

• pyproject.toml → [project].version
• src/vtx/version.py → fallback VERSION = "..."
• uv.lock → local package version block

Release workflow

1. Preflight

   • git status --short --branch must be clean (or confirm with user)
   • git tag --list and git log --oneline <prev_tag>..HEAD to summarize changes

2. Update CHANGELOG.md

   • Replace the ## [Unreleased] section's - No changes yet. with a new versioned heading: ## <version> - YYYY-MM-DD
   • Use git log --oneline <prev_tag>..HEAD to categorize changes into ### Added, ### Changed, ### Fixed sections
   • Credit external contributors with - @username
   • Commit message: docs: update changelog for <version>

3. Version bump

   • Update version in all 3 files above

4. Quality gates

   • uv run ruff format .
   • uv run ruff check .
   • uvx ty check .
   • uv run python -m pytest

5. Commit

   • Commit message: build: bump version to <version>

6. Tag

   • Annotated tag: git tag -a v<version> -m "v<version> ..."
   • Include concise "changes since previous tag" bullets

7. Push

   • git push vtx main
   • git push vtx v<version>

8. Build + verify artifacts

   • rm -rf dist && uv build
   • uv run python -m twine check dist/*

9. Publish to PyPI

   • Prefer token file if present (example ~/.pypi-token):
   • TWINE_USERNAME=__token__ TWINE_PASSWORD="$(< ~/.pypi-token)" uv run python -m twine upload dist/*
   • Verify:
     • https://pypi.org/project/vtx-coding-agent/<version>/
     • https://pypi.org/pypi/vtx-coding-agent/json reports latest version

10. Create GitHub release

    • If token exists at ~/.github-token, call Releases API:
    • POST /repos/<owner>/<repo>/releases with:
      • tag_name: v<version>
      • target_commitish: main
      • name: v<version>
      • generate_release_notes: true
    • If 403 occurs, report missing token scopes/permissions (contents:write required)

Important notes

• Tagging and GitHub release are separate:
  • Tag = git ref in repository
  • Release = GitHub object attached to a tag (notes/assets)
• You can do either independently, but most projects do both together for user-facing releases.
• If PyPI publish succeeds but GitHub release fails, do not retag/re-publish. Just fix auth and create the release for the existing tag.

Output checklist to report

• Changelog updated for <version>
• Version bumped in all files
• Checks passed
• Commit hash
• Tag created and pushed
• PyPI upload URL
• GitHub release URL (or exact error + remediation)