Release

Manages the full release lifecycle for sunholo-py and similar Python projects: version bumping, local testing, git tagging, pushing to trigger CI/CD, and monitoring GitHub Actions workflows through to PyPI publication.

Quick Start

Most common usage:

User: "release a new patch version"
# This skill will:
# 1. Read current version from pyproject.toml
# 2. Bump patch version (e.g., 0.146.1 → 0.146.2)
# 3. Run local tests (uv run pytest tests)
# 4. Commit version bump via PR (protected branch)
# 5. After merge, create annotated git tag v0.146.2
# 6. Push tag to trigger GitHub Actions
# 7. Monitor workflow status until PyPI publish completes

When to Use This Skill

Invoke this skill when:

• User asks to "release", "publish", "deploy to PyPI", or "tag a release"
• User says "bump version" (patch/minor/major)
• User asks to "monitor the release" or "check workflow status"
• User says "/release"
• User asks "what version are we on?"

Available Scripts

scripts/bump_version.sh <patch|minor|major>

Reads the current version from pyproject.toml and bumps it.

scripts/monitor_workflows.sh <tag>

Monitors GitHub Actions workflows triggered by a tag push.

scripts/check_version.sh

Displays the current version from pyproject.toml.

Workflow

1. Pre-Release Checks

Before any release:

• Ensure you're on the

  main

  branch (or the branch to release from)
• Run

  scripts/check_version.sh

  to see current version
• Run

  uv run pytest tests

  to verify all tests pass locally
• Check

  git status

  for uncommitted changes

2. Version Bump

Run

scripts/bump_version.sh <patch|minor|major>

Version types:

• patch

  : 0.146.1 → 0.146.2 (bug fixes, CI fixes)

• minor

  : 0.146.1 → 0.147.0 (new features, module additions)

• major

  : 0.146.1 → 1.0.0 (breaking changes)

Protected branch workflow: Since main is typically protected, the version bump needs a PR:

1. Create branch:

   git checkout -b release/v{new_version}

2. Commit the pyproject.toml change
3. Push and create PR via

   gh pr create

4. Wait for user to merge (or merge if allowed)

3. Tag and Push

After the version bump is merged to main:

git checkout main && git pull origin main
git tag -a v{version} -m "Release v{version}

- Summary of changes
- Key features or fixes"
git push origin v{version}

Tag format: Always

v{version}

v0.146.1

4. Monitor Workflows

Run

scripts/monitor_workflows.sh v{version}

The publish workflow steps:

1. Checkout code
2. Setup Python
3. Install build + pytest

4. python -m build

   (sdist + wheel)
5. Test minimal install (

   pip install dist/*.whl && python -c "import sunholo"

   )
6. Run unit tests (

   pip install .[test] && pytest tests

   )
7. Publish via

   pypa/gh-action-pypi-publish

5. Handle Failures

If a workflow fails:

1. Check failure details:

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

2. Common issues:
   • Test failures: Optional deps missing in CI (use

     pytest.importorskip

     )
   • Build failures: Check pyproject.toml syntax
   • Publish failures: Check PyPI token secret
3. Fix the issue, bump version again (patch), and re-release
4. Never reuse a tag that was pushed to PyPI (even if it failed partway)

6. Verify Publication

After successful workflow:

pip install sunholo=={version}  # Test install from PyPI

Resources

Workflow Reference

See resources/reference.md for GitHub Actions workflow details, troubleshooting guide, and common failure patterns.

Notes

• Always use

  uv

  for local package management, never pip directly
• Never force-push tags — create a new patch version instead
• Main branch is protected — version bumps require PRs with approving reviews
• CI tests with

  .[test]

  only — channel/adk tests must skip when optional deps are missing
• Repository:

  sunholo-data/sunholo-py

• PyPI package name:

  sunholo