Github Pull Request Templates - crccheck/crccheck.github.io GitHub Wiki

Pull request templates need to be:

  1. terse
  2. fast. I use snake_case for prompts because I can double click to replace them

Don't use checklists; checklists become noise that humans ignore, and unchecked items make it look like your PR is a work in progress. Reserve checklists for actual TODO lists and maybe as triggers for automation

My go to PR template

.github/PULL_REQUEST_TEMPLATE.md

SUMMARY_description_of_the_value_of_this_PR_and_implementation_notes

## Risks

paragraph_describing_what_the_negative_impact_could_be

## Verifying the change

testing_instructions__include_screenshots_for_visual_changes

The summary section should have all the context needed to solve the problem should be here. Readers should never have to navigate a JIRA/Trello/Github to learn more. If one exists, copy paste the content here. If your PR needs special steps to deploy, write them down. No heading is needed.

Risks tersely document the potential negative impacts of this PR. This section exists to force people to think about this. Lower risk PRs are easier to review, so encourage less risky PRs. If you're not sure if it goes in Risks or Summary, put it in Summary. For example breaking changes should go into the Summary. TBH you don't need this, but you should always think about it.

Verifying the change should have everything the reviewer needs to do to test your change:

  • curl commands
  • API responses
  • log output
  • screenshots

Cover your own ass (CYOA) things to communicate:

  1. cost/benefit of a feature
    1. document technical debt cost like how a legislative bill's costs are documented in a fiscal note
    2. Example: If you need 10000 lines of code to replicate a browser alert box... maybe this PR should just get closed
  2. design tradeoffs. Like a mini architectural decision record (ADR). Preempt questions about why you chose a particular approach (for example. "I optimized this to be easier to delete later")
  3. design research/prior art. Similar to point 2. It can save a lot of time and words to say "this works just like Technology X"

https://docs.google.com/presentation/d/1B9-IjIEJN50KiRVkLqTuE2ZFb--Z0jKSPMKs9VzOsU0/edit#slide=id.p