[RFC] Update PR template to use a checklist
ds300 opened this issue · comments
What
Change the PR template to do the following things
- Include instructions explaining how the Jira integration works
- Replace the 'optional' sections with a non-optional checklist.
The type of this PR is: **TYPE**
<!-- Bugfix/Feature/Enhancement/Documentation -->
<!-- If applicable, write the Jira ticket number in square brackets e.g. `[MX-434]`
The Jira integration will turn it into a clickable link for you. -->
This PR resolves [MX-]
### Description
<!-- Implementation description -->
### PR Checklist (tick all before merging)
<!-- 💡 This checklist is experimental. MX warmly welcomes any feedback about the list or how it impacts your workflow -->
- [ ] I have included screenshots or videos to illustrate my changes, or I have not changed anything that impacts the UI.
- [ ] I have added tests for my changes, or my changes don't require testing, or I have included a link to a separate Jira ticket covering the tests.
- [ ] I have documented any follow-up work that this PR will require, or it does not require any.
- [ ] I have added an app state migration, or my changes do not require one. ([What are migrations?](https://github.com/artsy/eigen/blob/master/docs/adding_state_migrations.md))
And, at the same time, we should remove the danger rule about new test files.
Why
In #3498 we're adding app state persistence and migration infrastructure. People who contribute to the app from now on will need to be alert to the fact that code changes can potentially cause data loss for users, and how to avoid that outcome.
I wanted to add a note in the PR template to remind people about this danger and point them to the relevant docs. Alas, it wasn't clear to me where to put the note in the current PR template. I also noticed that folks have been deleting parts of the PR template they don't need/want to fill out. This made me concerned that they might one day delete the note without thinking about it, as a result of habit.
I vaguely remembered contributing to github projects which used a 'checklist'-style template where all items are designed to be checked before submitting the PR, and I'm proposing that we adopt that approach here. The checklist items are worded in the first-person to give the PR author a sense of ownership and accountability.
I also think that this will be a good way to get people to be more thorough with testing (I am definitely one of these people), since the current danger rule only prompts people to add tests for new files, missing new functionality in existing files.
Another benefit of the list is that it's more easily extensible if we identify other things that, given a moment's thought, could prevent problems later on.
How
Merge #3498
Looks good to me! Having the state migration as an item in the PR checklist can definitely save us in the future
I love the comment about feedback 🤩
I think the tests one is kinda done for us by peril, right? well not for changes I guess, but then tests might fail?
also I liked the screenshots dedicated place, but I guess that list item makes it more generic here.
and I have to take a look at the migration thing, I'm not familiar with it yet. is it something temporary until everything is moved to easypeasy?
I don't wanna have too many questions. let's update it like you suggest and I'm sure we'll tweak it more as we use it more.
I think the tests one is kinda done for us by peril, right? well not for changes I guess, but then tests might fail?
The danger rule only enforces tests for new files, and even then it is quite easy for people to ignore. And tests only fail if we have good coverage in the first place 🙈
I don't want this checklist item to stop people from moving fast when they need to, but at the same time I think it would be good to move in a direction that gives all contributors an increased sense of shared ownership and responsibility for app quality.
and I have to take a look at the migration thing, I'm not familiar with it yet. is it something temporary until everything is moved to easypeasy?
It's permanent. The docs are in #3498 if you're interested in checking them out already, adding_state_migrations.md
Sounds great!
we should remove the danger rule about new test files
Yeah, I agree it's time. In theory it works but in practice it just introduces a lot of noise.
Would it be interesting to add another checkbox for like "I added a QA item" if there is a need for it?
You mean an item on the QA script? I really like that idea.
Resolution
We decided to do it.
Level of Support
2: Positive feedback.
Additional Context
We should keep an eye on how this affects our workflow. it's a pretty significant change.
Next Steps
I'll update #3498 's description to make it ready for a final review
Yup, that's exactly what I mean. :)