external-pr-style
External PR Style
Use this whenever opening a PR against a repository we don't own or control — any upstream, third-party, open-source contribution.
The problem
Some maintainers reject otherwise-correct, well-tested PRs purely because the description reads as AI-generated: generic section headers ("Root Cause:", "Why This Fix Works:", "Alternatives Considered:"), templated phrasing, over-explained one-line fixes. This is usually not an automated detector — it's a human maintainer pattern-matching by eye and closing with a canned rejection reply, sometimes on a diff that is otherwise correct and tested.
Maintainers in high-volume open-source repositories frequently pattern-match against common LLM artifacts: formulaic section headers, verbose explanations of trivial diffs, polite boilerplate, and hedging. Diffs that are completely correct and well-tested can be summarily closed if the PR text reads like an automated submission rather than a focused human contribution. Always inspect a target repository's recent merged and closed PR discussions to calibrate style before opening a PR.
Rules
- Write the PR body as first-person prose describing the bug and the fix, the way you'd explain it to a coworker over chat — not as a templated report.
- No invented section headers unless the target repo's own template requires them (see exception below). Skip "Root Cause:", "Why This Works:", "Alternatives Considered:", "Summary:" unless the repo asks for exactly that.
- State what you verified — tests run, red→green proof, residual risk on security-sensitive changes — as plain sentences woven into the explanation, not as a labeled checklist.
- Don't over-explain a small fix. Match the length of the description to the size of the change: for small fixes (1-20 lines), write 1-2 concise sentences describing the symptom and fix; for medium changes (20-100 lines), write one compact paragraph (3-5 sentences); for large changes (100+ lines), write two focused paragraphs detailing what changed, why, and what was verified.
- Don't hedge excessively or enumerate edge cases nobody asked about.