How to write a good pull request description

A pull request without a description is a puzzle with missing pieces.

The reviewer has to reconstruct what you were trying to do, why you did it this way, and what could go wrong, from the code alone. That’s not a review, it’s archaeology. And it’s why so many PRs get approved with a “LGTM” that doesn’t mean anything.

A good PR description isn’t bureaucracy. It’s the thing that makes your change reviewable — and therefore mergeable — without three rounds of back-and-forth.

Why most PR descriptions fail

The most common PR descriptions look like this:

• ”Fix bug”
• ”Update user service”
• ”WIP”
• ”Changes per feedback”

These tell the reviewer nothing. They don’t explain what the bug was, what broke, what the fix does, or how to verify it works. The reviewer is starting from zero.

The second most common failure is the opposite: a description that’s just a list of every file changed, copy-pasted from the diff. That’s also useless, it describes what changed, not why.

A good description answers the questions a reviewer would ask if they could.

The goal is to make the review faster and the approval more confident.

What to include in a pull request

A PR description that actually helps has four components. None of them are long, a good description for a focused PR can be under 150 words. The point is structure, not volume.

1. What this change does (2-4 sentences)

Not a list of files. Not a commit log. A plain explanation of what problem this PR solves and what it does to solve it.

This PR adds rate limiting to the /auth/login endpoint. Witout it, the endpoint can be used for credential stuffing with no hrottling. The implementation uses a sliding window counter in Redis with a 60-second TTL.

2. Why this approach

If there were alternative implementations you considered and rejected, say so.

This prevents reviewers from suggesting alternatives you already evaluated, and it shows your reasoning.

We considered using an in-memory counter, but that doesn’t work across multiple instances. Redis was already in the stack, so the overhead is minimal.

3. How to test it

Specific steps. Not “run the tests”, which tests? Where? Under what conditions?

1. Start the service locally with docker compose up
2. Hit /auth/login more than 10 times in 60 seconds with any credentials
3. The 11th request should return 429

4. What’s out of scope

This one gets skipped most often, but it prevents the review from expanding into territory you didn’t intend to cover.

This PR doesn’t address rate limiting on other endpoints. that’s tracked in #412.

Pull request best practices for developers

Beyond the description itself, there are a few pull request best practices that consistently improve review quality:

Keep PRs focused. A PR that does one thing is easier to review than one that does three. If you’re fixing a bug and refactoring a module and updating a dependency, that’s three PRs, or at minimum, a description that clearly separates the three concerns.

Link to the issue or ticket. The PR description doesn’t need to contain all the context, it needs to point to where the context lives. A link to the relevant issue, Jira ticket, or design doc is worth more than a paragraph trying to summarize it.

Don’t self-review your own PR right after writing it. The gap between writing code and reviewing it needs to be longer than five minutes. Come back to it after a break, or ask for a review first and do your own pass after seeing the comments.

Add a screenshot or recording for UI changes. A reviewer who can see the before/after state will spot visual regressions that are invisible in a diff.

The security section most teams skip

There’s one section most PR templates don’t include: a note on security implications.

Not every PR needs this, a typo fix doesn’t. But any PR that touches authentication, authorization, input handling, file uploads, external APIs, or new dependencies should include a line or two about what the security surface is and how it’s handled.

This doesn’t need to be a formal threat model. It can be as simple as:

Security: This endpoint accepts file uploads. Files are validated for MIME type and size limit before being written to S3. No user-supplied file path is used.

Or:

Dependencies: Added jsonwebtoken@9.0.2. Checked against OSV, no known CVEs. Replaces the unmaintained jwt-simple package.

Teams that use automated security analysis in CI can use that output as a reference, if the scanner flagged something, the PR description should acknowledge it and explain how it was resolved. Platforms like Ixtli produce per-PR security summaries that make this easy to include without doing the research manually.

A template you can actually use

Here’s a minimal template that covers the essentials. Adapt it to your team’s conventions, the point isn’t to fill out every field for every PR, it’s to make the important fields habitual.

GitHub

## What

[1-3 sentences: what problem does this solve and how]

## Why this approach

[Optional: alternatives considered and why they were rejected]

## How to test

[Specific steps to verify the change works]

## Out of scope

[What this PR explicitly doesn't cover]

## Security notes

[Optional: relevant security surface, how it's handled, or "no security impact — [reason]"]

Keep it in a .github/pull_request_template.md file and GitHub will auto-populate it for every PR.

GitLab

Keep it in a .gitlab/merge_request_templates/Default.md

Example

my-project/
├── .gitlab/
│   └── merge_request_templates/
│       └── Default.md
├── src/
└── README.md

## What

Describe the change and the problem it solves.

## Why

Why was this implementation chosen?

## How to test

Steps to verify the change works.

## Risks

Potential side effects or areas that may be impacted.

## Security impact

- [ ] No security impact
- [ ] Authentication / Authorization
- [ ] Input validation
- [ ] Secrets / Credentials
- [ ] Data exposure
- [ ] Infrastructure / Configuration

Conclusion

A PR description is not documentation for posterity. It’s communication for the reviewer who has to understand your change in the next 20 minutes.

The investment is small — 10 to 15 minutes to write a description that gives your reviewer everything they need. The return is a review that’s faster, more accurate, and less likely to require three rounds of clarification.

If your team’s PRs consistently lack context, the easiest fix is a template in the repo. Add it this week. If you want to take the security side further

without making it a manual process, ixtli.app integrates directly into the PR workflow.