Skip to content

Commit 65d1740

Browse files
authored
docs: add the merge-brief PR template (#2957)
1 parent d8b7c7a commit 65d1740

1 file changed

Lines changed: 60 additions & 0 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<!--
2+
Merge brief. AI agents and people both follow these rules. Replace every comment, and do not keep this block.
3+
4+
Write for the person who approves the merge, not for someone reading the code. Agents review the code line by line, so the approver does not read the diff.
5+
Every line must help them decide to merge, or know what to watch after the merge. If a reviewer can learn it from the diff, cut it.
6+
7+
Hard limits:
8+
- Budget: about 150 words for low risk, 250 for medium, and 400 for high. Never more than 500 words, not counting links.
9+
- At most 3 bullets per section. Each bullet is one or two lines.
10+
- Delete every section that has nothing real to say. A trivial PR is the headline plus the slot line.
11+
12+
Never include:
13+
- A What, Why, How, or Implementation section.
14+
- A restated diff, or a list of changed files.
15+
- The story of the investigation, or of the review rounds.
16+
- Test counts, or lists of lint, fmt, CI, or review runs. The checks tab shows them.
17+
- A tool-generated summary (for example "Summary by CodeRabbit").
18+
19+
Writing:
20+
- Plain, simple English. One idea per sentence. Short sentences. Active voice with a real subject.
21+
- Describe the change in system terms (behavior, money, services, alerts), not in code terms.
22+
- Say what the code does, not what you hope it does. Never invent evidence.
23+
- Link every issue as a real Markdown link. A bare Linear ID does not link on GitHub.
24+
- Do not hard-wrap lines. Write each sentence or bullet on one line.
25+
-->
26+
27+
<!-- Headline: 1 to 3 sentences, with no heading above them. What the system does after the merge, where its output goes, and why now. Link the issue. In a stack, say which part this is and what the next part adds. -->
28+
29+
**Live effect:** <!-- none, or what changes for users, money, services, or alerts --> · **Risk:** <!-- low, medium, or high, with the triggers in parentheses: money path, keys or IAM, production config or infrastructure, stored data, hard to undo. Name them even for low risk. --> · **Ships:** <!-- on merge, next release, or after a manual step --> · **Blocks:** <!-- PRs that must merge after this one, or delete this slot -->
30+
31+
## Needs your call
32+
33+
<!-- Only if you need a decision from another person. @mention the person who must answer. Never give the PR author an open action here. -->
34+
35+
-
36+
37+
## Decisions
38+
39+
<!-- At most 3. Only choices a teammate could dispute. Write each as "X, not Y, because Z." Link each to its lines in the diff. -->
40+
41+
-
42+
43+
## Risks
44+
45+
<!-- At most 3. What can go wrong, how bad it is, and what limits it or which issue follows up. -->
46+
47+
-
48+
49+
## Proof
50+
51+
<!-- The strongest 1 to 3 pieces of evidence: the test that reproduces the bug, a staging check, the plan summary, a screenshot. Not a list of every test. -->
52+
53+
-
54+
- **Not verified:** <!-- Always keep this bullet. Name what nobody checked, human or agent. -->
55+
56+
## Rollout
57+
58+
<!-- Only if live behavior changes or a manual step is needed. Give each step the signal to check. The last step is the rollback, with any trap named. -->
59+
60+
1.

0 commit comments

Comments
 (0)