How To Create A Good Pull Request

Creating a Good Pull Request is quite challenging for new engineers. It adds additional burden on working and making the PR look better. I have been reading about and listening to my peers and mentors on how to improve the ways to create a good PR. The rules and styles vary by company but there is still a standard that I try and encourage others to follow. This article is going to point out some best practices that will make code reviewing easier, not going to dive into the code level details.

Meaningful Branch Name

It all starts with a branch name, it is always suggested that branch name should be meaningful enough to reflect what changes are done in it. Also, I try to start the branch with a Jira Ticket number followed by few keywords, for example, ABC-123_Removing_Feature_X. This also makes it easier to track changes with respect to the tickets.

Stick To What’s Required

I see this as a very important point, making sure to do only the changes that are required. I have experienced this many times, whenever there is a slight change required, we simply update that within the current branch, ignoring the fact it belongs to a separate branch.

Split Big PRs

PRs should always have minimalist changes unless there is a reason like code refactoring. It makes it difficult for the reviewer to go through if there are more than like ten files. If possible, splitting it into multiple PRs is highly recommended.

Meaningful Commit Messages

Typo errors and shot vague commit messages are very common. Writing a full commit message with additional description in the body is very useful for code reviewers. Even if you go back one day, it would be easier for you to see what you did actually without going through the code. git commit gives you the option to write body as well, a short and common way is git commit -m <message>.

Recommended reading: How to write a good commit message.

Add PR Subject And Description/Comment

Since we use Github, there is an option to add a subject and description. Subject is usually assigned automatically based on branch name or commit message but it's not clear every time while the description tries to pick up the commit body. By following the above mentioned point you will have a nice and clean subject and description otherwise you should explicitly define a good subject (less than 50 characters) and a detailed description. Also, a good practice is to add the relevant screenshots, ticket links and other related PRs' reference in the description/comment section.

Rebase vs Merge

Start using rebase instead of merge, usually to sync our branch with master we do git merge master but there is actually a better way to achieve that goal using git rebase master. This article gives a detailed explanation of how rebase makes your git history better. If you forgot you can still squash them afterwards.

Squash Your Commits

In git there is a nice way to clean your commit history by squashing them together. The purpose is to merge all the commits that you think are useless into one commit with a meaningful message, it can be either testing commits or those that should have been committed together. Squash does not delete the commit messages instead it merges them in the body of the parent commit. The same article provides details on interactive rebasing.

Bonus

I have been going through a lot of top open source projects' PRs, and I found out that it is one of the best ways to learn the best practices. The reviews done by top engineers on PRs are very helpful.