Pull request descriptions

2023-08-16 #git #documentation

I used to leave pull request descriptions empty. "Let the code speak for itself" or "let the commits speak for themselves" are the perfect getaway from the extra work of documenting your thought process.

Recently, I've experienced that spending time on a good description is a worthwhile investment.

Notes to self

If you're working on a feature that takes a few days to complete, open a draft pull request as soon as possible. Keep the description up to date as you move forward.

When the rabbit hole of your fix or feature turns out to be deeper than expected, you'll have left a bunch of breadcrumbs behind you to trace back your steps instead of running in circles.

Besides describing what you've done, document next steps too. If a more pressing bug or features comes up and you need to leave the PR alone for a few days (or months), it'll be easier to get back in it with an actionable to-do list.

Happy reviewers

Reviewers are happy to have a summary for a high-level overview. Odds are the description might also answer some questions that would come up in the review ("why didn't you do it this (other) way?"). Less back-and-forth communication speeds up the review process.

During the review, keep the description up to date. Don't only rely on comments. Future readers shouldn't need to dig through a thread to get the gist of the decisions made.

Some extra context for the next developer (or future you)

Not all documentation has to be prose. Commits are documentation. Issues are documentation. Support articles are documentation. Pull requests are documentation. No need to put all your eggs in one basket. Pull request descriptions aren't a replacement for a structured document, but they're a welcome extra.

There's a 90% chance no one will read your debrief after the code is merged. But in the off-chance someone does, they'll be grateful it's there.

And while reading through git history tells you how the feature was implemented, it doesn't provide any context on how it wasn't implemented.

The actionable part: how to get started

At the end of the day, make sure:

Start doing this for pull requests that live longer than a day, that's where descriptions are most valuable. Before you know you've built a new habit.