Trial issue and PR templates to see what works best for us

GuySartorelli commented 1 year ago

Issue templates

We get quite a few issues that don't say what version of the module or of CMS is affected, don't provide a clear description, and don't include reproduction steps.

This is less of an issue on the framework repo, which does have a template. So we know issue templates do alleviate this problem. But we want to also experiment with a more prescriptive template that requires some information to be included, and see how they compare in effectiveness.

PR templates

We get quite a few PRs that don't clearly explain what they intend to do, and/or don't link back to an issue.

Even the framework repo, which does have a template for PRs, has this problem. We should replace the framework template with one that more clearly outlines the required information - minimally with a description and a link to an issue (and a note to create a new issue if one doesn't yet exist).

Looking at the docs, there isn't currently a way to have prescriptive PR templates with required fields.

Acceptance Criteria

[x] The issue template on the framework repo is evaluated, and if clear improvements to wording or structure are identified, those improvements are made
[x] Prescriptive form fields are considered. If a prescriptive form is adopted, these sub-ACs will apply:
- [x] Members of the CMS Squad and core committers must be able to remove required fields from individual issues, as we sometimes need to create issues that have cross-cutting concerns
- [x] "Affected Version(s)" is required - the template makes this clear that we expect the specific module version to be reported (as opposed to the Recipe-CMS version) and provided guidance on how to retrieve that information.
- [x] A "Description" is required
- [x] A "Type" is required, which is either a bug or an enhancement (OR alternatively have two templates - one for bug reports and one for feature suggestions)
- [x] "Steps to Reproduce" is required if the type is bug
[x] All issue templates encourage the reporter to create a pull request to fix their own bug or implement the feature themselves.
[x] The framework pull request template is changed to have clear headings and a explanation of what is required for each heading section
- [x] A "Description" heading is added, and the explanation encourages people to briefly explain what problem their PR solves
- [x] A "Testing Steps" or similar heading is added
- [x] A "Issue" or similar heading is added, and the explanation makes it clear that they should either link to an existing issue, or create a new issue to link to if one doesn't already exist
- [x] Consider adding the PR merge checklist to the template, but only if we agree that we will tick the boxes during peer review
[x] The team agrees about the templates before they are rolled to every repo.

Notes

See Configuring issue templates for your repository for information about creating issue templates
- The one currently on framework uses the legacy workflow
See Creating a pull request template for your repository for information about creating PR templates
The templates used by symfony might be a really good starting point

TO REVIEW

Note that everything is up for grabs - the PR merge checklist is included to see what it would be like - but if we don't all agree to actually use it, we shouldn't include it.

https://github.com/GuySartorelli/issue-template-playground
[x] bug report issue template
[x] feature request issue template
[x] links when creating a new issue (for directing people who need support or want to report a security vulnerability)
[x] pull request template

PRs

https://github.com/silverstripe/module-standardiser/pull/28

NOTE: These should be adding identical templates, except for the docs repos which are different

n8-dev commented 1 year ago

Informational update.

There is now a way to have a somewhat

prescriptive PR templates with required fields.

As in using the Form syntax and multiple templates feature of github, thus people are prompted to fill in the associated details https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates

Form syntax: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms

You can also add links on the create page that can offer comments like where to asking questions, where to review security policy etc which definitely help improve the developer experience and help new people into contributing

Here's some real world examples. Live Examples: https://github.com/carloscuesta/gitmoji/issues/new/choose https://github.com/wagtail/wagtail/issues/new/choose (Note: the please go here for questions links, and report vulnerability process) https://github.com/actions/toolkit/issues/new/choose

I especially markdown around form inputs. (see the second input field below as an example)

Example image:

emteknetnz commented 9 months ago

https://github.com/GuySartorelli/issue-template-playground seems good

sabina-talipova commented 9 months ago

All looks good to me, but there are couple small questions:

Could we provide small example here, like e.g 5.1.0 or 5.0 or 5.
If we will have a wiki page, could we provide a small template of "Steps to reproduce" there. I would personally prefer "cucumber" style, but probably there is another best way.

GuySartorelli commented 9 months ago

Could we provide small example here, like e.g 5.1.0 or 5.0 or 5.

Is the x.y.z in the placeholder enough? Or would you rather change that placeholder to "e.g. 5.1.0"? Note that 5.1 and 5 wouldn't really be as useful as exact patch numbers (e.g. 5.1.3) so I don't want to provide those as suggested values.

If we will have a wiki page, could we provide a small template of "Steps to reproduce" there. I would personally prefer "cucumber" style, but probably there is another best way.

Since we have a whole docs site I don't think it would make sense to also have a GitHub wiki. Especially since (afaik) those are per repository, so we'd need to add an identical wiki on each repository which gets a bit messy.

We could certainly add an example to the documentation, and link to that page from the template. Though frankly at this point any reproduction steps would be better than what we currently get :p

maxime-rainville commented 9 months ago

This is bloody awesome!!!

I love the extra link to submit security issues and to go the community resource.

On the bug template, do we want to include a link to Elvis on the "Check that there isn't already an issue that reports the same bug" checkbox?

GuySartorelli commented 9 months ago

On the bug template, do we want to include a link to Elvis on the "Check that there isn't already an issue that reports the same bug" checkbox?

We can do - but I'd rather wait until elvis has a proper domain (see https://github.com/silverstripe/github-issue-search-client/issues/121). I don't like the links we have to it in the docs as is because of this problem.

emteknetnz commented 9 months ago

Have merged all PRs except fluent

GuySartorelli commented 9 months ago

Fluent got merged

silverstripe / .github