Good PR descriptions turbocharge productivity

Getting serious about PR descriptions reshaped my approach to software development. I watched it make our team faster, more insightful, and surprisingly more connected.

When I worked at Betteromics, compliance was an important focus. As a company in the life sciences space, meeting standards like ISO9001 gave us credibility and helped us land customers.

The way these standards work is that you undergo an audit, and the auditor is looking for interpretability and understanding.

For software engineers, this means that the auditor could look at any PR and ask "What’s this supposed to do? Why? How do we know that it actually works?"

This meant that every PR had to have a meaningful description that answered those questions.

At first, I was dreading this. I thought it would be a huge drag.

But it ended up changing how I think about PRs and the role they play for engineering teams.

Faster onboarding / context gathering

I often found myself reading a part of the codebase, wishing for more context, and then immediately clicking through to a relevant PR.

Tooling

I used a VS Code extension called GitLens for this, but you could also use the git blame command.

This allowed me to ramp up on new parts of the codebase much faster than if I had to reach out to a colleague with questions.

It also made it super easy to get curious and learn more.

PRs weren’t just a means to an end (getting code merged), they were an end in and of themselves.

They became a living library that documented the context behind changes.

Plus, every PR linked to an associated ticket, so you could dig into the discussions that had gone into tasks before implementation had even started.

What was in the PRs?

PRs typically included a written description and proof of testing:

Written Description

A written description that outlined what the PR did and why.

Example:

1This PR updates our styling code to use dynamic viewport units,
2which Tailwind now supports as of v3.4.
3
4This makes our styling behave more gracefully in environments such
5as mobile browsers, where elements are shown/hidden dynamically.
6
7To learn more about dynamic viewport units, go here:
8[TODO: write a post about dynamic viewport units and link to it here]

Proof of testing

Testing was usually done through automated tests.

That said, there were times when we didn’t write these.

In these cases, a screenshot or screen recording could be included instead.

For example, you might include a recording to show that a tooltip that you added was working as expected.

...or you might include a before/after screenshot of a button whose styling you changed.

In fact, even in scenarios where you did write automated tests, it was often helpful to also include a screenshot or recording — if only to help explain the change easily.

Making screen recordings felt a bit unwieldy at first, but it didn’t take long to grok and streamline.

Tooling

For screenshots, I used Skitch.

For screen recordings, I used QuickTime to record locally, then compressed the files locally with Handbrake so that I could upload them directly into my PR descriptions in GitLab^*.

This seemed tedious at first, but I got it dialed in quickly.

There are also both paid and free alternatives that give you a shareable link to your video, which is nice.

^* Technically GitLab calls them MRs, not PRs.

Conclusion

Now that I’ve seen the light, I can’t go back.

The productivity gains that I’ve seen on teams that write good PR descriptions makes it a no-brainer.

Plus, as the author, writing the description helps me linearize my thoughts on why this change matters.

That mental clarity has benefits in other parts of work, streamlining standup updates and elevating team discussions.