Bug report template: various tweaks

[jrfnl]

Description

• Improve readability of reports by using headers.
• Improve readability of the versions list by using a table.
• Explicitly say that screenshots of code are not acceptable as a code sample.
• Added an "Install type" entry to the versions list
• Added an extra checklist for bug reporters in an attempt to reduce the number of issues which should never have been opened in the first place.

Suggested changelog entry

N/A

Related issues/external references

N/A

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [ ] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)
  • [ ] This change is only breaking for integrators, not for external standards or end-users.
• [ ] Documentation improvement

[gsherwood]

Github's preview of the file isn't rendering that table at all. I'm not sure if there is a syntax error there.

[jrfnl]

Github's preview of the file isn't rendering that table at all. I'm not sure if there is a syntax error there.

Thanks for catching that. That must be an issue with the GitHub flavoured markdown being less tolerant of table formats, but it should be good now.

[gsherwood]

Thanks. I've merged it in.

When trying out the new template the table layout in text has been messed up for me, which makes it hard to complete the report. I think it's probably just the font but switching it to a simple list might be more compatible.

This is what I see with default settings:

[jrfnl]

When trying out the new template the table layout in text has been messed up for me, which makes it hard to complete the report. I think it's probably just the font but switching it to a simple list might be more compatible.

@gsherwood That's the downside of the change I made to get the table working without header. The alternative would be to bring the table back to the original format (which should display less messily), but add table headers. Just means we'd have to think of what the headers should be....

[fredden]

Might something like this work? https://github.com/fredden/yaml-issue-template-test/issues/new?template=bug_report.yaml https://github.com/fredden/yaml-issue-template-test/blob/main/.github/ISSUE_TEMPLATE/bug_report.yaml You're welcome to experiment with that repository; I'll delete it after the discussion here has concluded.

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

[jrfnl]

@fredden I'm not really a fan of the YAML templates as I've found them to be too restrictive/limiting in most cases.

With the markdown templates, people can easily add an extra section or two or a detail fold-out with log information etc. With the YAML templates they can't and they'd have to add that information in follow-up comments, which doesn't necessarily make it clearer what the extra information belongs with.

[fredden]

Yes, I've found it difficult to put correct details in YAML style templates too. I hoped that the 'additional context' box at the bottom would suffice for this.

I was expecting to find some syntax to create a form similar to the 'affected products' section of the security vulnerability report, but didn't find this style described in the documentation.

Screen-shot of vulnerability report form


---

Back to / sticking with the markdown template:

Markdown doesn't need a lot of white-space around the table syntax. I wonder if removing that would increase the usability. Making the text line up in a mono-space font is nice, but the input box in GitHub for issues doesn't use a mono-space font by default.

eg, this table renders just fine:

| | |
| --- | --- |
| Operating System | Debian 11
| PHP version | 8.2
| Standard | PSR12

Operating System	Debian 11
PHP version	8.2
Standard	PSR12

[jrfnl]

That's weird as that is the table format I had originally when I first pulled this PR... 🤷🏻‍♀️

[fredden]

I think it needs the trailing pipe on the first row to work properly.

| |
| --- | ---
| Operating System | Debian 11
| PHP version | 8.2
| Standard | PSR12

Operating System	Debian 11
PHP version	8.2
Standard	PSR12

| | |
| --- | ---
| Operating System | Debian 11
| PHP version | 8.2
| Standard | PSR12

Operating System	Debian 11
PHP version	8.2
Standard	PSR12

[jrfnl]

@fredden That sounds like gfm (GitHub flavoured Markdown) weirdness to me as that shouldn't be needed based on the Markdown specs IIRC, but thank you for figuring it out. Nice find!

Do you want to send in a follow up PR to fix up that table format ?