New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update issue templates #9000

Merged
merged 4 commits into from Dec 5, 2018

Conversation

Projects
None yet
6 participants
@feerrenrut
Contributor

feerrenrut commented Dec 2, 2018

Closes #8494
Update github issue templates so that feature requests can be provided.

This keeps the bug report issue template the same, and creates a feature request issue template. I am using the suggested headings given by Github. Once we are happy with this PR I suggest that we create a new wiki page to explain the feature request template (and change the existing ones title). The new wiki page could include the following text:

New Feature request template

This page is meant to serve as an explanation for how to fill out our feature request Github issue template.

The template uses github markdown, to provide formatting for headings, lists, quotes etc. If you are not familiar, please take some time to learn about Github markdown

Warning: In all but exceptional circumstances we require this template to be completed. Your issue will likely be closed if this template has not been followed. However, please feel free to add more headings if you feel it provides more clarity into your request.

Tips

  • Consider swapping to the preview tab in order to read through your issue at any stage to confirm the issue reads as expected.
  • If you have trouble following this template, or with the initial investigation that is required, please politely ask for assistance from the fantastic community of people on the NVDA users mailing list

The template

The following headings match those that are found in the template, with a short description of how to fill in each section.

Is your feature request related to a problem? Please describe.

This section should provide a clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like

A clear and concise description of what you want to happen. If you can provide technical details about how to address the problem, please do so. Feel free to add a subheading.

Describe alternatives you've considered

A clear and concise description of any alternative solutions or features you've considered.

Additional context

Add any other context for the feature request here. This might be the other applications and their versions that the feature is expected to work with (EG Firefox or Microsoft Word). Also consider whether you can upload an attachment document that will help to serve as a test case for the feature.

Update issue templates
Update github issue templates so that feature requests can be provided.
@nvdaes

This comment has been minimized.

Contributor

nvdaes commented Dec 2, 2018

Thanks for addressing this. For me you can merge this like that, or may remove the context section for simplicity (this can be explained just in previous sections or ommited).

@DrSooom

This comment has been minimized.

DrSooom commented Dec 2, 2018

Is your feature request related to a problem? Please describe.

This is quite similar to STR and the actual behaviour. If there is an existing problem, the issue template would be the right place for it – in most cases.

Describe the solution you'd like

And this one is similar to expected behaviour. So I would rename both to them.

Additional context

This isn't really clear. Maybe the wiki article will help here out.

And please replace the bold markdown code with headlines level 3. Then it would be similar to the issue template. Thanks.

@feerrenrut

This comment has been minimized.

Contributor

feerrenrut commented Dec 3, 2018

This is quite similar to STR and the actual behaviour. If there is an existing problem, the issue template would be the right place for it – in most cases.

Perhaps this is an issue with the wording, but the key difference is "a problem with existing functionality of NVDA" vs "a problem I am unable to solve while using NVDA". This language is trying to get the user to define their problem statement / use case for the feature.

I think for the most part, a feature request can use simpler language, and does not require so much precision in the initial report. This can come later as the idea is explored in the comments. This is in contrast with a bug report where it can often become harder to get more details about the original issue as time goes on, so the initial report should be as precise and detailed as possible.

feerrenrut added some commits Dec 3, 2018

Update feature_request.md
Replace bold with level 3 heading.
Delete issue_template.md
This file will not be needed with the new feature / bug report templates.
@leonardder

This comment has been minimized.

Collaborator

leonardder commented Dec 3, 2018

It might be good to have additional headings in the feature request template for that urges one to provide possible technical details or known limitations in the suggested approach.

@feerrenrut

This comment has been minimized.

Contributor

feerrenrut commented Dec 3, 2018

It might be good to have additional headings in the feature request template for that urges one to provide possible technical details or known limitations in the suggested approach.

I'll certainly add this to the wiki page, it's always ok to add more details. I'd prefer feature requests first focus on the problem to be solved, rather then jumping straight to the solution. There may be several ways to approach it, or similar problems that could be addressed with a more general solution. Getting deep on the solution can close peoples minds to alternative approaches.

@DrSooom

This comment has been minimized.

DrSooom commented Dec 3, 2018

@feerrenrut: Could you please correct the following typo ("installed" instead of "Installed") in the template and in the wiki article too?

NVDA Installed/portable/running from source:

And deleting the blank lines between the 3rd and 4th level headlines in the bug template might be helpful too – as they aren't necessary here. Thanks.

Ah, and one more suggestion to the wiki article in the section "Other information about your system:". Maybe it would be helpful in some circumstances to add the current synthesizer and the current braille display in the example quotation.

Update bug_report.md
Small formatting changes.

@feerrenrut feerrenrut requested a review from michaelDCurran Dec 4, 2018

@feerrenrut

This comment has been minimized.

Contributor

feerrenrut commented Dec 4, 2018

There will be quite a bit of duplicated information if there is one wiki page for each template. Instead, I will put the information on one page with links to each template explanation at the start.

@feerrenrut feerrenrut merged commit ddab676 into master Dec 5, 2018

1 check passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details

@nvaccessAuto nvaccessAuto added this to the 2018.4 milestone Dec 5, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment