github: add a Pull Request template

[agilgur5]

Summary

Add a brief PR template for contributors to write against

• Follow-up to "Next Steps" from github: add troubleshooting steps to the issue template #350
• See GitHub's docs on PR templates here

Details

• keeping it short and simple for now, but this is basically the format that the majority of my PRs follow

  • can add more sections or optional sections as needed in the future
    • (e.g. I've used "References", "Next Steps", etc in this codebase)

• this should help keep PRs consistent, which makes them easier to read and review

  • (similar rationale as that for code style consistency)

• should also help preserve the historical context and rationale behind PRs

  • which also makes reviews significantly easier and involve less guesswork
  • which can be very important for figuring out the intent of code
    • which can be particularly important when trying to decipher if a piece of code was written intentionally for a specific purpose, or accidentally has a bug in it, or is redundant, etc
      • which I've had to do many a time in this codebase and many others, and reading issues and PRs is how I gained most of my historical context from which I can identify patterns, fix issues, close duplicates, etc
    • while comments serve a similar function, not all code is commented and the overall purpose of a PR may not necessarily fit into any line of the code
      • or it may only be relevant historically, and not necessarily relevant to a piece of code's current functionality
    • etc etc etc etc

• also requests a small bar of quality from PR authors as well

Hopefully I'm barking up the same tree here, but I've had to teach many, many, many, many people and teams the usefulness and purpose of the best practice of high quality change history, which only becomes apparent over time in the long-term.
Corporate PR templates that I make tend to be much more detailed, especially when dealing with large, production codebases, so this is just a tiny sample, but this should hopefully provide a very basic framework for contributors.

[ezolenko]

I shudder just thinking what your corporate PRs look like, but yeah :D

[agilgur5]

I shudder just thinking what your corporate PRs look like, but yeah :D

Legit laughed out loud reading this hahaha 😆 .

It depends on the codebase, complexity, teams involved, etc. The more complicated ones with more teams involved as contributors (e.g. "innersource" projects) are very roughly ~4 required sections and 4+ optional sections.
(mainly bc complex infra projects can have many moving pieces that need addressing and are hard to test well, and the more outside contributors, the more need for consistency and guardrails -- honor code also doesn't go as far. not to mention compliance concerns -- detailed issues/PRs are very helpful during audits).
Less complicated ones with only 1 team are roughly similar to this, maybe a bit more detailed. Like 2x this really tiny one maybe.
For what it's worth, my corporate templates are actually based on my OSS experience! (and not the other way around)

And I try to split most of my PRs into small, independent chunks (as you probably noticed), so that helps keep things quick (still have to teach others to do the same though).

My JIRA (or w/e task manager the company is using) can get as heavily detailed as all my RCAs here though 😅
Though I wanna say OSS RCAs tend to actually be longer as there's more history and dependencies than corporate code.
(or, well, sometimes corporate code has years of legacy history too ...but often there's no documentation or issues what-so-ever to even be able to investigate through... 😐 ... becomes much more guesswork at that point...).