What Makes A Good Pull Request?

Writing is a vital skill and a continuous activity for professionals working with software engineering. Whether you are creating a JIRA ticket, crafting a wiki page or composing an email, clear communication through writing is crucial for effective collaboration.

Creating Pull Requests (also referred to as: PR) is not an exception. A well structured and written pull request can be a deal breaker for launching a new feature in your team. And there is more to it than simply shipping code when contributing to the solution.

This article explores the basics of working with pull requests and the importance of writing well. We will explore the structure and the way we communicate when contributing as a software developer in a collaborative team.

Let’s dive in!

What Is a Pull Request?

During the spring of 2022 I created my first pull request. I got my code changes approved, merged and shipped to production! A personal milestone for a beginner coder like me.

But what does this really mean and what is a pull request to start with?

When we work in teams, we want to keep our team-mates up to date on what we are working on. We need to show our work so that we are aligned on our mission. We want to make sure we all work towards the same goal, right?

It is not about others micromanaging, more about collaboration. I like to see it as a process where you pull your teams attention into your contributions and asking your team for input and review.

In a software engineering team, a developer needs to tell the other developers about the changes he/she has done in their repository. This is a key step when shipping continuously since you apply a “4-eyed principle” and gather up all competencies in the team. A beautiful mix of shared responsibility and personal accountability.

When you open a pull request you also open up the discussion with your collaborators so that your work can be reviewed before it is merged into the main branch. That is where the latest updated code rest. Until it get merged again.

“The central repo holds two main branches with an infinite lifetime: master and develop.” — Vincent Driessen

The Structure — The Why, The What and The How

The main structure of a pull request is made up of clear communication line starting usually in your preferred development environment and/or command prompt and visualized in your code repository (Gihub, Bitbucket etc.).

Starting With Why

Provide a concise title-description stating the purpose of your pull request. Whether it is a new feature or a simple typo, a crisp title makes it easier for anyone to know what to review and why.

When you are ready to open your pull request you also open up your creative ability to explain The What and The How. In this section you can use screen-shots, videos of your application and even GIFs to serve your reviewer an easier way understand what the code change looks like.

In the example below I chose to include some text due to the simplistic nature of the change. The more complex the change, the more creative you can be.

Crisp Commits & Clear Comments

Another way to make your reviewers life easier is through self-explanatory messages.

Usually there are several commits that adds up to one pull request. When we work on a feature and add our changes to the working directory. When you commit and push them to your branch they will also be visible in your cloned repository.

Writing a clear and concise message in your commits will immediately lead your team mate into what the foundational pieces are for your pull request. They can look something like below

Another way to present your pull request, which I really like, is by using a checklist to easy present what is in scope and what has been done.

Small, Fast & Nimble

Finally, I would like to push for the importance to keep the pull requests small.

Keeping them small removes the risk of burdening the review with complexity. A big pull request with big chunks of code puts your reviewer in a blurry state where it is hard to find any valuable insights.

The smaller it is, the higher the possibility is for finding issues and valuable feedback in the code review.

The bigger the pull request the harder it is to find valuable input.

That was it for this time. I hope you found this article useful. These simple ideas are easy to skip over from time to time but it for sure makes it easier for all of us to collaborate effectively when contributing to the same code base.

Especially when working remote.

Further learning

Here are some good online resources if you want to dive further into the realm of version control and learn Git.

If you just want a high level walkthrough
What Is Version Control?
Making A Pull Request

If you want to get your hands dirty
The Beginners Guide To Git & Github

If you have chosen to get your hands dirty and you got stuck
Git Cheat Sheet