What Makes A Good Pull Request?
This article explains what a pull request is, how to structure them to communicate clearly and why that is important.
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 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 to 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. These are summarized on a timeline as 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 pull request, like a working log.
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.
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.
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
Maildrops & Articles
Join my circle and get updates when I write something new. No spam ever.