Practical PR authoring tips

21 Jun 2023

I have been working for GitHub for a few years and, as you surely know, GitHub is a big fan of pull requests. The teams I have been working with have been mostly distributed anywhere between UTC+2 and UTC-7 and that meant very little overlap opportunities for synchronous work. At the same time, during my tenure at the company, I did quite a bit of opensource work on ExternalDNS, which meant working with different sets of people, different cultures, different skills and, at the end of the day, different ways of collaboration. Those asynchronous ways of working gave me a new perspective on the importance of well structured pull requests. I want to talk about some of this today.

Pull requests as a unit of work

The main reason we write pull requests is to modify or add something to an existing project. Pull requests are a way to contain a unit of work. At GitHub, that work is done when the pull request has been discussed, reviewed, approved and deployed. GitHub is still using the “GitHub flow”, a model of work in which pull requests are deployed before merging them, which makes it so that a piece of work is done when it is proven in front of customers. It’s a powerful way of working with PROs and CONs, especially at scale, which I’m not going to describe now. Funnily enough, while this approach should help with the definition of done and thus work estimation, it really doesn’t, but that’s also a more complicated topic for another time. Anyway, enough with the context, for the rest of this post, I want to focus on who we write pull requests for.

Who do we write pull requests for

Pull requests are not a way to limit contributions to a codebase. I’d argue that the main value they bring is not even “code quality”. The main value is communication, sharing context and establishing relationships with the people we collaborate with, including our future selves.

Given that, my approach throughout my years has always been: write for the next person who doesn’t know anything about the work, for who is interested in the reasons behind the work and write for who is interested in all of the little implementation details. But even more, write for yourself a year from now or your colleagues when you will be working somewhere else, so that you can go back and try to understand why something was made in a certain way. I’ve used this mindset countless times and it has been a superpower during debugging, refactoring or simply when explaining to colleagues why things are in a certain way.

How to actually do that

My practical PR authoring tips are:

• Write a great description: say what the PR does, why the work is done in the first place, what alternatives have been considered, link related work. Note that this doesn’t always apply: sometimes you just need a quick revert and need to go fast, some other times you want to open a PR early to show an idea and don’t have a lot of things to write yet. You will likely have time to go back and edit the description for most of those cases.
• Remember that you are not coding for yourself: you are most likely contributing code to a project that is not your private project or to a codebase owned by your employer. In those cases, the code is not yours, so you shouldn’t put yourself in the position of wanting to win an argument with a specific approach, rather to do what is the right thing for the codebase that you are contributing to.
• Do a self review: After opening the PR, I always go through it and review it myself. I normally try to anticipate questions that I think I will receive and try to add an inline comment to anything that could be controversial or a major decision point for the implementation that I am contributing. This approach helps to have the discussions on decision points that I know we may want to have, especially if there are major decisions that may influence the project’s future.

I don’t do all of those things right all the time. Sometimes I go too quickly, sometimes I’m not descriptive enough. Keeping those things in mind has helped me through the years to be a better contributor, both at work and in open source.