Git: Better Pull Requests for Large Feature Branch

TLDR: Break large Pull Requests into smaller related ones to receive better reviews. Summarized steps at the end of the article.

Most software engineers have either created or reviewed a large pull request at some point in their career. Such pull requests are difficult to review and should be avoided. Strategies such as feature flagging can enable frequent merges and reduce PR size. However, large PRs will inevitably emerge and it is up to the author to present the code as clearly as possible. One method is to split up the large PR into smaller related PRs. Some examples of the splits could be:

• a frontend PR and an API PR in a monolith application
• break up different parts of the UI into multiple PRs
• a feature implementation PR and an end to end testing PR

Method

Let’s walk through an example of splitting up a large PR. Say we implement a feature containing a main-page, some charts and a sidebar in our frontend web application.

Final feature folder structure

We push our feature branch remotely to create Pull Request for our peers to review, only to discover that we have added 1570 lines of code.

1,570 LOC

We decide it might be better to break down the PR into three parts: main-page, chart and sidebar. Taking a look at git log , we see that we’ve made updates non-sequentially to the different parts of the feature. (i.e. updating the main page styles after adding sidebar)

This means we cannot breakdown the PR by our existing commits and we have to rewrite our feature branch history.

STEP 1: Just in case we make a mistake, we clone our feature branch first.

STEP 2 (optional): This would be a great time to rebase and fix merge conflicts this branch might have with master.

Rebase on top of master

STEP 3: Now we can reset the files in the commit and re-add them in the order we want.

git reset HEAD~1

STEP 4: We first create a new branch part-1-main-page. Then we add all the main-page files, commit, and finally push the branch remotely.

Creating branch part-1-main-page

Step 5: Now we repeat the previous step with chart and sidebar.

Creating branch part-2-sidebar

Creating branch part-3-chart

Step 6: At this point, we have our branches created and pushed. We are now ready to create three different PRs.

Step 7: We will point the three PRs as such:
1: master -> part-1-main-page
2: part-1-main-page -> part-2-sidebar
3: part-2-sidebar -> part-3-chart

Here’s our three final pull requests:

We have successfully broken down a large 1570 LOC PR into three smaller and more manageable PRs. Once the PRs are individually reviewed and merged into one another, a final squash can be done before merging to master.

By creating three smaller PRs, the reviewer(s) can much more easily provide feedbacks and find potential bugs. By taking these extra steps, we can improve the quality of the reviews and with it, generate a healthier codebase.

Summarized Steps:

1. git checkout -b {clone-branch} // clone branch as backup.
2. git reset master or git reset HEAD~{number-of-commits} // reset the files to local.
3. git checkout -b {first-branch} // create first branch.
4. git add {files-for-first-pr} // add all the files for the first pr.
5. git commit -m '{message-for-first-pr}' // commit for the first pr.
6. git push origin {first-branch} //push branch to remote
7. repeat step 3–6 until all files are committed.