Improve consistency of issue and PR templates

[SaschaCowley]

Detailed description of the issue

The NVDA project has a number of issue and pull request templates, for bug reports, feature requests, special issues, merge requests, and revert requests. These templates contain a number of inconsistencies and annoyances:

• The headings in these templates are level 3 headings (### ...), even though comment headings (except for the heading for issue descriptions) are at level 3 on GitHub. This means that (1) the logical structure of the document is not preserved; and (2) consequently, it is not possible to skip the contents of the initial comment easily by navigating by level 3 heading (3 in browse mode).
  • I do not know if GitHub intends to update the PR experience in line with the new issue experience.
  • Nevertheless, this highlights that adjusting our heading levels around GitHub's interface is dangerous, as this could change at any time. Ideally, GitHub would automatically adjust all headings in comments so that they are consistent with the page's structure, though of course this has its own issues.
• Some of the questions/prompts in these templates end with a colon (":"), some with a question mark ("?"), some with a full stop (".") and some with no punctuation. This makes it less obvious exactly where users should add responses.

Why are the other templates not appropriate in this case?

This issue is not about NVDA itself, but about the issue and pull request templates in its GitHub repository.

Have you asked for advice on how to report this issue via a community discussion? If so, please link to the discussion

No.

Steps to reproduce or illustrate the issue (if applicable)

Create a pull request or issue on NVDA's repository.

Expected outcome or behaviour (if applicable)

• The highest heading level in these templates should be level 4, so that these questions are logically contained by their comment.
• Questions should end with a question mark ("?"), and prompts with a colon (":"). Grouping headings should not end with any punctuation (except for close brackets, quotation marks etc.)

Screenshots, logs, and other attachments (if applicable)

N/A

System configuration or software environment (if applicable)

N/A

Additional information (if applicable)

N/A

[juanchax]

hey team! I'm new to contributing to this project, but I wanted to let you know that I've put together a couple of Issue Form Templates (Bug report & Feature Request), based off of this repo's current templates.

I've attached sample screenshots (below) of the forms for a quick view, you can demo the templates here. Feel free to test them out, file issues, etc. They are hosted in a public repo I created solelly for the purpose of this contribution.

I'd be more than happy to take ownership of this request, polish the form templates I've already created + create new Form Templates for the special issues, merge requests, and revert requests categories.

Feel free to ping me with any questions/suggestions!

[seanbudd]

Hi @juanchax - it looks like you've decided to use GitHub's issue form system rather than follow the issue outlined here.

We have a separate issue / PR for this: #15320

Note that this work is blocked as the new GitHub issue form design has several accessibility issues.

[juanchax]

hey @seanbudd , apologies for the mixup, and I appreciate the time taken to review this comment.
I used github's recommended "great first issues", and by the looks of it, I shouldn't have.
I will be more careful in the future.

[seanbudd]

@juanchax the good first issues is a good place to start, but I would encourage following what the issue actually requests. If you want to do something different, please open a new issue or check in first before doing a bunch of work.

[CyrilleB79]

@SaschaCowley given GitHub has recently introduced a new page layout for issue list and issues, I'd say that the request to change heading levels do not apply anymore for issue templates. Do you agree?

I wonder if they plan to perform similar changes in the future for PRs.

[SaschaCowley]

@CyrilleB79

given GitHub has recently introduced a new page layout for issue list and issues, I'd say that the request to change heading levels do not apply anymore for issue templates. Do you agree?

Yes, I agree.