Writing Effective Pull Request Descriptions: A Developer’s Guide

Crafting a well-thought-out Pull Request (PR) description is more than just a task — it’s an essential part of the development process. A clear and concise PR description not only helps your teammates provide useful feedback but also speeds up the review process, ultimately helping everyone get their work to production faster.

Why Your PR Description Matters

Imagine you’re on the receiving end of a PR review. The easier it is to understand the changes, the quicker you can provide valuable feedback. And when you make life easier for your teammates, they’ll likely do the same for you. It’s a win-win situation! By making the review process smoother and less tedious, you encourage more frequent and thoughtful participation, which benefits the entire team.

The Three Essential Questions

To create a PR description that hits the mark, try to answer these three key questions:

1. What did you do?
2. Why did you do it?
3. How did you achieve it?

While these questions serve as a great guideline, they aren’t set in stone. For example, if you’re fixing a simple bug, the “Why?” might be obvious, so you can skip it. The goal is to write with intention — crafting your description to help your reviewers understand and provide effective feedback.

1. What?

Start by giving a high-level overview of what you’ve done. This doesn’t mean listing every single change, but rather providing enough context for the reviewer to grasp the main idea.

Examples:

❌ See #JIRA-666.
❌ Fixed bugs.
❌ Added early return to someFunc.

✅ Sentry now allows modifying the default breadcrumb message. 
I have implemented a feature to recognize clicked elements and 
human-readable text from available HTML attributes.

✅ Fixed the alignment issues in the toolbar that caused it to appear 
off-screen when scrolling.

✅ There is a bug with the position of sidebar dropdown menu.
Steps to reproduce:
1) Scroll the page so the dropdown item at the bottom corner
2) Click on the dropdown. 
Actual: Dropdown menu positioned at the bottom of the block and not visible. 
Expected: Dropdown menu positioned at the top of the element.

2. Why?

Here, explain the reasoning behind your changes. This is where you share both the technical reasons and the broader goals, whether they’re related to improving user experience, enhancing performance, or meeting business objectives.

Examples:

❌ Because it was necessary.
❌ It was broken.

✅ Sentry breadcrumbs are meaningless for the most part 
because we can't restore the user's action by them.
✅ The dropdown's misalignment was causing usability problems, especially 
on smaller screens, leading to a poor UX.

3. How?

This section is where you can dive into the technical details, but remember to keep it focused. Highlight the significant changes and explain anything that might not be immediately obvious, like tricky algorithms or subtle updates.

Examples:

❌ Changed a variable name.
❌ Updated some CSS.
❌ Modified the API call.

✅ Replaced the static error messages with a dynamic system that pulls 
user actions from a session log to provide context.
✅ Refactored the dropdown component to use the Intersection Observer API to 
dynamically position the dropdown menu, ensuring it doesn’t overlap 
with the viewport edges.

Additional Tips

• Visual Aids: Whenever possible, include screenshots, ‘before and after’ comparisons, short videos, diagrams, or tables. Visual aids can significantly enhance understanding, especially for changes involving UI or complex workflows.
• Keep It Brief and Relevant: While it’s important to be clear, it’s also crucial to be concise. Avoid unnecessary details, especially for simple fixes. Instead, focus on information that genuinely helps others understand your changes and makes the review process more productive.

By following these guidelines, you’ll not only make your own PRs more effective but also contribute to a more collaborative and efficient development environment. Happy coding!