Do you know how to write a great Pull Request (PR)?

As a software developer, you are going to create Pull Requests (PRs) that you want to be easy for others to review and approve. The quality of a Pull Request can vary - from cryptic to well-written.

Including a little bit of context helps your reviewer understand changes quickly so they can review your PR faster and give better suggestions.

There are 2 essential things you should have when writing a Pull Request:

1. Concise and self-explanatory title

Good PR titles provide a clear, concise summary of the change, helping reviewers quickly understand its purpose and priority.

• What the PR will do
• How the PR achieves it
• Emojis! Follow the GitMoji.dev standard

The key to writing a concise Pull Request is to base the PR itself on a PBI / Issue (assuming they are well written).

Having the "What" information allows the reviewers to quickly understand what this is about while having the "How" can help the reviewer to quickly understand how your PR solved the problem. Sometimes we might want to put the "How" in the PR descriptions (see below) if it is too long or hard to explain in one sentence.

2. Clear and informative description

The Pull Request description is a medium for the developer to tell the reviewers what the changes are about.

Good PR descriptions provide context to help others quickly understand the problem, solution, and rationale. This minimizes confusion, accelerates reviews, and improves overall code quality.

Examples of sentences to have in a good PR description:

• "Relates to #{{ ISSUE NUMBER or URL }}" (⚠️ see avoid linking to Issues you do not want to close)
• "From email subject: {{ EMAIL SUBJECT }}" (similar to the rule on warn then call)
• "As per my conversation with {{ NAME(S) }}" (similar to "as per our conversation" rule)
• "Worked with {{ @MENTION(S) }}" (as per pair or mob programming rule)
• "This PR is to {{ ACHIEVE THE FEATURE / FIX THE BUG / OTHER GOAL(S) }}" (anything that was not possible to explain in the title)
• "See {{ SCREENSHOT / DONE VIDEO }} for more details" (to help the reviewer to understand the changes. E.g. styling changes)

If you noticed that a change needed to be made and had no specific task/issue, use:

• "I/We noticed a problem: {{ DETAILS }}"

If there is an area you are uncertain about, add:

• "I'm looking for feedback on this code"

If the PR is closing an email task after merged, remember to refer back to it:

• "Done - see email: {{ EMAIL SUBJECT }}"

How to approach making a Pull Request

Video: 5 Tips For Better Pull Requests (11 min)

FAQs

Q: Are you making many small changes? A: You should summarize by saying: “Improved readability” OR “Fixed typos and grammar”.

Q: Are the changes big and complex? A: You should include a demonstration of the change.
E.g. A screenshot to show text/UI changes, or a Done video to demo functionality changes.

Q: Are you using a CMS editor (i.e. Netlify or Tina) A: CMS editors may automatically add a placeholder description. If you're using a CMS to make your changes, you may need to go to the PR afterward and update the description to include the context.