PR Best Practices: Small Focused PRs, Linking Issues, and PR Description Templates
Knowing how to technically create a pull request (previous lesson) is only half the picture — writing pull requests that are genuinely easy and pleasant for someone else to review is a distinct, learnable skill. This lesson covers three of the most impactful practices: keeping PRs small and focused, linking related issues, and using a description template.
Learning Objectives
- Explain why small, focused pull requests are easier and faster to review than large ones.
- Link a pull request to a related issue so it can automatically close when merged.
- Use a PR description template to ensure consistent, complete information for reviewers.
- Recognize the practical impact of these practices on team velocity and code quality.
Key Terms to Know Before Learning PR Best Practices
- Small, focused PR: A pull request that addresses exactly one logical change, mirroring the atomic commit principle from Module 1 at the level of an entire pull request.
- Linking an issue: Referencing a GitHub issue number within a pull request's description using special keywords, connecting the two and optionally auto-closing the issue on merge.
- PR description template: A pre-defined Markdown structure, stored in a repository, that automatically populates a starting structure whenever a new pull request is opened.
- Closing keyword: A specific word (such as 'closes', 'fixes', or 'resolves') followed by an issue number, which GitHub recognizes to automatically close that issue when the pull request is merged.
How Effective Pull Request Practices Actually Work
**Keeping pull requests small and focused** is, in many experienced engineers' view, the single highest-leverage PR practice there is. A small PR — ideally addressing just one logical change, mirroring the atomic commit principle from Module 1 but applied at the level of an entire proposed change — can typically be reviewed thoroughly in minutes. A large PR touching dozens of files across multiple unrelated concerns can take hours to review properly, and in practice often doesn't get that thorough review at all — reviewers under time pressure tend to skim large PRs rather than genuinely scrutinize them, which is precisely when subtle bugs slip through. Small PRs also fail faster and more cheaply: if a small PR has a problem, it's usually obvious and quick to fix; if a large PR has a problem discovered late, unwinding or reworking it can be significantly more disruptive. As a practical guideline, many teams informally target PRs that can be reviewed in under 15-20 minutes, breaking larger features into a sequence of smaller, incrementally mergeable PRs wherever feasible — directly echoing Module 3's guidance on preferring short-lived branches.
**Linking related issues** connects a pull request to the GitHub issue (covered in the next lesson) it addresses, giving reviewers immediate context about the underlying problem or request the PR is solving. GitHub recognizes specific **closing keywords** — `closes`, `fixes`, `resolves` (and a few variants) — followed by an issue number, written anywhere in a pull request's description:
```
Fixes #42
```
When a pull request containing this text is merged into the repository's default branch, GitHub automatically closes issue #42, keeping the issue tracker naturally up to date without requiring anyone to manually close it afterward. Even without using a closing keyword, simply mentioning `#42` links the two together for easier navigation between them, without triggering the automatic closing behavior.
**PR description templates** solve the problem of inconsistent, incomplete pull request descriptions across a team. By adding a file named `.github/pull_request_template.md` to a repository, its content automatically pre-populates the description field every time a new pull request is opened against that repository, prompting the author with a consistent structure — commonly including sections like 'What does this PR do?', 'How was this tested?', 'Related issue(s)', and a checklist of common requirements (such as 'Tests added' or 'Documentation updated'). This ensures reviewers consistently get the context they need, without relying on every individual author to remember to include it unprompted.
Together, these three practices directly serve the same underlying goal: **making a reviewer's job as easy as possible**, since code review that's genuinely thorough and fast is one of the highest-leverage activities on any software team.
Small vs Large Pull Requests: Visual Walkthrough
Draw two contrasting PR cards side by side. LEFT labeled 'Large, unfocused PR': '47 files changed, +2,340/-891 lines, no linked issue, empty description' with a red clock icon reading 'Review time: 3+ hours (often skimmed, not truly reviewed).' RIGHT labeled 'Small, focused PR': '3 files changed, +42/-8 lines, "Fixes #42" in description, template checklist filled out' with a green clock icon reading 'Review time: ~10 minutes (thorough, confident review).'
PR Best Practices: Quick Reference Table
| Practice | What It Does | Why It Helps |
|---|---|---|
| Small, focused PRs | Limits a PR to one logical change | Faster, more thorough reviews; easier to revert if something's wrong |
| Linking issues (Fixes #42) | Connects a PR to the issue it addresses | Gives reviewers context; auto-closes the issue on merge |
| PR description templates | Pre-populates a consistent structure for new PRs | Ensures reviewers consistently get the context they need |
Linking Issues and Structuring a PR: Syntax and Examples
# Example pull request description using a closing keyword
## What does this PR do?
Fixes the incorrect discount calculation on the checkout page for bulk orders.
## Related issue
Fixes #42
## How was this tested?
Added a new unit test covering the bulk-order discount edge case; verified manually
in the staging environment with a sample cart of 15 items.
## Checklist
- [x] Tests added
- [x] Documentation updated (N/A for this fix)
- [x] Linked related issue
# --- Example repository file that auto-populates this structure for every new PR ---
# .github/pull_request_template.mdBreaking Down the PR Best Practices Example
This example description demonstrates all three best practices working together: the PR is scoped to one specific, describable fix (small and focused); it uses the `Fixes #42` closing keyword, which will automatically close that issue once this PR is merged; and its overall structure (What does this PR do? / Related issue / How was this tested? / Checklist) reflects exactly the kind of consistent structure a `.github/pull_request_template.md` file would automatically provide as a starting point for every new pull request opened against this repository.
How PR Best Practices Are Applied on Real Engineering Teams
- Many engineering teams explicitly enforce a 'small PR' culture through code review norms, sometimes even configuring automated bots that comment with a warning on pull requests exceeding a certain line-count threshold.
- Nearly every actively maintained open-source project uses a .github/pull_request_template.md file, since it dramatically reduces the number of incomplete or context-free contributions maintainers need to follow up on.
- Project management workflows that rely on GitHub Issues (next lesson) for tracking work depend heavily on the closing-keyword convention to keep the issue tracker automatically synchronized with actual completed work.
- Engineering managers and tech leads frequently cite PR size as one of the most reliable predictors of review quality and velocity, often coaching new team members specifically on breaking large changes into smaller, incremental PRs.
PR Best Practices Interview Questions and Answers
Q1. Why are small, focused pull requests generally considered a best practice?
They can be reviewed thoroughly and quickly, since a reviewer can hold the entire scope of the change in their head at once. Large PRs are often only skimmed rather than genuinely scrutinized due to time pressure, making it more likely for subtle bugs to slip through, and they're also more disruptive to unwind if a problem is discovered late.
Q2. How do you link a pull request to a GitHub issue so the issue closes automatically when the PR is merged?
Include a closing keyword like 'Fixes', 'Closes', or 'Resolves' followed by the issue number (e.g., 'Fixes #42') anywhere in the pull request's description. When that PR is merged into the repository's default branch, GitHub automatically closes the referenced issue.
Q3. What is a PR description template, and what problem does it solve?
It's a file (commonly .github/pull_request_template.md) that automatically pre-populates a consistent structure whenever a new pull request is opened against a repository. It solves the problem of inconsistent, incomplete PR descriptions by prompting every author with the same set of expected sections, such as what the PR does and how it was tested.
PR Best Practices Quiz: Test Your Understanding
1. Why are small, focused pull requests generally easier to review than large ones?
- They automatically skip the need for any review
- A reviewer can hold the entire scope of a small change in their head, enabling a thorough, fast review
- GitHub technically limits how large a PR can be
- Small PRs never contain any bugs
Answer: B. A reviewer can hold the entire scope of a small change in their head, enabling a thorough, fast review
Explanation: Small, focused PRs are easier to fully understand and scrutinize, while large ones are often only skimmed under time pressure, increasing the risk that subtle issues go unnoticed.
2. Which keyword, followed by an issue number, causes GitHub to automatically close that issue when the pull request is merged?
- Mentions
- Fixes
- Views
- Includes
Answer: B. Fixes
Explanation: 'Fixes' (along with 'Closes' and 'Resolves') is one of GitHub's recognized closing keywords — when followed by an issue number in a PR description, it triggers automatic closing of that issue upon merge.
3. What is the purpose of a file named .github/pull_request_template.md?
- It automatically merges all pull requests
- It automatically pre-populates a consistent description structure for every new pull request opened against the repository
- It deletes old, stale pull requests
- It prevents any pull requests from being created
Answer: B. It automatically pre-populates a consistent description structure for every new pull request opened against the repository
Explanation: This file's content automatically appears as the starting description for any new pull request, ensuring every author is prompted with a consistent, complete structure rather than starting from a blank field.
Common Pull Request Mistakes to Avoid
- Submitting large, sprawling pull requests that touch many unrelated concerns at once, making genuinely thorough review impractical.
- Forgetting to link a related issue, or using a keyword GitHub doesn't recognize, missing the opportunity for automatic issue closing.
- Leaving a pull request's description blank or minimal, forcing reviewers to reconstruct context from the diff alone.
- Not setting up a repository-wide PR description template, leading to inconsistent, unpredictable levels of context across different contributors' pull requests.
PR Best Practices: Exam-Ready Quick Notes
- Small, focused PRs: easier, faster, more thorough reviews; mirrors the atomic commit principle at the PR level.
- Closing keywords (Fixes/Closes/Resolves #N): auto-close the linked issue when the PR merges into the default branch.
- PR description templates (.github/pull_request_template.md): auto-populate a consistent structure for every new PR.
- All three practices share the same underlying goal: making a reviewer's job easier and more effective.
PR Best Practices: Key Takeaways
- PR size is one of the strongest predictors of review quality — small, focused PRs get genuinely thorough reviews, while large ones often don't.
- Linking issues with recognized closing keywords keeps a project's issue tracker automatically synchronized with actual merged work.
- A PR description template removes the guesswork and inconsistency of relying on every contributor to remember what context to include.
Frequently Asked Questions About PR Best Practices
Q1. Why should I keep my pull requests small?
Small pull requests are much easier and faster for someone else to review thoroughly. Large pull requests are often only skimmed due to time pressure, increasing the chance that subtle problems go unnoticed, and they're also harder to unwind if an issue is found.
Q2. How do I link a pull request to a GitHub issue?
Include a closing keyword like 'Fixes', 'Closes', or 'Resolves' followed by the issue number (for example, 'Fixes #42') anywhere in the pull request's description. GitHub will automatically close that issue when the pull request is merged.
Q3. What is a PR description template?
It's a file, typically named .github/pull_request_template.md, that automatically pre-fills a consistent structure in the description field every time someone opens a new pull request against that repository, prompting them with expected sections like what changed and how it was tested.
Q4. What should I include in a good pull request description?
A clear explanation of what the change does and why, a link to any related issue (ideally using a recognized closing keyword), and information about how the change was tested — a PR template can help ensure this is consistently included.
Q5. Does linking an issue automatically close it right when I open the pull request?
No. The issue only closes automatically once the pull request containing the closing keyword is actually merged into the repository's default branch — simply opening or mentioning it doesn't trigger the automatic closing.
Summary
Writing effective pull requests goes beyond the mechanics of opening one. Keeping PRs small and focused — addressing exactly one logical change, mirroring Module 1's atomic commit principle — leads to faster, more thorough reviews and lower risk, since large PRs are often only skimmed under time pressure. Linking a related issue using a recognized closing keyword (such as `Fixes #42`) gives reviewers immediate context and automatically closes that issue once the PR is merged into the repository's default branch. Finally, a PR description template, defined in a `.github/pull_request_template.md` file, automatically pre-populates a consistent structure for every new pull request, ensuring reviewers reliably get the context they need rather than depending on each individual contributor to remember to include it. All three practices share the same underlying goal: making code review as fast, thorough, and low-friction as possible.