release

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:

1. 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.
2. Check the public API diff — look at changes to src/index.ts for added/removed exports.
3. List merged PRs between the two tags:

gh pr list --search "is:merged merged:>=<last-tag-date>" --json number,title,author --limit 100

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

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