As a software engineer, our day to day job is to solve problems primarily by coding. Several years ago, we used to use FTP (File Transfer Protocol) to move our local code to the remote server. But that is highly non-practical, not secure, and hard to track the changes. So here comes the version control, a tool that is used to track the code changes (author, file, commit, and timestamp) and to ease the collaboration among software engineers. And the best way to introduce changes using version control is via Pull Request (PR).
Pull request for me is a "discussion platform" where every software engineer can jump in to review the code changes and approve it. But oftentimes, we don't do it in the correct way thus lead to headaches both for the reviewer and pull requester. In this post, I will share my knowledge that I get from experiences when creating a pull request to several repositories within my company.
Why
Before we go into the details, I think it's a good practice to raise the fundamental question:
Why do we need to create an effective and efficient pull request?
That's an interesting question. At first, I believe it's not necessary if we only have a pair of programmers and sit close each other. At this point, we can just ask our partner to review it directly in our local machine or even if we create a pull request, it doesn't need to follow any rules, because our partner must have known what we are doing all the time.
But, what if someday we need to work with hundreds of programmers from different teams across countries and in different timezone? The standard of each team's repository must be different: the branching strategy, the unit tests, the coding guideline, and PR review process itself. So this is when an effective and efficient PR is useful.
The effective and efficient PR consists of a set of basic rules that are meant to be generic, so hopefully, everyone can follow it. This PR approach has some characteristics which are has reasonable-sized, focused, and does not have side-effects. Those are needed to reduce the reviewing time, introduce no bug, and eventually to solve the actual problems.
General Idea
The first thing to notice when creating a pull request is to focus on the goal. What is the goal of the PR? Is it for fixing bug? Is it to introduce new error code? And so on. Once we define the goal, we can make the solution that is implemented in the code (addition/deletion). And the code should reflects that solution. Nothing more. So how can we do that? Here are my tips.
1) Focus to solve the problem
The PR should only do one thing and do it right. Let's say the goal of the PR is to introduce new error code and how to handle it. So the solution to that goal is registering new error code. In addition, unit test to prove the change is working properly and not breaking the current implementation.
For example, here is the simple PR to delete unused deployment files.
In contrast, in this screenshot below shows how the goal is not clearly stated.
2) Code changes should reflect the solution
Sometimes we are too excited to create a PR that does a lot of things. This is totally not a good practice. For instance, in the big feature PR, we also fix typo or translation or formatting. Instead of creating PR that does a lot of things, we can create another small and quick-to-review PR for that specific goal. So the changes are still aligned with the main goal.
An example of clean and straightforward PR.
However, this PR is doing unnecessary changes: extra line.
This type of unnecessary changes can actually be prevented by having a git pre-commit hook. In that hook, we can do formatting such as running a linter tool to standardize the code format (no-console statement, space, comma-dangle, and so on).
3) Create a pull request template
DISCLAIMER
PR template is only available for GitHub (as long as I know), not sure about the other platforms such as GitLab or Bitbucket.
A template could be very useful. With the little effort to create a template (typically with the name PULL_REQUEST_TEMPLATE.md in the root folder in GitHub), it can hugely improve our pull request review process. We can define the goal of the changes, the type of changes, and also the checklist which is a list of the repository's code policy. You can see the example of my team's pull request template below.
At a glance, as a reviewer, we can see the summary of the PR by just looking or screening at the PR description. Even better, a repository that has a built-in PR template provides a consistent and well-structured PR description so if the repository has so many incoming PRs, it won't be a problem for reviewers since there's already a standard for creating a PR description.
4) Follow the proper commit convention
Git commit acts as a short description that reflects the changes we've made to the file(s). Essentially, it should only have one goal and or context (and in my opinion should be stateless). There are many commit conventions out there, but the ones that I trust so far are angular and commitizen. The proper commit message will help the reviewers when they try to search something specific in the PR and want to fully understand what is the requester trying to achieve. But still, the file changes are the source of truth for the review process. Best practice from me is to avoid using a single word for each commit message. Use full sentence instead so the reader won't be confused.
Good, easy-to-read commit messages.
Unclear, incomplete commit messages.
Conclusion
This post is meant to cover the basic understanding on how to create an effective and efficient pull request. It doesn't explain much details as it aims to give the reader the brief principal to create an elegant PR so that the review process can run smoothly and focus on the substantial and significant things. Happy coding!
Top comments (0)