skillsaw-release · diff
v1.0 to v1.0
6 added, 6 removed. Audit A to A.
---
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"
---
<!-- 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. All tests pass: `make test`.
3. Formatting is clean: `make lint`.
4. 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:
```bash
.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:
```bash
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/`.
- Also check the documented plugin dependency floor: `grep -rn "skillsaw>=" docs/
- skills/ examples/`. The floor names the first release shipping `Rule.setting()`
- and must not exceed the version you are releasing — if it does, release the
- version the floor names (it is a minor-feature floor), or lower the floor to
- the version being released. A floor above the released version makes every
- scaffolded plugin uninstallable.
+ 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:
```bash
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:
```bash
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`:
```bash
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:
```bash
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:
```bash
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.