github: add a Pull Request template#370
Conversation
- 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
- 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
- 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
|
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. 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 😅 |
Summary
Add a brief PR template for contributors to write against
Details
keeping it short and simple for now, but this is basically the format that the majority of my PRs follow
this should help keep PRs consistent, which makes them easier to read and review
should also help preserve the historical context and rationale behind PRs
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.