PR Description & Release Notes

When creating a PR

Follow the repo's PR template. Always create PRs as drafts. All AI-agent PRs must include the 🤖 bot label.

1. Analyze the changes

Before writing, understand the full diff:

bash

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 and apply the 🤖 bot label. Do not mark as ready for review until CI passes and the prompter approves.

bash

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

[what and why]

### What to review

[guidance for reviewers]

### Testing

[tests added or manual testing explanation]

### Notes for release

[release notes or N/A]

---
EOF
)"

If the label was omitted at create time:

bash

gh pr edit --add-label "🤖 bot"

After CI is green and the prompter approves, mark ready for review:

bash

gh pr ready

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