Skillsaw release

Skill stbenjam/skillsaw/.apm/skills/skillsaw-release

Bump the version, generate release notes, and publish a new skillsaw release to PyPI. Use when cutting a new release.From its SKILL.md

Install

npx -y skills add stbenjam/skillsaw --skill skillsaw-release

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

What its file declares

Copied from the file, not written here

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.8 KB, as published. Nobody here has run it

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.