General

Four simple steps for a well crafted Pull Request

Gnaneshwara
Babu

November 2, 2022

4

mins

Image courtesy: Wikipedia

This post will concentrate on enterprise collaboration and the key elements of submitting a well crafted pull request. I want to provide you with some valuable information and walk you through the different stages of a pull request during the code review process until the code is merged to the main branch.

Writing clean code is an important attribute of a good developer and part of neatly designed and maintainable software. Building well designed software or an application in a large enterprise is accomplished by a team of developers working in a collaborative environment. In the modern day software development teams, Git is the de facto choice for source control. Git forms the basis for collaborative teamwork along with a sound development workflow. As developers work in the team, Pull Requests (PRs) are a great way of submitting contributions to a project and working collaboratively, especially when there are multiple developers working on the codebase at the same time. They are a medium with which developers can review code, receive feedback and increase visibility for the changes they are shipping.

What is a Pull Request?

In a nutshell: A Pull Request (or widely called a PR) is a request to introduce your code changes into a repository. Once you make the changes, you submit a PR. Once submitted, another member of your team is notified or requested to perform a code review and provide you with any feedback or changes required.

The changes are then agreed by approval or passing the defined unit tests and will be merged into the main code base (main branch).

 

Step 1: Create a Branch

As a developer in a team, we will pick up a specific task to work on, or we have identified a solution for a problem that leads to a change in the codebase. These changes are introduced in the form of Pull Requests. As a first step, always create a separate branch to introduce your changes to the code base. This ensures that you have flexibility to work on the code and have the freedom to test the code with various data-sets. This stage will help you to:

  • Estimate the time required to complete the change
  • Estimate how big the change could be

During this phase, plan to split your changes into multiple commits. This will help save time for yourself and the reviewer. Having smaller changes in each commit will make it easier for the reviewer to understand the changes you are going to introduce. Larger changes will make it complex and time consuming for the reviewer to understand your changes. Always remember that you're requesting someone else's time during the review process and respect their time.

Creating a separate branch also enables you to perform tests on your own to ensure the changes fit into the wider code base and doesn't conflict with other moving parts.

Step 2: Push to Remote

The next stage in your PR process is to push your local changes to the remote repository. The remote git host (GitHub/Bitbucket Remote for example) will allow you to create a Pull Request for your newly pushed commit. You will have two different options while submitting a Pull Request at this stage:

  • Draft Pull Request (Work in Progress)
  • Pull Request

Draft Pull Request (Work in Progress)

Deciding between submitting a draft pull request and pull request depends on multiple factors. Submitting a PR in draft is always useful if you are still working on your changes but at the same time you also want to let the team know about the work you’re doing. It will also help to see the full pipeline run with all the integration tests, just to make sure you are not running tests locally. This will allow you to visualise how your changes would interact with the entire codebase in an end to end workflow. This will allow you to pick up any triggers that would cause any unexpected behaviours in the build pipeline.

This will also allow you to get into the shoes of the reviewer, take a step back and review the code from the reviewer's point of view. Run through all the steps in the CI pipeline and evaluate how your change would fit in.

Reach out to the reviewers if they need to provide any specific feedback at this stage, this will also allow you to let others know that you are working on the proposed changes. At this stage continue to work on the change and keep submitting additional changes in the form of small commits into the same PR.

 

Step 3: Submit the Pull Request

It's the time you say to yourself, “I am ready for the change to be merged!” 👍, You have passed all the integration tests and are confident about the code changes. Now is the time to either create a pull request for your locally pushed commit or convert your draft pull request to “ready for review”.

Once you submit the PR, you can either tag a reviewer on the PR, or in some organisations, the PR process will automatically trigger the review process by assigning a group of users as reviewers. In a normal enterprise practice, the PRs will not be merged until it has been reviewed by at least one of the reviewers.

Here are some of the best practices for PR hygiene to follow when submitting a PR.

  • Make sure all the integration tests are passed in the build pipeline. The green tick always looks better!
  • Normally your first push of a local commit will be the title of the PR, revisit and review the title of the PR. Make sure the title is simple and precise.
  • Add additional details to your PR in the body, explain the purpose of the changes you are making and add a screenshot of any proposed design.
  • Perform a final self-review.
  • Tag the reviewer if you intend to get feedback from a particular person.

Constructive Feedback

It always feels good to have someone else backing your work. Once you submit the PR, it's feedback time. The reviewer will start looking at the code and  make suggestions to improve the code or prevent the introduction of bugs and issues. The feedback will be provided in the form of comments, either at every line of code change or a  general comment. Don't take feedback personally, the reviewer's intent is to look at how your change would fit into the wider codebase.

Acknowledge the feedback, discuss with the reviewer if you have a difference of opinion and if necessary make changes as per the request by pushing a new commit. Follow up on the new changes and  make sure they are closed or approved. Close all the feedback loops in the PR workflow by "resolving conversations". This ensures acceptance from the reviewer(s) and means you are ready to merge.

Step 4: Merge!

After going through the complete PR approval process, it's now time to merge your changes to the main branch. You can now go ahead and merge your pull request into the main branch. Each organization follows a different merge strategy, adhere to these principles while merging your PR.

Don't wait too long to merge your PR after obtaining approval. If you do you will likely find merge conflicts have been introduced as changes from other team members have been introduced and merged.

A few sanity checks to follow after the merge:

  • Make yourself available and reachable. This is to make sure you resolve any issues in the production environment due to the new change.
  • Update the stakeholders about the change and monitor the change.
  • Make sure your feature/update branch is deleted after merge.

Conclusion

We’ve walked through a complete journey in the PR process. We created a branch on the remote and pulled it to the local system to make changes to introduce either a new feature or resolve a bug. We pushed these changes to the remote branch or to the code base by pushing our local commits and raising a pull request. We worked with colleagues to receive feedback regarding the change and merged the change into the wider code base (main branch). Every step I explained here is based on my learning while working in an enterprise. I have tried to provide as many details as possible to make your PR journey successful every time you create a new pull request! 

Reference:
About pull requests - GitHub Docs

Next Article

Looking for a new challenge?

We’ve got ambitious plans to be the best Microsoft solutions company in Australia and New Zealand.