| name | skillsaw-release |
| description | Bump the version, generate release notes, and publish a new skillsaw release to PyPI. Use when cutting a new release. |
| compatibility | Requires git, gh CLI, and internet access |
| license | Apache-2.0 |
| user-invocable | true |
| metadata | {"author":"stbenjam","version":"1.0"} |
skillsaw Release
Follow these steps to release a new version of the skillsaw linter.
Step 1: Run pre-flight checks
Before releasing, verify:
- Check you are on the
main branch, it is clean (git status), and up to
date with origin/main (git pull origin main).
- All tests pass:
make test.
- Formatting is clean:
make lint.
- Determine which version to release. If none was specified, review the
commits since the last tag. Add a minor bump for new features or rules;
keep a patch bump for fixes only (the bump script defaults to patch when given no argument).
The Makefile creates the .venv and installs dependencies automatically; run make venv first if needed.
Step 2: Run the bump script
Run the bump script:
.venv/bin/python -c "pass" || make venv
bash scripts/bump-version.sh [version]
Verify the script updated pyproject.toml, src/skillsaw/__init__.py, and
action.yml (the action's default skillsaw version). If you pass no version
argument, keep it empty — the script increments the patch version automatically.
Then run make update to regenerate generated files and catch the pinned
version references the script does NOT update:
make update
grep -rn "{old_version}" README.md docs/
Update every stale pin by hand — currently pip install skillsaw==X.Y.Z in
README.md and docs/ci.md, and the pre-commit rev: vX.Y.Z in README.md
and docs/pre-commit.md. Never touch historical "Since vX.Y.Z" lines in docs/rules/.
Step 3: Create a version-bump PR
main is branch-protected — a direct push is rejected, so the bump goes
through a PR. First verify remotes with git remote -v (origin should
be stbenjam/skillsaw). Then run:
git checkout -b release/{version}-bump
git add -A
git commit -m "[Auto] Bump version to {version}"
git push -u origin release/{version}-bump
gh pr create --title "[Auto] Bump version to {version}" --body "Version bump for the {version} release."
Wait for all required checks to pass, merge the PR, then update local main:
gh pr checks {pr} --watch
gh pr merge {pr} --squash
git checkout main && git pull origin main
Step 4: Write the release notes
Read all commits since the last tag with git log:
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges
Review the commits and group them into categories:
- New features — new rules, new functionality.
- Fixes — bug fixes, validation corrections.
- Other — refactoring, CI changes, docs.
Write the release notes in markdown. Keep it concise — one line per change.
Include a "## What's New" header. Skip trivial commits (version bumps, merge commits, CI-only changes).
Step 5: Create the GitHub release
Create the release only after the bump PR has merged, so the tag includes the bumped version files:
gh release create v{version} --title "v{version}" --notes "{release_notes}" --target main
The tag triggers the release.yml workflow to build and publish to PyPI via OIDC trusted publishing.
Step 6: Verify the publish
Check the release workflow completes:
gh run list --workflow release.yml --limit 1 --json status,conclusion
Check the conclusion: if success, the release is live on PyPI. If it failed,
review the workflow logs and report the error.
