Minnesota Nice Pull Requests: Writing Better PR Descriptions

Minnesota is infamous for its winters. And despite our harsh winters, Minnesota continues to operate even when other states would struggle in the same conditions. You don't hear about massive vehicle pile-ups, power grid failures, and even flight cancellations as you do in other states. When a winter storm hits, it energizes Minnesotans. They are up for the challenge! And this is when you see Minnesotans at their best, putting in that extra effort to make sure their state keeps on running.

In a classic MN neighborhood, you have that neighbor who snowblows their sidewalk and ends up doing the entire block. If caught, they say, "Oh, I was already out here, figured I'd just keep going." That's the spirit of going above and beyond to keep everything moving smoothly.

In this article, consider how you prepare your Pull Requests. The Pull Request is at the tail end of a task. You've done the research, written the code, and completed the unit tests; you're now ready to merge this code. It is tempting to do the bare minimum to get that green check mark. But just like waking up to a ten-inch snowfall in Minnesota, this is a time to rally!

Put in the extra effort for your Pull Request

Like any author, you need to consider your audience, not just your peers, but also future maintainers who may have little context for the codebase. A well-written description communicates clearly to both audiences.

Let's examine some examples, starting with poor versions and then showing an improved version.

Example: The PR Description Only Refers To A Ticket

Poor

Fixes #1234

It's very common for a PR description to only refer to a ticket, assuming the ticket contains all the necessary information. While it is in the spirit of traceability, it also poses a risk. As soon as you change ticket systems, this reference can become meaningless, a.k.a link rot. Tickets are valuable references, but PR descriptions must stand on their own. I recommend that you always include a helpful description in your PR, along with the ticket.

Also, referenced tickets usually only explain the problem and not the solution. So, by including only the ticket, you're asking the reader to infer how you solved the issue.

Better

This PR adds an ARIA-compliant tooltip to the settings icon.
Before

Fixes #1234

And since this PR is UI realted, include a before and after screenshot, or video.

Before:

After:

Example: The Description Is Too Vague

Poor

Makes account activity view go zoom!

A vague PR description can happen when the author has already discussed the solution with the assumed reviewers, or when they think it will be evident from the code changes.

In this example, we improve it by not just explaining the problem and the solution, but also providing evidence of improvement.

Better

# Description
This PR adds a composite index on `(account_id, timestamp DESC)` to the `transactions` table, significantly improving the performance of queries that retrieve recent transactions for a specific account.
​
Previously, queries like the one below triggered sequential scans and required separate sorting steps, especially as the `transactions` table grew to tens of millions of rows, causing noticeable delays in the account activity view.​

```sql
SELECT * FROM transactions WHERE account_id = ‘abc123’ ORDER BY timestamp DESC LIMIT 100;
```

# Testing
* Confirmed composite index usage with `EXPLAIN ANALYZE`
* Benchmarked against a production-sized dataset in staging
* Query latency reduced by ~85%, from ~1200ms to ~180ms
* Verified no regressions in related endpoints
​
# Related Issue
Fixes #1234

Example: The Description Is Cryptic

Are you submitting a PR that is difficult to understand? A cryptic PR description can happen when you are too close to the code. You may have spent hours or days working on this change, and it is easy to forget that others don't have the same context. Does your PR description use abbreviations, jargon, or a complex idea? If so, consider defining or describing it first.

Poor

Added QTF support

Better

# Description​

Added support for QTF (Quantum Transmission Format) cryptographic protocol to the cipher suite, ensuring our encryption remains secure against future quantum-based attacks.

# Testing

* Verified QTF support in the `Cipher` class

* Added unit tests for QTF encryption and decryption

Setting Standards

These are a few examples of how you can improve your PR descriptions. Your team can land on a baseline for what is necessary in a PR description, and PR templates are a great way to do that. But watch out! A template is often the minimum required, not the maximum.

Also, is there redundancy between a well-written commit message and a well-written PR description? Definitely! GitHub has a solution for that; you can use your PR title and description for the commit message when using " squash merging ."

Conclusion

Just as Minnesotans rally in the middle of a storm and put in that extra effort to keep the streets clear, developers can make a final effort in their PR descriptions. After doing the hard work of coding and testing, this last step honors that effort by making the review process smoother. That small investment makes the whole process easier for your peers and future maintainers to navigate.

• John Cavalieri

  Software Engineer

  More from John