Create a new pull request template

[grenewode]

Why

Resolves #518

We want to ensure that all pull request made to this repository follow a uniform pattern. This will make it easier to review new pull requests. It will also help to promote cultural norms around testing and security/accessibility mindfulness.

Pre-Merge Checklist

All these boxes should be checked off before any pull request is merged!

• All new features have been described in the pull request
• Security & accessibility have been considered
• All outstanding questions and concerns have been resolved
• Any next steps that seem like a good ideas have been created as issues for future discussion & implementation
• High quality tests have been added, or an explanation has been given why the features cannot be tested
• New features have been documented, and the code is understandable and well commented

What

• Adds a pull request template (you're looking at an example of a pull-request follow this template right now!)
  • Major sections such as Why, What, How
  • Questions section
  • Future work section
  • Final pre-launch checklist
  • Best-practices sections for security, accessibility and testing
  • Meta section for developer-experience comments

How

A github pull request template is a simple markdown document, placed in the special .github/PULL_REQUEST_TEMPLATE directory. Github will use files in these folders to give users the option to use the template when creating new pull requests.

You can find more information in github's documentation. This template was also inspired by the casa project's pull request template

Testing

Again, there's nothing really to test for this issue - but hopefully having this section will encourage more testing in the future!

Outstanding Questions, Concerns and Other Notes

• This template is rather long - do we want something shorter?

Next Steps

We should create issue templates as well!
Once issues templates have been created, we should make sure that we are using automation urls as appropriate throughout the project.

Accessibility

This changes does not have any accessibility implications by itself. However, by encouraging developers to think about these issues as they propose changes, we can hopefully improve the quality of the accessibility & security of the app in the future.

Security

Likewise, this change does not have any security implications by itself.

Meta

I'm exited to see these templates being used!

[svileshina]

Few thoughts - we could add something to encourage people to use their discretion as to how much of the PR template to use vs which sections to delete. Not all PRs will require all (or almost any) sections to be filled out. That said - we can also add something to stress that the "why" is preferred for most PRs. There will (hopefully) be a lot of PRs and not everyone reviewing can be expected to have all the context for every PR.

[solebared]

This is great! 🙌🏾
A few comments/thoughts and i also second @svileshina's suggestion.

This is the kind of thing we'll have to try out for a while and tweak.

[h-m-m]

Thanks for doing this, @grenewode. I've had templates like this in other projects, and I feel like having one is a good fit here.

I like the idea of making ensuring or encouraging every PR has "why", "what", and "how" answered. I usually find it easier to focus on more helpful writing for the team if we use different wording as the prompts. For example, I like "Summary (why)" (or "Description" or "Overview") as a reminder to keep that initial "why" section short like the lead paragraph in a newspaper article. And then maybe a "Changes (what)" section that then goes into more details?

Also, for sections we want to be more optional than others, GitHub will respect HTML comment syntax as commented out. We can also use these comments to include guidelines or suggestions for formatting. For example, we could keep "How" has a section header, and then add a commented out block that says something like

<!--
This section can include an overview or notes about implementation
details or design choices. These comments should help explain how 
this change  implements the goals or reasons outlined in the first section.

It's okay to summarize, or to skip this section if you feel the changes 
themselves include enough of an explanation
-->

And this lets us incorporate @svileshina suggestion of letting some sections be optional. I'm not happy with this exact wording, so suggestions / recommendations welcome

[h-m-m]

I started writing my comment at some point before @exbinary posted anything and the page didn't update. If my comments seem out of sync compared to comments he's already made, that's why

[maebeale]

may we add a "Resolves #" section to top?

[grenewode]

I made some changes, with a note about using github's keywords for this

[grenewode]

I just pushed some changes to make things a little nicer.

1. Sections have been reordered & grouped so that there doesn't feel like there are quite so many
2. Several sections at the end have been marked as optional, as many pull requests won't need them
3. The premerge checklist has been moved further up. I'm not sure if this is the best place for it, but I kinda want it to be one of the first things people see when they look at a pull request

[solebared]

LGTM! Appreciate you reworking it, i like this version.

[solebared]

Not sure why, but the template doesn't seem to be presented on new PRs 😕.