docs: add a pull request template, all of it optional - #473
Merged
Conversation
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>
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
.github/has issue templates and no pull request template. A contributorarriving 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:
Closes #467.then "@Haiulus asked whether…"; "Reported by @luanfernandes in an edit to #153"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 all —
grep -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.ymlruns. 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
name, and the commit convention (
fix(editor):,feat(tags):,test(scripts):) already carries that information in the title.practice, on their own pull request, rather than something every change
carries.
tempting, but on inspection it appears on user-visible feature work and not on
fixes, and a heading that is right a third of the time trains people to leave
empty headings behind.
Verification
npm run check— 645 files, 0 errors.npm test— 692 pass, 0 fail. Thisadds one Markdown file and touches no source; that is a "nothing broke"
baseline, not a claim about the change.
.github/PULL_REQUEST_TEMPLATE.mdat the repository root of.github/is thepath GitHub picks up for every new pull request; the existing
.github/ISSUE_TEMPLATE/directory is untouched.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.