A pull request description should say what the change does and why. For a security reviewer, add three more facts: what data or permission it touches, where the trust boundary is, and how you tested the denied case. Vague titles such as "Fix bug" make a careful review slower and less likely.
The baseline from Google's guide
Google's engineering practices treat a description as a permanent record. The first line should be a short, specific summary written as an imperative sentence, followed by a blank line. The body explains the problem and why this approach was chosen, notes shortcomings, and includes background such as bug numbers. The guide lists "Fix bug", "Fix build", "Add patch" and "Phase 1" as bad descriptions.
It also says to check before submitting that the description still matches what the change does, since changes evolve during review.
Add the security facts
Three short lines go a long way.
- Touches: data, permissions, secrets, network calls or file paths this change reads or writes.
- Boundary: where untrusted input enters, and where it is checked.
- Tested: which tests cover the denied or hostile case.
Before and after
Weak: "Update upload handler."
Better: "Reject uploads over 5 MB before parsing. Large bodies were parsed fully before the size check ran. Touches: request body of the upload route. Tested: new test for a body over the limit returns 413."
The second version tells the reviewer exactly where to look.
Dependency changes
For a version bump, say why and what you checked: the changelog, whether the new version is a major bump, and what the lockfile diff shows. Tools can help list new transitive packages, but the human sentence says what you did.
Generated and bot pull requests
The guide says tool generated descriptions should follow the same principles. If a bot opens pull requests, make sure its template includes what changed and why. Review expectations for those are covered in CODEOWNERS for bot opened pull requests.
Links need context
External links can go dead. The guide says to include enough context to stand on its own. A ticket number alone will not help the auditor next year.
Put it in the template
A pull request template can ask for these prompts so nobody has to remember them.
A free scan of your dependencies is available at gold.safeguard.sh/scan.
A short checklist for authors
Before you click create, reread your description and ask: could someone who has not seen the ticket explain this change from the text alone? Does the first line stand by itself in the history? Does the body say why this approach was chosen, and not only what it does?
If the change touches a sensitive area, add the three security lines. It takes two minutes, and it often finds a missing test before the reviewer does.
Quick check
How long should a description be?
As long as the reasoning needs. Even small changes need context, according to Google's guide, but a few lines usually do it.
Sources
Last reviewed: 19 October 2026.
