<!-- Source paths below are repo-root-relative references, not links navigable from this skill's directory. --> <!-- skillsaw-disable content-unlinked-internal-reference -->

skillsaw Release

Follow these steps to release a new version of the skillsaw linter.

Step 1: Run pre-flight checks

Before releasing, verify:

1. Check you are on the main branch, it is clean (git status), and up to date with origin/main (git pull origin main).

2. Verify the current main commit has a successful push run of the Tests workflow. Do not accept the reduced PR test run: pull requests run Python 3.9 plus the 3.14 coverage job, while a main push must have passed Python 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14. The workflow run must test the exact HEAD being released:

   main_sha=$(git rev-parse HEAD)
   run_id=$(gh run list --workflow test.yml --branch main --commit "$main_sha" \
     --event push --status success --limit 1 --json databaseId --jq '.[0].databaseId')
   test -n "$run_id" && test "$run_id" != "null" || {
     echo "No successful Tests workflow run exists for main at $main_sha" >&2
     exit 1
   }
   gh run view "$run_id" --json jobs | jq -e '
     [.jobs[] | select(.name | test("^test \\(3\\.(9|10|11|12|13|14)\\)$"))]
     | length == 6 and all(.[]; .conclusion == "success")
   ' >/dev/null || {
     echo "The full Python 3.9–3.14 main test matrix did not pass" >&2
     exit 1
   }
   

3. All local tests pass: make test.

4. Formatting is clean: make lint.

5. 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 the documented install pins. The action installs its checkout by default; its empty version input stays unchanged during a release. If you pass no version argument, the script increments the patch version automatically.

Then regenerate generated files, refresh the human contributor list from GitHub, and check for pinned version references the script does NOT update:

make update
make update-contributors
grep -rn "{old_version}" README.md docs/

The contributor update combines commit contributors and issue filers, removes bots and known automation accounts, and writes the generated README table. Run it before committing the version-bump PR so every release thanks the current community without a scheduled workflow holding repository write permissions.

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/.

Also verify the documented plugin dependency floor: grep -rn "skillsaw>=" docs/ skills/ examples/. The bump script rewrites skillsaw>= floors alongside the other pins, and tests/test_release_metadata.py asserts the floor never exceeds the project version — a floor above the released version makes every scaffolded plugin uninstallable, so investigate any grep hit the bump did not move.

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.