/
PR documentation guidelines

PR documentation guidelines

Owned by Zak Burke
Last updated: Apr 22, 2025Version comment
2 min read

  • PR subjects should begin with the Jira ticket this code references, e.g. UIFOO-123. This makes it easy to find when grep’ing through git log output or browsing through commit history on GitHub or writing scripts that connect GitHub PRs and Jira tickets.

  • PR subjects should describe the state of things once the code is merged. For feature-tickets, describe the feature. For bug-fix tickets, describe the solution, not the (now-resolved) problem.

    • “Fix bug with validation” is not helpful because it lacks context; it amounts to “made some changes”. Right after you discuss this bug at standup, of course you know what this comment means, but when you’re looking at this code year a year from now and trying to remember, “Why did we write it this way?” it doesn’t offer much help. Be specific if possible, e.g. “Relax acceptable characters when validating user barcodes”.

    • “User gets error when clicking button” is not helpful because it does not describe the current state of the codebase; once this commit is merged, that problem will be gone. A commit subject should describe what the code does now, not what it previously did. Try “Catch and report errors in save-button’s click-handler”.

  • PR descriptions should be self-contained and fully describe the code change. It’s polite to link to the relevant Jira, but note that this is not sufficient either; you must describe the work contained in the PR.

    • If you are implementing a feature, summarize the work in a sentence or two.

    • If you are fixing a bug, describe how the old code caused the buggy behavior, and describe how and why the new code resolves it. Don’t simply restate your code change in words; we can see what changed with git diff. The reviewer should not have to re-triage the bug to figure out what caused it, and should not have to reverse-engineer your change to see how it resolves the bug.

  • Consider adding a screenshot, before and after screenshots, or even a short movie that demonstrates the change. Sometimes, a picture is worth a thousand words.

  • When a PR template is present, fill out the required parts and remove the optional/irrelevant parts. A half-filled or unfilled template gives the impression of unfinished work-in-progress.

Here are some model PRs: