Create A Great Pull Request In Just 5 Steps [A How To Guide]

First of all, congratulations! You have come this far. Creating pull requests is the last step to propose your code to the code owners as well as other contributors. It is really important to have a great pull request as it would help the reviewers to understand and learn from your delivered code better. This article will show you how to make Pull Requests great again just in 5 steps.

1. Branch

Branching means you diverge from the main line of development and continue to do work without messing with that main line. The way Git branches is incredibly lightweight, making branching operations nearly instantaneous, and switching back and forth between branches generally just as fast. —  Git document.

A new branch should be created from the latest code of its destination branch from upstream. This means, at the point of branching, the local branch’s HEAD commit must be the same with the upstream branch’s HEAD commit. It will help to make the history of commits in the upcoming PR clean. In order to do it, if you are using Git command, you could follow these steps:

git fetch --all #1
git checkout upstream/dev #2
git checkout -b Feature/New #3

#1 to fetch all the latest code from your remote repos.
#2 to check out the latest code of development branch on upstream.
#3 to create a new branch named Feature/New from the latest code of development branch.
You also can use SourceTree and apply the similar steps above to achieve the same thing.

About naming, you mostly see master, release, or development as a common name for a branch. However, for refactor branches, new feature branches, or bugfix branches, what will you name?

I would love to suggest 2 ways that you could choose up to your preference.

● Ticket number or issue number-based names

Let’s say you are working on a Jira ticket VAJ-96, to fix a bug in Home Screen. Then you can just name the new branch as

VAJ-96/Fix_Bug_In_Home_Screen

As one ticket might require multiple branches to complete, this naming convention can also be applied. Like these

VAJ-96/Fix_Bug_1_In_Home_Screen
VAJ-96/Fix_Bug_2_In_Home_Screen
VAJ-96/Fix_Bug_3_In_Home_Screen

● Branch type based names

In the development cycle, there are at least 3 branch types including Feature, Fix, and Refactor you will be working on. We can categorize our branches based on it just like these

Feature/Pet_Dating
Feature/Music_For_Pet

#or
Fix/Loading_Issue
Fix/Crash_In_Home_Screen

#or
Refactor/Duplicated_Code
Refactor/Module_A

One of the benefits you will see clearly if you are using Terminal is to use the auto-completion feature. If you are using SourceTree, this is how it looks like

We can easily categorize the branch following the convention. 

2. Commit

In order to have a great pull request, we need to have a great list of commits. Therefore, it is important how we define a great commit. 

● Commit’s content

A commit should only contain what it needs. It is better to commit whenever you get something done regularly. It would help you in case you need to revert some of the commits or cherry-pick any commit to other branches as well.

Don’t wait until everything is done to commit, neither to commit every line of code you write. For the honor of being an engineer, do it right!

● Commit’s name

Have you ever seen a commit like “this is a commit” or “fix todo”, or “I don’t know what I am doing”? Sounds funny, but it happens every day. Honestly, it would become a nightmare in the future if you or your teammates looked back for something.

For that reason, commit’s name should tell the changes itself, it might look like these

Fix: - Fixed the crash on Home Screen.
Feature: - Implemented playground game view.
Merge: - Merged latest develop to the feature branch.
Chore: - Increased the build number on Production configuration.
Refactor: - Replaced Singleton pattern by Dependencies Injection.

Let’s keep the message short but explicit. It might save your life one day!

Last but not least, a pull request will not be great if the code within is not clean nor correct. Therefore, it is super important to make sure that the code you wrote is clean, well structured, optimal and follow your (organization’s) conventions. My recommendation here is to act as a reviewer and review the changes by yourself one last time before creating the pull request at step 3. If there is anything you think could be better, make it better! It is to make sure that the code you are requesting others to review is at your best. Hence, it would help to save you as well as other reviewers a lot of time later.

3. Propose

A great pull request should have a clear name, following with detail descriptions and additional tags or labels.

An example of one of my great pull requests.

● Pull request’s name

The pull request’s name should tell the changes itself generally, to give an overview idea of what the pull request is about. Well, it can just follow the commit naming standard that we have seen above.

● Pull request’s descriptions

The description helps the reviewers to understand better about motivations behind the code, achievements, and contributor’s explanations.

WHY — Which tickets/issues/proposals you are working on? 
WHAT — What have you done?
HOW — What the reviewers should know?

I am attaching the template here so that you can just download and put it in your source repo. It will automatically fill the default description for the next pull requests.

### Jira ticket: (or Issue number, or Proposal number)
Please pass the requirement information link which are related to this PR here

### What has changed:
1. Please list down what you have done here
2. Please list down what you have done here
3. Please list down what you have done here

### What reviewers should know:
Please highlight what reviewers should know when reviewing this PR
For example, your new proposal algorithm, your new proposal architecture
Or, show the gif to demo of how the screen you implemented works

A pull request template that you can download to use directly.

● Tags, Labels

Sometimes you want to add more information for the pull request so that we can have a better filter and overview. This is an optional step.

An example of one of my great pull requests.4. Review

A great pull request should have responsive interactions among reviewers and contributors.

The reviewers might or might not give you feedback on the code before they approve. In the case they do, it is important to make sure that you understand the feedback correctly before making any changes.

Conflicts might happen at this point as people may have different approaches.

So, if you think the code is perfectly right or your solution is better, debate respectfully and explain it to the reviewers calmly. Otherwise, don’t you hesitate to modify your code then commit new changes, it’s totally fine.

On another side, if you are the reviewer, my advice is to focus on the code, not the person. Do it professionally and frequently, it will really help you as well as others.

Don’t you spend too much time to debate or even make it personal. At the end of the day, we are one team trying to contribute to make the world a better place, not to fight, right?

Photo by jesse orrico on Unsplash

5. Approve, Merge

After resolving all the change requests and getting the approvals, you now can merge your pull requests to the destination branch. There are multiple strategies to merge pull requests. However, two of the most common strategies I’m using are creating a merge commit on top of the commits in the pull request and squashing all the commits in the pull request into just one merge commit.

Shortly, the first strategy is mainly to merge a big feature or a refactor branch into a destination branch, to keep the history of commits. The second strategy doesn’t care about the history of commits in the pull request. It will squash all of the commits then create a new one to make the history simpler and cleaner. Therefore, it’s mostly for a small feature or a quick bugfix branch.

Merged?! It is now up to you and your branching model to decide either to delete the original branch or to keep it for future references. Anyway, sit back and relax.

Congratulations to get your task done. Take a break and get to a new task!

Thank you for reading. I do hope you enjoy the article and please feel free to let me know your thoughts on these steps.