Reasonable Pull Request -Writing an Effective and Meaningful Pull Request Description

Crystal by Michael Dziedzic
  1. Why this PR exists?
  2. What is it trying to achieve?
  3. How does it achieve it?
  4. How to test it
  5. Important Remarks

The Why

Explain why this pull request exists. For organization that uses management software such as JIRA, you can link the JIRA ticket for the issues. If you are using GitHub issues, you can refer to the issues ID. For urgent and untracked issues, write a prompt description directly on the description.

The What

The what should come directly after the why to ensure the reviewer can connect the two immediately. For example on the untracked why above.

  1. What’s being added?
  2. What’s being updated?
  3. What’s being removed?

The How

The how is a more thorough explanation of the what. Usually, it is not necessary unless there is important knowledge that needs to be shared. For example, when implementing a complex algorithm. Explain why the algorithm was chosen and if there’s a diagram that can be shared, make sure to share it to help understand the algorithm.

How to Test

Another important details that needs to be shared is how to test the PR. If your organization have a Quality Assurance team that helps with testing, this would help them a lot. If not, it would helps the reviewer to test the PR directly and not just going through the code.

Important Remarks

Add any extra information that is relevant to the PR. It doesn’t have to be put at the end of the PR. For example, remarks about the urgency of the PR can be put at the top together with the why section.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store