A pull request (PR) is a social contract between developers, architects, and technical leads. So what are the major parts of a pull request?
Code
In software development, most of the time, PR is about code. Keep the changes as small as possible. Do not try to include too many changes in a pull request.
Description
I have seen many pull requests with poor descriptions. When I read them, they do not give me any helpful information. What should be included in a PR’s descriptions?
Bugs: Root Cause – Solution – Impact
Root Cause: It is a critical part. Developers must explain why and how it occurred. A common understanding between developers and reviewers is established once they read and agree upon the root cause. When the root cause is wrong, the rest does not matter.
Solution: Explain how you have fixed the problem. Did you make any tradeoffs? And why did you choose that approach? Depending on the problem, the detail differs.
Impact: Some changes might have significant consequences, such as infrastructure changes, changes in frameworks, changes in common flows. Some changes are local. Developers must be aware of them, and they must write them down.
Features: Problem/Requirement – Solution – Impact
The steps are the same as bugs, except the first one is "Problem/Requirement," a sentence explaining the outcome of the PR.
Commit Logs
Many pull requests have only one poor description commit. And it includes every change in the PR. IMO, it is a waste of commit feature. Commit logs should tell the process of solving the problem, a series of small changes. It reflects the implementation flow.
- A commit should capture a single "logical" change if possible. It is the same as the Single Responsibility Principle in software development.
- A commit should have a "good" commit message. At least it should help you, the developer, understand what has been implemented in that commit.
- The commit logs (all commits in a PR) should form an implementation flow, which is very important. It is like a checklist for both developers and reviewers. One can figure out what was missing by reading the commit logs.
There is pushback. What is a single "logical" change? Well, there is no definition. Developers have to practice and improve their judgment over time. It is also the magic of this practice. It makes developers better.
Resolve Code Reviews
If possible, resolve a comment in a commit. It is much easier to track what has been resolved and how – by looking at the commit detail.
Small practices can make a big difference.
