docs: require a detailed PR description - #91
Merged
Conversation
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
1 participant
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.
Sets an explicit expectation that pull requests carry a detailed description, in the three places a contributor encounters it.
What changed
PR template — the Summary section previously said "briefly describe" / "concise description" / "one or two sentences", which invited exactly the one-liners we keep receiving. It now asks for the problem, the approach, anything to review closely, and how it was verified — and states plainly that a one-line description will be sent back.
CONTRIBUTING.md — a new "Writing the pull request description" section covering the same four points, plus two clarifications: the description explains why, not what the diff already shows; and known limitations should be stated rather than omitted. It also repeats that
Closes #Nmust live in the description, since GitHub ignores closing keywords in comments.Issue templates — a closing note so the expectation is visible when someone picks the issue up, not discovered after they submit.
Why
Review time goes disproportionately into reconstructing intent from diffs. A description that states the approach and the author's own uncertainty is faster to review and likelier to merge first time.
Documentation and templates only — no code paths touched.