The debate around how best to communicate code changes has been raging since punch card programming.

Behold! A PR from 1970:

Complete with commit messages: PROJF SLOW VER, GDRAW, PROJF DEMO, XEQ GDRAW, PROJF FAST VER. If these kinds of commit messages look like the ones in your repo… I’m deeply sorry. But there’s still hope!

*** Note in this article I'll be using PR title and commit message pretty interchangeably, as I believe that all PRs should only contain one commit. To read more about that check out stacking.dev ***

While we’ve come a long way since the 70’s, there’s still a lot of disagreement on what the absolute best way to write PR titles/commit messages is. Most organizations and open-source projects typically dictate messaging style in their contribution guidelines. Angular’s contributor guidelines, for example, specify that “Any line of the commit message cannot be longer 100 characters!” On the other hand, Linus Torvalds specifies “74 characters" in his contributor’s guide for Subsurface.

There also exits whole projects specifically dedicated to standardizing PR/commit messaging, such as Conventional Commits, outlining a spec that has been adopted by various opensource projects and organizations around the world.

While it’s fine and good to have opinions based on ideological fervor and passion, I prefer opinions based on facts based on data! Today, we’re going to quantitatively dive into what makes a good PR title.

(For all the correlation ≠ causation folks out there I totally hear you, but sometimes it’s fun to jump to conclusions 🙂.)

The optimal PR title

For the sake of this exercise, let’s assume that the primary purpose of a PR title is: “get your PR reviewed quickly.” It’s also fair to pick titles for things like… “quality,” but for now, we’ll leave that to the contributor guides. If we put everything else aside, what is the best PR title optimizing for “how fast can I get reviewed?” Here’s your data-backed answer:

(Sampled from 2 million PRs, of length 50-250 lines, with at least one review, comparing median time to first review)

• Make your title short (under 40 characters, ideally)

  • 18% faster than 100 char titles

• Include an exclamation point but not a question mark

  • 30% faster with an exclamation point

  • 3% slower with a question mark

• Keep it all lowercase

  • 47% faster than titles with any capitalization

• Keep it PG (no cursing)

  • 10% faster without any curse words

• Do include “quick” or “fast”

  • 3% faster

• If on the fence, use the word “fix” instead of “feat”

  • “fix” is 73% faster than “feat”

By plugging all of this information into our supercomputer, we can derive the scientifically perfect PR title.

And we get…

fix!: delete prod!! fast!!!

Coming in at a mere 27 lowercase characters, with exclamation points, zero curse words, and with the words “fix” and “fast, I can guarantee you this will be reviewed within seconds.

Feel free to title all your future PRs the same.

PR titles matter

The average professional engineer (more than 200 PRs a year) authors nearly 600 PRs a year (590) with a median time to review of 1.34 days. That's a lot of titles for a person to have to write. And how they write those titles matters - even a 10% increase in PR review time would save the average engineer 80 days of waiting around for review. You can view your own stats here to see how you stack up with the rest of the coding world.

Now, to be fair, engineers aren’t completely blocked while they wait for review. If they’re using Graphite and leveraging stacked PRs, they can even begin work on dependent features while they wait. We’ve found the median engineer has three unreviewed PRs concurrently awaiting feedback at any one time. So, if we divide the 80 days of waiting by 3 — that’s still ~27 days of waiting time that could be saved by a 10% increase in review speed.

The official style guide for fast PRs

At Graphite, we obsess over the details so you don’t have to. In summary, for a faster review, we recommend a PR title be:

• Short

• Lowercase

• Categorized as “fix” (if appropriate)

• Include an exclamation point

• Clean (no swearing)

Incorporate this framework into your existing PR writing flow, and let us know how it goes by messaging us in our community slack!