Editor’s note: This is a programming-related blog post; if you don’t program or your don’t know what a pull request is, you probably won’t get much value out of reading this.
Disclaimer: I currently work for GitHub, and I work on the pull requests team. I’m writing these thoughts about pull request in my personal capacity, and I don’t speak for GitHub (although I bet GitHub agrees with every word I say here).
The pull request’s most obvious value is as a tool to ensure that you are merging in high quality changes to your software. And that’s probably what you’re primarily using them for. You’ll post a PR with your changes, and a story behind those code changes, and you’ll spur a conversation that ideally ends with you improving and merging the code (or sometimes closing the PR without merging because of stuff you hadn’t considered, and that’s okay too!).
But that’s not the only thing a pull request is good for!
As someone is reviewing your pull request, it gives your PR a second, and equally important purpose: spreading knowledge! Now that others are reading your PR, you’re not the only person who knows how it works. It’s less risky for your company when more than one person knows how something works.
And if that’s not enough, a PR is a gift that has the potential to keep on giving, even long after it gets merged.
A merged PR serves as an excellent artifact. It is an immutable record of the actual changes to the code, but also it’s a glimpse into the developer’s state of mind from when they wrote it.
Awhile back, I was working on preparing some queries for an upcoming change in our database setup, and I noticed that there was a piece of code that conditionally would either take a list of IDs or a scope that represented a set of records. A comment in the code told me that taking the scope instead of the IDs was faster, but it didn’t say much else.
I was about to revert that change, so I was interested in knowing more.
GitHub ProTip™: If you’re looking at a commit page in GitHub, it’ll show you the pull request where it got merged, which is super handy:
And in my case, I was able to look at fuller context behind that optimization, and I learned two important things: 1) the PR was over six years old, and that decision was based on very old assumptions about our database size and setup, and 2) the actual improvement in performance at the time was not huge. Armed with that knowledge, I deployed my change with better confidence (still using Scientist, of course), and I was tickled to learn that indeed, my approach came with a modest performance improvement in most cases.
Pull requests aren’t just good for developers looking for extra context behind an old code change. While your individual commit messages might be full of gems like WIP and fix that linter error for real this time and this really should work now, the PR itself becomes a place where you get to craft the story the way you want to.
If you have a docs team or a team that constructs release notes, PR descriptions are probably a lifeline for them, serving as an initial draft of what will become the user-facing release notes.
And if you release something and discover a bug that a PR introduced, the PR is even more helpful, because it’s an opportunity to see if the bug or bad behavior was expected or considered.
The PR is an important cultural contribution to how software development teams work together. They might have been introduced as a way to make it easier to merge in changes, but secretly they were a Trojan horse that also got software developers unknowingly to produce useful, human-generated documentation without skipping that step, because now it’s part of the software development process.
Leave a Reply