Pull requests (PRs for short) are useful as a way to document changes. This provides two benefits:

• It provides evidence that this change is indeed useful.

• At a later point in the future, a PR can show up as the result of a git blame. The PR can then retroactively provide context and explain why things are the way they are.

A good PR has the following information:

• Title: a short, one-line summary

• What is contained in this change?: Describe, in as much detail as useful, what this change does. If the change is visual, consider including screenshots. If the change is visual and interactive, consider including a video.

• References: Add links to anything that is relevant for this change, suck as tickets, mockups, and design documents.

• Checklist:

  • Either:
    • I have updated the tests
    • This change does not need tests
    • I promise to write the tests soon
  • Either:
    • I have updated documentation
    • This change does not need documentation
    • I promise to write the documentation soon
  • This change can be safely rolled back
  • This change is safe to deploy (to production) by itself

Specific things to call out:

• If resolving a ticket, copy the description of the ticket too. Don’t just link to the ticket, so that if the ticketing system or project management system is later replaced,¹¹1 A former employ forgot to pay the bill for their project management system, and all information in it was irrevocably lost. Because the PRs only had ticket IDs rather than descriptions, the PRs had no useful information anymore, either.  no context gets lost.