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.
Confirmed directly across several upstream contribution sessions: individual maintainers of some well-known PHP/JS ecosystem repos have closed multiple PRs this way, including one with an identical fix and real tests to a version that was later accepted once the description was rewritten. This pattern is maintainer-specific, not universal — always check a target repo's recent closed-PR history for this signature before assuming it applies.
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.
- Don't hedge excessively or enumerate edge cases nobody asked about.