Do deploy

Skill tomcounsell/popoto/.claude/skills/do-deploy

Deploy popoto: run tests, bump version, tag release, publish to PyPI, deploy docs. Triggered by 'deploy', 'do-deploy', or any request to publish a new version.From its SKILL.md

Install

npx -y skills add tomcounsell/popoto --skill do-deploy

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

9 stars9 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.2 KB, as published. Nobody here has run it

Deploy

Release a new version of popoto to PyPI and deploy documentation.

How releases work

Version is bumped manually in pyproject.toml and setup.cfg
A release branch + PR is created and merged
Pushing a v* tag triggers release.yml which publishes to PyPI via OIDC
Docs are deployed to GitHub Pages via mkdocs

Instructions

Step 0: Determine bump type

Use $ARGUMENTS if provided (patch, minor, or major). Default to minor if empty.

Step 1: Pre-flight checks

cd ~/src/popoto

# Must be on main
BRANCH=$(git branch --show-current)
if [ "$BRANCH" != "main" ]; then
  echo "ERROR: Must be on main branch (currently on $BRANCH)"
  exit 1
fi

# Must be clean
if [ -n "$(git status --porcelain)" ]; then
  echo "ERROR: Working tree has uncommitted changes"
  exit 1
fi

# Pull latest
git pull origin main

Abort if any check fails.

Step 2: Run tests

cd ~/src/popoto && pytest

Abort if any tests fail. Do not proceed with a broken test suite.

Step 3: Calculate new version

Read current version from pyproject.toml (version field under [project]).

Calculate new version:

patch: 1.4.0 → 1.4.1
minor: 1.4.0 → 1.5.0
major: 1.4.0 → 2.0.0

Confirm the new version with the user before proceeding.

Step 4: Update version files

Update the version in both:

pyproject.toml: the version field under [project]
setup.cfg: the version field under [metadata]

Step 5: Create release branch and PR

cd ~/src/popoto
git checkout -b release/v{new_version}
git add pyproject.toml setup.cfg
git commit -m "Bump version to {new_version}"
git push origin release/v{new_version}
gh pr create --title "Release v{new_version}" --body "Bump version to {new_version}"

Step 6: Merge, tag, and push

gh pr merge --merge
git checkout main
git pull origin main
git tag v{new_version}
git push origin v{new_version}

The tag push triggers the release.yml GitHub Actions workflow, which builds and publishes to PyPI via OIDC trusted publishing.

Step 7: Create GitHub release

gh release create v{new_version} --title "v{new_version}" --generate-notes

Step 8: Deploy documentation

cd ~/src/popoto
python -m mkdocs build --strict
python -m mkdocs gh-deploy --force

If mkdocs is not installed: uv pip install mkdocs

Step 9: Verify

Check the GitHub Actions release workflow: gh run list --limit 1
Report the new version, PyPI publish status, and docs URL (https://popoto.io/)

Troubleshooting

PyPI publish fails

Check the GitHub Actions run: gh run view --log-failed Common issues: OIDC token permissions, build errors.

Docs deploy fails

python -m mkdocs build --strict  # Check for errors first
uv pip install mkdocs            # Reinstall if needed

Need to roll back a release

git tag -d v{version}
git push origin :refs/tags/v{version}

Then yank the version on PyPI if already published.