write-pr

SKILL.md

Writing pull requests

Standards for PR titles and descriptions in tldraw/tldraw.

PR title

Use semantic PR titles (Conventional Commits format):

<type>(<scope>): <description>

Types

feat - New feature

fix - Bug fix

docs - Documentation only

refactor - Code change that neither fixes a bug nor adds a feature

perf - Performance improvement

test - Adding or fixing tests

chore - Maintenance tasks

Scope (optional)

A noun describing the affected area: fix(editor):, feat(sync):, docs(examples):

Examples

feat(editor): add snap threshold configuration option

fix(arrows): correct binding behavior with rotated shapes

docs: update sync documentation

refactor(store): simplify migration system

PR body

Use this template:

<description paragraph>

### Change type

- [x] `bugfix` | `improvement` | `feature` | `api` | `other`

### Test plan

1. Step to test...
2. Another step...

- [ ] Unit tests
- [ ] End to end tests

### Release notes

- Brief description of changes for users

Description paragraph

Start with: "In order to X, this PR does Y."

Keep it specific - avoid vague phrases like "improve user experience"

Link related issues in the first paragraph

Don't expect readers to also read the linked issue

Change type

Tick exactly one type with [x]

Delete unticked items

Test plan

List manual testing steps if applicable

Remove the numbered list if changes cannot be manually tested

Tick checkboxes for included test types

Release notes

Write brief notes describing user-facing changes

Use imperative mood: "Add...", "Fix...", "Remove..."

Omit this section entirely for internal work (CI, tooling, tests, etc.) that has no user-facing impact

Concepts, examples, and FAQ (for large or feature-intensive PRs)

When a PR introduces a new system, several new types/APIs, or otherwise has enough surface area that a reviewer would benefit from a glossary, include extra explanatory sections above the standard ### Change type / ### Test plan / ### Release notes block. Skip these for small or focused PRs — they're for features and large refactors.

Pull from this menu, in roughly this order, using only what fits:

Concepts — a table of the new terms/types the PR introduces, with Term | Type | Meaning columns. Use this when readers need a shared vocabulary to follow the rest of the description.

Module augmentation — short code blocks showing how consumers extend the new types, when the PR exposes augmentable interfaces.

Editor API / Component props — Method | Description and Prop | Type | Description tables for new public surface.

Per-shape / per-feature breakdown — tables showing what each affected shape/module returns or accepts under the new system.

Example — a realistic, copy-pastable code snippet showing how a default implementation uses the new system, plus a second snippet showing how a consumer would override it.

FAQ — anticipated "How do I…?" questions with short code answers. Cover the obvious customization paths a downstream user will reach for first.

New examples — bullet list of any new entries added under apps/examples/src/examples/, with a one-line description each, so reviewers know where to look for runnable demos.

Reference: tldraw/tldraw#8410 is a good worked example of all of these sections together.

These sections come before ### Change type. The standard ### Change type / ### Test plan / ### Release notes / ### API changes / ### Code changes blocks still appear at the bottom in the usual order.

API changes section

Include when changes affect api-report.md:

### API changes

- Added `Editor.newMethod()` for X
- Breaking! Removed `Editor.oldMethod()`
- Changed `Editor.method()` to accept optional `options` parameter

Code changes table

Create a table that includes net LOC changes for each of the following sections. The sum of all rows must match the total PR diff. Omit rows with no changes.

Core code — SDK packages (packages/) source, excluding tests and API reports

Tests — unit tests, e2e tests (*.test.*, e2e/)

Automated files — generated files (e.g. api-report.api.md, snapshots)

Documentation — docs site and examples (apps/docs/, apps/examples/)

Apps — application code (apps/dotcom/, apps/mcp-app/, apps/vscode/, etc.), excluding e2e tests

Templates — starter templates (templates/)

Config/tooling — config files, lock files, lint config, CI, build scripts (eslint.config.*, yarn.lock, etc.)

### Code changes

| Section         | LOC change |
| --------------- | ---------- |
| Core code       | +10 / -2   |
| Tests           | +5 / -0    |
| Automated files | +0 / -1    |
| Documentation   | +2 / -0    |
| Apps            | +3 / -1    |
| Templates       | +0 / -0    |
| Config/tooling  | +1 / -0    |

Related issues

Search for and link relevant issues that this PR addresses.

Human notes (preserve exactly)

The PR author often writes a personal note at the very top of the description, prefaced with a "person" emoji such as 🅯 or 👨 (or similar). This block is human-written and readers trust it as such.

When updating an existing PR description, if the body starts with a paragraph/section led by a person emoji, you MUST preserve it byte-for-byte exactly at the top — do not rewrite, reflow, reword, retitle, or "improve" it, even slightly.

If the human note is longer than a single paragraph, it will be delimited at the end by a --- horizontal rule. Preserve everything from the person emoji through (and including) that --- exactly.

If there is no ---, the human note is just the leading paragraph led by the person emoji.

Make all your edits to the content below the human note (and below the --- if present).

When creating a new PR, do not invent a human note — leave that for the author to add.

Important

Never include AI attribution unless the PR directly relates to AI tooling

Never use title case for descriptions - use sentence case

Never put yourself as co-author of any commits

Always include an API changes section if the PR has changes to any api-report.md