// 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.
| 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} |
Automate the release workflow for the pagination-helpers npm package.
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.
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:
1.0.0-alpha.4) when the user asks for an alpha/beta/rc release — increment the prerelease suffixBump the patch version unless the user specifies otherwise.
Edit package.json to set the new version number.
pnpm install
This updates the lockfile with the new version.
pnpm run lint-fix && pnpm run lint && pnpm run tsc && pnpm run test && pnpm run build
All must pass before proceeding.
Commit package.json and pnpm-lock.yaml with message v<new-version>. Push to main.
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.
Once the user confirms the publish, write release notes by thoroughly analyzing the changes.
Do not just list PRs. Study the actual changes to understand what they mean for users:
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.src/index.ts for added/removed exports.gh pr list --search "is:merged merged:>=<last-tag-date>" --json number,title,author --limit 100
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.
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>
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.