Pull Request Best Practices

A pull request is a communication tool as much as a technical one. The habits you build around PRs — how you scope changes, write descriptions, and respond to feedback — follow you into every team you join.

Keep PRs small and focused

The most common PR mistake is scope creep: you set out to add a feature, and along the way you also refactor a function, fix some formatting, and rename a variable. Now the reviewer has to untangle three different kinds of changes.

One PR, one purpose. If you notice something worth fixing while working on a feature, either:

• Fix it in a separate PR first, or
• Make a note of it for later and stay focused on the original change

Smaller PRs get reviewed faster, get better feedback, and are easier to revert if something goes wrong.

What “small” means in practice:

A PR that touches one file with 20 lines changed gets reviewed in minutes. A PR that touches 40 files with 800 lines changed sits unreviewed because no one wants to start.

There is no fixed line count, but if a PR takes more than an hour to review, consider whether it could be split.

Write a description that respects the reviewer’s time

The description is the reviewer’s context before they open the diff. A good description answers three questions:

What changed? Summarize the purpose. Not a list of every file you touched — the diff shows that. A sentence or two on the intent.

Why? What problem does this solve? What would stay broken without this change? Include any relevant context the reviewer might not have.

How can I verify this? List the steps a reviewer should take to confirm the change works correctly. For UI changes, include before/after screenshots if possible.

## Summary

Adds a "difficulty" field to each trail entry so users can judge
routes before attempting them. Addresses feedback from the February
user survey where 60% asked for difficulty context.

## Verification

1. Open pine-ridge.txt
2. Each trail entry now has a "Difficulty:" line
3. Values are one of: Easy, Moderate, Hard

Title conventions

The PR title follows the same rules as a good commit subject line:

• 50–72 characters
• Imperative mood: “Add difficulty ratings to trail notes” not “Added” or “Adding”
• No period at the end
• Describes the change, not the implementation

The title appears in the repository’s PR list, in notifications, and in merge commit messages (for squash merges). Make it scannable.

Giving feedback professionally

When reviewing someone else’s PR:

Be specific. “This could be better” is not useful. “This will cause a problem if the file is empty because we never check for that case” is.

Distinguish blockers from suggestions. Many teams prefix non-blocking comments with “nit:” (short for nitpick). A nit is something worth mentioning but not worth blocking the merge over.

Ask questions before assuming. “Was this intentional?” costs you nothing and avoids accusing someone of a mistake they made deliberately.

Acknowledge good choices. “Nice — this approach is much cleaner than what was there before.” A review that is only critical is harder to receive.

Receiving feedback professionally

Respond to every comment. Even if you disagree, acknowledge it. If you made the change the reviewer suggested, reply “Done.” If you disagree, explain why and either come to agreement or ask a third person.

Do not take it personally. Reviewers are looking at code, not judging you. Good teams build a culture where critical review is expected and normal.

Learn from patterns. If you keep getting the same feedback, internalize it. The goal is for the same feedback not to appear twice.

The self-review habit

Before requesting review (or before merging a solo PR), review your own PR:

1. Open the Files changed tab as if you are seeing it for the first time
2. Read every line of the diff
3. Look for: typos, leftover debug code, inconsistent naming, missing edge cases

You will catch things in the diff view that you missed while writing the code. This is the most valuable habit you can build.

Exercise

There are no commands in this lesson. Instead:

1. Look at the last PR you merged in your git-practice repository.

2. Review the title and description. Does it answer: what, why, and how to verify?

3. Look at the Files changed tab as if you are seeing it for the first time. Do you understand every change just from the diff?

4. Note one thing you would write differently if you were writing the PR description today. That is your takeaway.

Recap

• Small, focused PRs are reviewed faster and get better feedback. One PR, one purpose.
• A good description answers: what changed, why, and how to verify.
• PR titles follow the same rules as commit subject lines — imperative mood, concise, scannable.
• Give feedback that is specific, distinguishes blockers from suggestions, and asks questions before assuming.
• Respond to every comment. Learn from patterns in the feedback you receive.
• Self-review your own diff before requesting review — you will always find something.

Next: the module recap — a consolidated reference for the full pull request workflow.