| name | release |
| description | Release a new version of the pagination-helpers npm package. Bump version, build, publish, and create a GitHub release. Use when the user mentions releasing, publishing, cutting a release, or shipping a new version. |
| metadata | {"internal":true} |
Release
Automate the release workflow for the pagination-helpers npm package.
Instructions
0. Verify on main branch
Before doing anything else, confirm the working tree is on main and up to date:
git branch --show-current
If not on main, switch and pull:
git checkout main && git pull
Never start a release from a feature branch. Version bumps, commits, and tags must land on main.
1. Determine the next version
Find the latest git tag:
git tag --list 'v*' --sort=-version:refname | head -1
Read the current version from package.json.
Get the diff since the last release tag:
git log <last-tag>..HEAD --oneline
git diff <last-tag>..HEAD --stat
If no v* tag exists yet (first release), use the version already in package.json and review all commits with git log --oneline.
Determine the next version following semver:
- patch for bug fixes and dependency updates
- minor for new features that are backwards-compatible
- major for breaking changes
- prerelease (e.g.
1.0.0-alpha.4) when the user asks for an alpha/beta/rc release — increment the prerelease suffix
Bump the patch version unless the user specifies otherwise.
2. Bump version in package.json
Edit package.json to set the new version number.
3. Run pnpm install
pnpm install
This updates the lockfile with the new version.
4. Run checks
pnpm run lint-fix && pnpm run lint && pnpm run tsc && pnpm run test && pnpm run build
All must pass before proceeding.
5. Commit and push
Commit package.json and pnpm-lock.yaml with message v<new-version>. Push to main.
6. Ask the user to publish
For stable releases, tell the user to run:
pnpm publish
For prerelease versions (alpha/beta/rc), tell the user to run:
pnpm publish --tag alpha
The --tag alpha flag prevents npm from marking the prerelease as latest.
Do not run pnpm publish yourself — it requires an OTP. Wait for the user to confirm they've published before continuing.
7. Create the GitHub release
Once the user confirms the publish, write release notes by thoroughly analyzing the changes.
Analyze changes in depth
Do not just list PRs. Study the actual changes to understand what they mean for users:
- Check dependency changes first — diff
package.json for new/removed/changed peerDependencies and dependencies. Peer dependency bumps are the highest-impact breaking changes because they gate who can install the package at all. Flag these immediately.
- Check the public API diff — look at changes to
src/index.ts for added/removed exports.
- List merged PRs between the two tags:
gh pr list --search "is:merged merged:>=<last-tag-date>" --json number,title,author --limit 100
- Read every PR's description — PR bodies contain author-written summaries, migration instructions, and context that titles and diffs alone don't provide. Read each one:
gh pr view <number> --json body,title --jq '.title + "\n---\n" + .body'
Run these in parallel (all PR reads in a single message) for efficiency.
- Read the changed source code when a PR description is missing or unclear — don't assume what a change does from the title alone.
Write release notes
Use the following structure. Include only the sections that apply:
## Breaking Changes — narrative subsections explaining each breaking change, what it replaces, and what users need to do. Order by impact: dependency requirement changes first (peer dep bumps affect every user at install time), then behavioral or API changes. Include code examples showing before/after when helpful.## New Features — bullet points with bold title, PR number in parens, and a one-line description drawn from the PR body.## Bug Fixes — bullet points with PR number and linked issue closes (e.g. "Closes #123").## What's Changed — full PR list with author links, formatted as:
* <title> by @<author> in https://github.com/seasonedcc/pagination-helpers/pull/<number>
End with:
**Full Changelog**: https://github.com/seasonedcc/pagination-helpers/compare/v<previous>...v<new>
Create the release
For stable releases:
gh release create v<new-version> --title "v<new-version>" --notes "<release-notes>"
For prerelease versions:
gh release create v<new-version> --title "v<new-version>" --prerelease --notes "<release-notes>"
Use a HEREDOC for the notes to preserve formatting.
