Forcing Functions For Great Pull Requests
Why some development teams might naturally write great PRs
There’s a lot said online about why we should craft good pull requests, and how to do it. Despite how well accepted this seems to be (bordering on “common knowledge”), I haven’t observed this to be common practice.
I’ve been thinking about this a lot lately, especially since I begin my journey on a new team, at a new company — and since my previous team and current team have very different PR writing cultures. This got me to ask:
Why is it that we consider writing great PRs to be obviously beneficial, and yet we do not see the expected widespread adoption in practice?
Reflecting on my own experiences, I’ll offer my thoughts on some forcing functions that might naturally incline development teams towards producing higher-quality PRs.
My criterion for high-quality PRs is quite simple (but not easy):
The team reviewing the PR is easily able to glean the context for the work, this includes newish team members (2+ months) — At a minimum, this should include information about why we are doing this work, how it is being accomplished, and being explicit about risks and assumptions.
The work itself has been broken down and structured in a way that makes absorbing the entirety of the changes easy within a relatively short time window (1 hour at the most). Usually, this manifests as well-structured commits that build on each other and tell a story.
The current state of things
There’s no shortage of content on the internet advocating for writing “good” pull requests. Search for:
“Why should I write a good pull request” (365 million results), or
“How to write a good pull request” (601 million results)
And you’ll find an endless supply of opinions and blogs about the benefits of writing good pull requests, and even some guidance around what a good pull request might look like.
For the “why” in particular, the themes across the articles boil down to the following:
You (the PR author) want to make it easy for the reviewers to understand your changes and help you ship those changes.
Well-written PRs serve as documentation for future developers (including future you!) around the rationale for certain changes, or the approach taken to introduce them i.e. capturing context.
A well-written PR provides an opportunity to rationalize and justify your changes, making your thinking clear to others, and giving people an opportunity to challenge your rationale for the changes or the approach you have chosen.
This all makes sense in theory, and yet…
Despite these benefits being widely known and the “how” made easier through mechanisms like PR templates, well-crafted PRs are anything but ubiquitous.
Empirical Observations
In my career so far, I’ve seen some teams naturally gravitate towards well-crafted PRs, and other teams adopt them begrudgingly at best, seeing it as “process” and “paperwork” that distracts them from getting their code shipped.
The teams that take pains to craft good PRs understand the theoretical benefits, but are often subject to subtle influences (behavior shaping tendencies a.k.a forcing functions) that sustain the practice of writing great PRs until it becomes a part of the team’s DNA.
Here are some forcing functions that I have observed and experienced:
A team with varying experience/skill levels around the language, tooling, or framework being used to deliver the work. Varying levels of expertise force the simplification of the presentation (the PR!) of that work.
Closely related to #1, varying levels of familiarity with the codebase/systems being changed. Everyone on the team may be on an even footing with their technical chops, but they don’t all understand every part of the codebase, therefore forcing the change to be explained and presented well before being merged in.
New teams, where team members don’t know each other very well (yet), result in people putting a lot of effort into clearly communicating the “why” and “how” of the changes they are trying to ship.
Closely related to #3, a team that is changing often (people coming onboard, as others leave the company or transfer to other teams). This incentivizes well-written PRs as a mechanism to capture and transfer context. Situations like this might be common in companies that encourage high mobility, or the nature of the team necessitates a relatively short tenure.
Some teams work with many stakeholders that need to know the context of the work being shipped but aren’t experts in the codebase or technicalities of the work. Product Managers, Designers, and Engineers from adjacent teams contribute to the codebase via inner-sourcing efforts.
The codebase has history or context, such that the commits in a PR by themselves are insufficient to tell the full story. OR the codebase represents a system that has complex interactions with other systems, and the change being made must be coordinated with changes to those systems.
What other forcing functions have you seen? Are you an Engineering Manager or team hoping to improve the PR writing culture on your team, and could you leverage any of these forces to shift your team’s culture and practices around PRs?
Resources
About Pull Requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
Forcing Functions: https://en.wikipedia.org/wiki/Behavior-shaping_constraint
7 Reasons For Good Pull Request Descriptions — https://frontside.com/blog/2020-04-15-7-reasons-for-good-pull-request-descriptions/
How To Write The Perfect Pull Request — https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/