pr-description

PR Description & Release Notes

When creating a PR

Follow the repo's PR template. Always create PRs as drafts.

1. Analyze the changes

Before writing, understand the full diff:

git log main..HEAD --oneline
git diff main...HEAD

2. PR title

Must follow conventional commits (CI-enforced):

type(scope): lowercase description

• Types: feat, fix, chore, docs, refactor, test, perf, ci
• Scope: package or area affected (groq, cli, form, schema, deps, etc.)
• No backticks, quotes, or markdown in the title
• Description starts lowercase

3. Write the PR body

Lead with why. Only elaborate on the non-obvious. The reviewer can read the diff — they need the context the diff can't give them. Default to terse; expand only where a reader would genuinely wonder.

Priorities for the Description section:

• Heavy on why — the motivation, the problem being solved, the constraint or incident that forced this change
• Cover why not — alternatives considered and rejected, one sentence each. This is often the most valuable part: it prevents the reviewer from suggesting a path you've already ruled out. Skip if there were no real alternatives worth mentioning
• Light on how — only call out approach when it's non-obvious, novel, or a reviewer might reasonably have picked a different path. Skip it for routine changes where the diff speaks for itself
• Minimal what — the diff shows what changed. One sentence of orientation at most; don't restate file-by-file changes the reviewer can see

Length test: if a sentence would tell the reviewer something they could deduce in 10 seconds from the diff, cut it. A good PR description is often 3–5 sentences total. Bulleted lists of "alternatives considered" should be one line per alternative, not a paragraph.

If you catch yourself writing "this PR renames X to Y" or "adds a new function Z", delete it. If you're explaining why X needed to be renamed or why Z exists (and why the obvious alternative wasn't chosen), keep it — but stay brief.

Use all four sections:

Description

Focus on why and why not, tersely:

• The problem or context the diff doesn't reveal (one short paragraph)
• Alternatives considered and why rejected (one line each, only if they were real candidates)
• How only when non-obvious or debatable
• What reduced to a one-line orientation

What to review

• Which files/areas matter most
• Anything tricky or non-obvious
• Which packages are affected (this is a monorepo)

Testing

• Tests added or modified
• If no automated tests: how you tested and why automation wasn't practical

Notes for release

This section is used by the docs team to write release notes.

If not needed, write one of:

• N/A — internal-only changes
• N/A – Part of feature X — partial implementation not yet enabled
• N/A – Internal only — tooling/chore work

If needed, write for end users and the docs team:

• What changed from a user perspective
• How to use it (code snippets if applicable)
• Limitations or breaking changes

Always end this section with a --- horizontal rule. The release-notes automation stops at the first --- after the "Notes for release" heading, so the rule fences off anything appended below (Cursor Bugbot reviews, later edits) and keeps it out of the changelog.

4. Create the PR

Always create as draft. Do not mark as ready for review until CI passes.

gh pr create --draft --title "type(scope): description" --body "$(cat <<'EOF'
### Description

After CI is green, mark ready for review:

Release notes checklist

• Written for end users, not internal engineers
• Includes code snippets for new APIs or changed behavior
• Mentions breaking changes prominently
• No unexplained jargon
• Concise — a paragraph plus code example is ideal