Skip to content

docs: add a pull request template, all of it optional - #473

Merged
PathGao merged 1 commit into
masterfrom
docs/pr-template
Aug 6, 2026
Merged

docs: add a pull request template, all of it optional#473
PathGao merged 1 commit into
masterfrom
docs/pr-template

Conversation

@PathGao

@PathGao PathGao commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

.github/ has issue templates and no pull request template. A contributor
arriving from outside gets an empty box.

Derived from the merged pull requests, not from a best-practice list

I read the bodies of #468, #464, #462, #460, #459 and #458 and took the headings
that recur. There is a house style here and it is quite specific:

section as it appears in
opening Closes #467. then "@Haiulus asked whether…"; "Reported by @luanfernandes in an edit to #153" #468, #464, #462
mechanism "Mechanism", "What 900 was", "Why it looks intermittent", "Why the macros were not simply renamed", "The observation the design change rests on" #464, #468, #462, #460, #459
scope / what was left alone "Scope" (three Monaco sub-options deliberately untouched), "Two things found while checking, neither fixed here", "Judgement calls, not defects", "Why no orphan-cleanup command here" #462, #460, #459, #458
tests + falsification "Reverting the template … turns 7 of the 9 red", with the red output pasted; "Reverting the fix with the tests kept gives 300/450 … 2 red" #468, #464
Verification present in every single one, always the exact commands with counts all six
honest gaps "I did not export from a running Tauri build"; "Only Blink was measured" #468, #464

The mechanism heading is the one worth pointing at. Not one of those pull
requests is titled "Description" or narrates what the author did — each one is
named after the finding, and explains why the old behaviour happened before it
says what changed. That is learnable from an example and essentially
unguessable from a blank field.

The one outside pull request this week, #463, arrived with ## Symptom,
## Root cause, ## Fix, ## Verification — the right shape, by instinct,
from someone who had no way of knowing. A template is how that stops being luck.

Nothing is required

Five headings, prompts only, no checkboxes at allgrep -c '^- \[ \]'
returns 0. Same reasoning the issue forms just adopted: a checkbox that feels
mandatory is a required field wearing a disguise, and friction is what makes
someone close the tab rather than fill the form in. The header comment says
outright that any section can be deleted and that they can be renamed to say
what the author actually found, which is what the merged pull requests do
anyway.

42 lines, of which 6 are the header comment and 6 are a fenced list of the four
commands test.yml runs. A long template is a template people delete.

No licensing or CLA line, no code of conduct line, no "I have read the
contributing guide" — there is no contributing guide, and a template should not
point at something that does not exist.

What I left out, deliberately

Verification

  • npm run check — 645 files, 0 errors. npm test — 692 pass, 0 fail. This
    adds one Markdown file and touches no source; that is a "nothing broke"
    baseline, not a claim about the change.
  • .github/PULL_REQUEST_TEMPLATE.md at the repository root of .github/ is the
    path GitHub picks up for every new pull request; the existing
    .github/ISSUE_TEMPLATE/ directory is untouched.
  • Not verified: how it renders in the compose box. I cannot open a pull
    request against master with this file already on master, so I have not seen
    GitHub actually pre-fill the body from it. The mechanism is a filename, and it
    either works on the first pull request after merge or the filename is wrong.

Your call

You are the one who reads every pull request this shapes, and a template that
does not match how you review is worse than none. If a heading here is not one
you would ask for, cut it — the file is easier to shorten than to argue with.

The review discipline here is real but undocumented: a mechanism section that
explains why the old behaviour happened rather than what was done about it, a
Scope section saying what was deliberately left alone, a falsification step on
fixes, and a Verification section with the exact commands, their counts and an
honest list of what was not checked. #468, #464, #462, #460 and #458 all have
that shape. Nobody arriving from outside can know it. #463 came close by
instinct, which is the argument for writing it down rather than hoping.

Five headings, prompts only, no checkboxes. A checkbox that feels mandatory is
a required field wearing a disguise, and friction is what makes a contributor
abandon a template rather than fill it in; the header says outright that every
section can be deleted. No licensing, conduct or "I read the guide" line --
there is no contributing guide to read.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
@PathGao
PathGao merged commit d345036 into master Aug 6, 2026
4 checks passed
@PathGao
PathGao deleted the docs/pr-template branch August 6, 2026 02:39
@PathGao PathGao mentioned this pull request Aug 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant