search

parse-community / .github

Default community health files for the Parse Community
4 stars 7 forks source link

Default pull request template #6

Open TomWFox opened 3 years ago

TomWFox commented 3 years ago

In terms of a PR temp, maybe something like this would be good:

### New Pull Request Checklist
<!--
    Thanks for contributing to the Parse Platform!

    Please only submit your issue if ALL of the below are true. Check each box [x] to indicate this to our triage team:
    Click the "Preview" tab for better readability.
-->

- [ ] This is not a vulnerability disclosure. If it is, [report here](https://github.com/parse-community/parse-server/blob/master/SECURITY.md).

### Issue Description
<!-- Add a brief description of the issue this PR solves. -->

### Approach
<!-- Add a description of the approach in this PR. -->

### TODOs before merging
<!--
    Add TODOs that need to be completed before merging this PR.
    Delete suggested TODOs that do not apply to this PR.
-->

- [ ] Add changes to documentation (guides, repository pages, in-code descriptions)

Experiences from the parse server repo, after which this template seems to be shaped:

  • Sometimes the checkboxes at the top are misunderstood as "check which ones apply" instead of the intended "all are required, so make sure all are checked". That comment section of the template should therefore be rephrased to male that clear.

  • It still (although much rarer than pre-PR template) happens that PRs are created without corresponding issue. Issues should always be mandatory for a PR, because a low-level solution should be derived from a high level discussion, which should take place in the issue thread, not in the PR thread. This template is lacking that, but I think the server repo template has that as required checkbox.

  • TODOs at the bottom are repo specific and important, to reduce the risk of PRs lacking required chores. It proved to be successful with the server repo. I think at least each of the client sdk repos also should list its specific TODOs at some point, and will therefore require a specific template.

Originally posted by @mtrezza in https://github.com/parse-community/.github/issues/5#issuecomment-846318966

TomWFox commented 3 years ago
  • Sometimes the checkboxes at the top are misunderstood as "check which ones apply" instead of the intended "all are required, so make sure all are checked". That comment section of the template should therefore be rephrased to male that clear.

This is the best I could come up with:

Please only submit your issue if ALL of the below are true. Check each box [x] to indicate this [to our triage team]:
- [ ] This is not a vulnerability disclosure. If it is, [report here](link).

It still (although much rarer than pre-PR template) happens that PRs are created without corresponding issue. Issues should always be mandatory for a PR, because a low-level solution should be derived from a high level discussion, which should take place in the issue thread, not in the PR thread. This template is lacking that, but I think the server repo template has that as required checkbox.

Trying to give me a hint? ;)

I didn't add this checkbox as there are situations across the org where a corresponding issue is not necessary. I also feel that for maintainers that operate differently to Parse Server it doesn't make sense to impose (at least not without further consultation, org wide issue & PR management policies etc).

  • TODOs at the bottom are repo specific and important, to reduce the risk of PRs lacking required chores. It proved to be successful with the server repo. I think at least each of the client sdk repos also should list its specific TODOs at some point, and will therefore require a specific template.

Agreed. Are you suggesting that should affect this suggested default template in any way?

mtrezza commented 3 years ago

Please only submit your issue if ALL of the below are true. Check each box [x] to indicate this [to our triage team]:

  • [ ] This is not a vulnerability disclosure. If it is, report here.

Yep, just would comment the hint with <-- /-->.

I didn't add this checkbox as there are situations across the org where a corresponding issue is not necessary. I also feel that for maintainers that operate differently to Parse Server it doesn't make sense to impose (at least not without further consultation, org wide issue & PR management policies etc).

For all repos we should impose an issue for a PR. The separation of high / low level discussions is part of QA - which we are largely lacking. We can always make an exception if there is a micro PR that fixes a changelog typo for example. However, that rule should be org wide for simplicity, I currently only see the docs repo as being exempt. There have been instances in PRs that I recently reviewed where the PR itself contains the whole issue description, but that's the wrong place if a high level discussion reveals that the PR is the wrong approach. This scatters high level discussions over many threads, which makes reviews and later research a real pain.

Are you suggesting that should affect this suggested default template in any way?

I think that just means the default template will not be visible in certain / many (?) repos, maybe something to keep in mind.

mtrezza commented 3 years ago

Here is yet another example why we need a proper policy that requires a separation of high-level discussions in issues vs. low-level discussions in PR.

And another example, and another one.