sanity-io 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:
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 changesN/A – Part of feature X— partial implementation not yet enabledN/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.
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:
gh pr edit --add-label "🤖 bot"
After CI is green and the prompter approves, mark ready for review:
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