Why do we have pull requests?
As software developers, we enjoy that feeling of being immersed in the flow, that wonderful state of being where hours whizz by in an instant, and our mental model stands clear; where we can be hyper-productive as long as we can keep the outside world at bay and remain in blissful uninterrupted solitude.
However, building modern software is also a complex team sport where collaboration and continuous feedback loops with fellow developers are key to personal development and high-quality code.
Code reviews are the most obvious contact point with other developers and a foundational process in working towards becoming a part of, remaining in or working towards building a high-performing team that creates code that is stable and fun to work with.
While one on one code reviews likely offer the most value in terms of learning from each other and making available stable applications to our end users it is unfortunately not always practical to meet face to face. We are frequently working on different schedules in distributed teams or require input from multiple people to weigh in on a design decision all reasons making it unpractical to talk one on one about our code.
Fortunately, the development community has been steadily iterating on the process of reviewing code contributions from developers distributed around the globe. Through many iterations and trial and error of sharing patches via email, IRC, forums, and various other communication channels we are currently positioned to take advantage of the “Pull Request” concept for conducting code reviews.
The concept of a pull request as a mechanism for conducting code reviews is built into all popular modern code management platforms like GitHub, GitLab, Bitbucket and others.
In simple terms, a pull request is simply a request to get input from fellow developers on some code that you would like to contribute back to a project. Depending on the platform in use there are various features for working with pull requests but usually, there is a forum-style feature set used to discuss and reason about source code changes.
What is a pull request?
Ok, so let’s take a stab at a definition of a pull request.
“A pull request is a form of code review that is facilitated by a code management application that provides communication mechanisms specifically designed for talking about specific source code changes. In other words, it is a technical solution for conducting asynchronous code reviews, typically before accepting code into the code base.”
Before digging a little deeper into the pull request, I want to take a quick detour and encourage you to think about what type of developer you are striving to be and to think about your work in the context of your team. Ideally, you are reading this with the motivation of striving to be the best developer you can be and that includes thinking beyond the code. Hold that thought in the back of your mind as we move on.
Alrighty, so back to pull requests. Recalling that pull requests are a mechanism for discussing code it then follows that a pull request is an opportunity for learning and expanding one’s development skills. The net result is an improvement in the ability to craft quality code.
Things to consider
I want to now list a train of thought that you may consider following as a starting point for developing your own thinking about pull requests.
So, let’s start with the following: I want to ensure my code is of high quality and I want to try and discover something I did not previously know. I’m therefore seeking to take advantage of collective knowledge embedded in my peers and in those that may be more experienced with the code, language, design patterns, algorithms and so on.
Furthermore, I can empathise with what it feels like to be interrupted and how little time we have for the fun part of our job, that is, the actual problem-solving and writing of coding.
Therefore, I need to ensure that my pull request is easy for others to reason about and work with.
Finally, I want to use this opportunity to ask any specific questions to learn and make it simple to iterate over suggested code changes.
Pull request checklist
What follows is a mental checklist of points to consider before submitting your next pull request.
- The pull request description provides enough context to what the code is supposed to do through the lens of the end-user.
- I have asked specific questions on areas of uncertainty.
- Where I use a non-obvious approach, I have explained why I avoided the obvious approach.
- I have considered splitting up this pull request if I have more than 250 lines of functional code. Ignoring boilerplate/comments/styling.
- The commits in the PR have been squashed to related code changes.
- The code is technically related (cohesive) and focused on a specific feature.
Following, the above will put you well on the way to getting the most out of your pull request and hopefully make you rethink the notion that a pull request is simply a hurdle to getting code into a project.
In a follow-up article, I want to take a dive into GIT and share some techniques for using GIT to craft pull requests that will delight your teammates.
🍺 Happy Coding! 🤘