Added a new paragraph to the bug and feature issue templates, explaining where to enter comments #12333
Conversation
See test results for failed build of commit 3f9f39ca46 |
|
Chrome TEST i7562 was what failed here, and I have no idea why since this PR doesn't touch anything related. Full Name: |
…s, explaining that comments should appear BENEATH the lines with hashmarks.
… to the current bug template's revision.
XLTechie
force-pushed
the
issueTemplatesAnswerPlacement
branch
from
a046876
to
f6104c6
Compare
|
Should also the colon at the end of the section title be removed? |
|
What would we do with the bug template in that case? Some have colons, some
have question marks.
I personally believe it is the appropriate punctuation, and should stay.
I emailed @britechguy, and he said the problem with that issue would probably
still have happened without the colons.
We could even put an HTML comment on each heading line, saying "answer below",
but in the bug template that would make for some long lines.
It is maybe overkill.
|
|
I was thinking to remove colons but keep question marks. I also vote against the comment at the end of the line. It makes things to heavy when editing. We should also keep in mind that the vast majority of bug templates are filled correctly, even by people that did not know markdown before (myself included). |
|
If filling these templates is such a problem, we really should consider switching to Github Issue Forms at some point. |
|
Looks good, but random question: I've never heard the term "hashmarks". I've always seen them referred to as "the hash symbol" or simply "hash". Personally, I would reword the first part of each change from: (The change to the COM registration fixing tool is fine as is). |
|
@LeonarddeR I would love to do something like that. It's on my short term radar,
but it will take some time and development effort, and then some convincing I
suspect.
For now, I'm trying to make the existing system the best it can be, for however
long we have it.
As to "Github forms issues", what exactly do you mean?
Are you talking about using integrations with Google forms, Zapier, etc.? Or is
there another feature of Github that isn't coming up in normal searches?
Because I've been looking for something like that for several days, trying to
avoid having to roll my own, and found nothing that was Github native.
|
|
See
https://github.com/home-assistant/core/issues/new?assignees=&labels=&template=bug_report.yml
I'm not sure @feerenrut was yet convinced about the benefits.
|
|
Looks good, but random question: I've never heard the term "hashmarks". I've always seen them referred to as "the hash symbol" or simply "hash".
Over here we call them pound signs or number signs, among other things. I was
relying on the Wikipedia article's statement that hashmarks was more commonly
the term in Europe and some other places. But I don't know how reliable that is,
or particularly care what word is used as long as the meaning is clear.
Language updated as you recommend.
|
|
Oh, I see. That has a lot of potential.
Unfortunately, in order to build a demonstration model of what we could do with it, I would need access to the private alpha. I don’t have any personal or organizational projects big enough to get me access to the private alpha.
That aside: because it’s an alpha, meaning a lot of it can change in implementation among other things as time goes on, we may have to wait for it to ripen before it can really be useful.
But I will definitely be watching what happens here, because this seems to me like the direction NVDA should go in, if it can do all of the right things for the various types of user.
Thanks for the reference.
|
|
One other thing to make this more clear might be to include a complete raw markdown example on the wiki: |
Link to issue number:
In response to incidental discussion in #11847
Summary of the issue:
At various times, we've seen issue templates filled out in garbled ways, that make it difficult to navigate or work with the issue description.
In the above issue, for example, the initial description--by a sighted user--had the issue's answers and comments entered directly after the colons on the question lines.
This caused all answers to be headers, along with the questions provoking them, which lead to the issue being hard to navigate other than by simply arrowing through it.
In this case the author is a very experienced technical user, but because he did not know Markdown, and had no idea that he should know Markdown, he answered in the way that seemed most logical.
I've also observed worse examples, where the issue details are written after all the section/question headings, and so on.
Description of how this pull request fixes the issue:
This issue can't be fixed while still using a text based template for issues.
However, it may be possible to mitigate it, by including very basic instructions about where answers should be placed in the template.
This PR adds the following comment, after a blank line to make it stand out, at the bottom of the top HTML issue comment for the bug and feature templates:
This language was the best of a few variations I came up with, but I'm sure it could be improved upon. Still, I think it's better than nothing.
We can't make people read the comment paragraphs, but at least providing the definite instruction will reach those who do.
Edit: Subsequently, I added this to the default issue template as well. And while it's unrelated, I added the revised COM Reg. Fix tool question from #12276 to the default template since I was there. If this isn't approved, I'll do a separate PR for that.
Testing strategy:
N/A
Known issues with pull request:
The term I used, "hashmark", is both shorter than "number sign", and I think somewhat more global. Whether it needs a space, or whether one of the other terms would be better, is debatable, and I'm fine with anything that improves clarity.
This Wikipedia article section has a list of terms, and Wikipedia's idea of how popular they are.
Change log entries:
None needed.
Code Review Checklist:
No code changed.