Draft Prisma Release Notes

Draft release notes

This skill fires inside a release cut (stable or RC-line, both published under latest). The release-cutting agent runs it from the release/<version> worktree that publish-npm-version created, with the target version already known, and produces the committed notes file that is the GitHub Release body (the publish workflow ships it verbatim via gh release create --notes-file docs/releases/v<version>.md). There is no --generate-notes fallback — the file you author here is what every consumer reads.

The skill is prose-driven: there is no codemod or script to run. You — the agent — do the enumeration, the Linear-context lookup, the triage, and the writing directly, the same way record-upgrade-instructions walks you through authoring an upgrade entry rather than running one for you.

When to use

Run this skill when all of the following hold:

• A release is being cut (stable or 8.0.0-rc.N) — the target version $NEXT is known (computed by publish-npm-version step 1, e.g. 8.0.0-rc.2).
• You are in the release/<version> worktree with the bumped root version and reviewed, assembled upgrade guides committed, following the upgrade instruction lifecycle.
• docs/releases/v$NEXT.md needs drafting or refreshing after new fragments were incorporated (the PR-mode release-notes gate, pnpm check:release-notes --mode pr, requires the notes file).

Do not run it for -dev.N or -beta.N builds: those create no GitHub Release and are not gated. Do not run it to backfill notes for an already-shipped release — the convention starts from the first release cut after it landed.

The two hard rules

These are project requirements, not style preferences. A draft that violates either is wrong even if everything else is perfect.

Rule 1 — Never copy Linear content verbatim

Linear is a summarization-context input only. You read a ticket to understand the user-facing outcome of an opaque PR title, then you write a fresh, public, user-facing sentence describing that outcome. You never paste ticket prose into the notes. Specifically, the following must never appear in docs/releases/*.md or CHANGELOG.md:

• Customer names, account names, or any identifying detail of who reported or requested the change.
• Internal rationale, sprint/standup chatter, estimate or priority talk, or links to internal docs.
• The raw TML-NNNN: issue prefix or issue title — link the PR (#NNN) instead.
• Quoted sentences from the ticket body.

If you cannot describe a change for a public audience without leaning on internal context, that is a signal the entry needs rethinking (or is internal-only and should be excluded — see the triage rubric), not a licence to paraphrase the ticket closely. When in doubt, describe only the externally-observable behaviour change.

Rule 2 — Every line is verifiable

Every entry links its PR (#NNN) so the human reviewer can check your one-line summary against the actual diff during the release-PR review. The human review is the backstop for triage and summarization judgment calls — write for that reviewer.

Procedure

1. Resolve the range lower bound — the previous release tag

Reuse the actual prior published stable/RC ref resolved during release preparation. When invoked independently, resolve and confirm that published ref before proceeding. The range is "everything since the last release", so the lower bound is the most recent published release v* tag — stable or -rc.N — excluding -dev.* / -beta.* build tags (an -rc.N tag is a release and deliberately not excluded, so an RC respin's notes cover exactly what changed since the previous RC):

PREV_TAG=$(git describe --abbrev=0 --tags --match 'v[0-9]*' --exclude '*-dev.*' --exclude '*-beta.*')
echo "$PREV_TAG"   # e.g. v0.11.0

Equivalently, list and filter explicitly (useful when describe can't find an ancestor tag):

git tag --list 'v*' --sort=-v:refname | grep -Ev -- '-(dev|beta)\.' | head

The dev/beta exclusion matters: a -dev.N tag is cut on most merges, so an unfiltered "previous tag" would scope the range to a single PR. Filtering to release tags gives the full set of changes since consumers last saw a release.

2. Enumerate the commit set, then resolve PR metadata

Take the commit set from git log and resolve each commit to its PR via gh:

git log --first-parent --oneline "$PREV_TAG"..HEAD

For each merged PR in the range, resolve the metadata you need with gh / gh api — PR number, title, author (login), labels, and whether the author is a first-time contributor:

# PRs merged in the range (adjust the search window to the range you enumerated)
gh pr list --state merged --base main --limit 200 \
  --json number,title,author,labels,mergeCommit,mergedAt

# Or resolve a single PR by its merge commit:
gh api "repos/prisma/orm/commits/<sha>/pulls" \
  --jq '.[] | {number, title, author: .user.login, labels: [.labels[].name]}'

Use --first-parent so squash-merged PRs each show up as one commit; cross-check against gh pr list so you do not miss a PR or double-count.

3. Resolve opaque titles via Linear context

When a PR title is an internal shorthand (TML-NNNN: <terse handle>), read the referenced Linear issue (via the Linear MCP) to understand what changed for the user. This is enrichment only — re-read Rule 1 before writing anything. Summarize the outcome in your own public words; cite the PR, never the ticket.

4. Triage public-worthiness

Decide, per PR, whether it earns a line in the public notes. The rubric biases toward a clean, user-facing changelog over exhaustiveness — the human PR review is the backstop for judgment calls.

Always include:

• Anything flagged breaking.
• Anything touching the public surface: package exports (@internal/* public API), CLI commands/flags, prisma.config.ts fields, the contract format (contract.json / contract.d.ts shape), on-disk migration shape, or error codes.

Default-exclude unless user-relevant:

• Pure-internal refactors with no observable behaviour change.
• CI / workflow / tooling changes.
• Test-only PRs.
• Chore / dependency bumps (include only if a bump changes user-observable behaviour or a peer requirement).
• Doc-only changes (include only if they document a user-facing behaviour change worth surfacing).

Excluded PRs are dropped silently — no "internal changes" catch-all section. If a default-exclude PR has a genuine user-facing consequence, include it and describe that consequence.

5. Categorize into the fixed section order

Write the entries under the fixed section order from docs/releases/README.md, omitting any section with no entries:

1. Breaking changes — API removals/renames, semantic changes to existing APIs, contract-format changes. Say what the reader must do, not just what changed.
2. Features — new capabilities.
3. Fixes — bug fixes.
4. New contributors — first-time contributors, with the PR that welcomed them.

Breaking changes lead because they are what a reader scanning the notes most needs to see. Every line links its PR as an absolute markdown link — [#NNN](https://github.com/prisma/orm/pull/NNN), never bare #NNN. Bare references only autolink inside the GitHub Release body; they render as plain text when the committed docs/releases/v<version>.md is read as a repo file or in PR review, so the explicit link form is what makes every reference work in every context.

6. Anchor breaking-change entries to their migration recipe

Release preparation synthesizes feature-PR fragments into one reviewed guide per audience before this step, following the upgrade instruction lifecycle. Link these published guides, never pending fragments or source archives. The transition label — written <transition-label> below — names both ends of the hop, each end rendered the way versionSegment() in scripts/check-upgrade-coverage.mjs renders it: a stable version truncates to major.minor (v0.11.0 → 0.12.0 gives 0.11-to-0.12), and a prerelease keeps its full version string (8.0.0-rc.1-to-8.0.0-rc.2). Point the breaking note at the recipe directory rather than restating the migration.

Recipe links must be absolute, tag-pinned URLs — https://github.com/prisma/orm/blob/v$NEXT/.... The notes file becomes the GitHub Release body via --notes-file, and the Release page does not reliably resolve repo-relative links, so a relative recipe path would publish as a dead migration link. Pinning to the release tag (/blob/v$NEXT/) means the link always resolves and never rots as the recipe tree evolves on main:

• User-facing migrations: https://github.com/prisma/orm/blob/v$NEXT/skills/prisma-8/upgrading/app/upgrades/<transition-label>/
• Extension-author migrations: https://github.com/prisma/orm/blob/v$NEXT/skills/prisma-8/upgrading/extension/upgrades/<transition-label>/

A breaking change can affect one or both audiences — link the relevant audience's guide. Both directories exist for chain continuity, but an empty guide is not a migration recipe for a breaking change.

If a required guide is absent or omits a migration, return to release preparation to repair and review it before finalizing notes. Inline action summaries do not replace release completeness.

For a skipped-publish range, use the assembled guide from the actual previous published release to the target (e.g. 0.11-to-0.13 when 0.12 never shipped). Do not invent an intermediate release boundary. Existing historical published chains remain intact.