Reasonable Pull Request -Writing an Effective and Meaningful Pull Request Description
A reasonable pull request (PR) is when the reviewer of your pull request can reason about it, and understand why the PR exists and what is it about.
To be reasonable, your PR description should contain the answer to these questions.
- Why this PR exists?
- What is it trying to achieve?
- How does it achieve it?
- How to test it
- 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.
This helps the reviewer to understand the context behind the PR and to help catch any duplicates as other PR might also exist for the same reason.
Examples:
> See ATL-123 for context.
Above, ATL-123 refers to a JIRA ticket ID.
> Untracked: User were not able to authenticate due to missing Authorization header.
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.
> Why
> Untracked: User were not able to authenticate due to missing Authorization header.
> What
> This PR contains change that adds the missing Authorization on all network calls to the API.
By reading the first few lines of the PR description, the reviewer immediately knew what’s the context behind the PR and what is it trying to achieve.
Usually, you can explain the what within three categories.
- What’s being added?
- What’s being updated?
- 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.
Third-party libraries that are added should also be explained here to understand the implications of the additions, why it is being chosen, and what other alternatives might be possible.
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.
If you have automated pipelines to deploy preview on each PR, it would help the testing phase a lot.
Share any test credentials that can be used to test, and provide a step-by-step instructions on how to test it.
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.
If your PR depends on configuration changes, explain the changes. Such as, the addition of environment variables along with its development values, or if your PR depends on the next action that needs to be executed after the PR has been merged.
The TLDR is; the reviewer should be able to understand the changes directly from the description. So that when they go through the file changes, they have a general understanding of what is happening in the code. The reviewer would be able to focus on discovering bugs or improvements that can be done to the code.
How do you write your PR? What would you do differently from this guide? Let me know in the comments.
— — —
Written by: Aditya Purwa
As a student under Sekolah Tinggi Informatika & Komputer Indonesia (STIKI) Malang — Jl. Raya Tidar №100, Karangbesuki, Kec. Sukun, Kota Malang, Jawa Timur 65146
Author ID: 171116002
Sekolah Tinggi Informatika & Komputer Indonesia (STIKI) Malang is a higher education institution that focuses on the field of informatics. STIKI Malang is one of the universities in Malang City, which produces Bachelor and Associate Expert graduates in the field of Informatics and Visual Communication Design. STIKI Malang was founded in 1985 and has received institutional accreditation with Accreditation Decree №3131/SK/BAN-PT/Akred/PT/XII/2016 dated 27 December 2016. Currently STIKI has 4 study programs, namely Informatics Engineering (S1), Visual Communication Design/DKV (S1) and Informatics Management (D3), and Information Systems (IS). All study programs have been accredited by BAN-PT.
