Skip to contentSkip to conversation

Gitlab: Add issue templates

PATCH Superseded John Snow 2 participants 9 messages May 21, 2021 – Jun 3, 2021

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

John Snow

author
#0 lore raw

v2 cover Gitlab: Add issue templates

Add "Bug" and "Feature Request" templates to the Gitlab interface to help improve the quality of newly reported issues.

To see what this looks like, I've temporarily allowed my Gitlab fork to diverge with these files merged. See my fork's "new issue" page to see it in action: https://gitlab.com/jsnow/qemu/-/issues/new?issue

These patches do not add a "default" template, the user still has to select one from the list. I recommend that someone with permissions updates the default template:

1. https://gitlab.com/qemu-project/qemu/edit
2. ctrl+f "Default description template for issues"
3. Update the default to the (suggested) below:

```
<!-- Select "Type: Issue" and choose one of the Description templates above. -->
```

We can use this cover letter to discuss/review the wording on that default template which exists outside of repository data.

--js

V2:
- Updated both templates based on feedback from Peter, Daniel, and Thomas.

John Snow (2):
GitLab: Add "Bug" issue reporting template
GitLab: Add "Feature Request" issue template.

 .gitlab/issue_templates/bug.md             | 61 ++++++++++++++++++++++
 .gitlab/issue_templates/feature_request.md | 32 ++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 .gitlab/issue_templates/bug.md
 create mode 100644 .gitlab/issue_templates/feature_request.md
Signature · 1 line
2.30.2
author
#1 lore raw

PATCH v2 1/2 GitLab: Add "Bug" issue reporting template

Based loosely on libvirt's template, written by Peter Krempa.

CC Peter Krempa <[email protected]>
---
 .gitlab/issue_templates/bug.md | 61 ++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 .gitlab/issue_templates/bug.md
.gitlab/issue_templates/bug.md new file +61 -0
new file mode 100644
index 00000000000..67a02a3ffcf
@@ -0,0 +1,61 @@
+<!--
+This is the upstream QEMU issue tracker.
+
+Before submitting a bug, please attempt to reproduce your problem using
+the latest development version of QEMU obtained from
+https://gitlab.com/qemu-project/qemu/.
+
+QEMU generally supports the last two releases advertised via
+https://www.qemu.org/. Problems with distro-packaged versions of QEMU
+older than this should be reported to the distribution instead.
+
+See https://www.qemu.org/contribute/report-a-bug/ for guidance.
+-->
+
+## Host environment
+ - Operating system: (Windows 10 21H1, Fedora 34, etc.)
+ - OS/kernel version: (For POSIX hosts, use `uname -a`)
+ - Architecture: (x86, ARM, s390x, etc.)
+ - QEMU flavor: (qemu-system-x86_64, qemu-aarch64, qemu-img, etc.)
+ - QEMU version: (e.g. `qemu-system-x86_64 --version`)
+ - QEMU command line:
+   <!--
+   Give the smallest, complete command line that exhibits the problem.
+
+   If you are using libvirt, virsh, or vmm, you can likely find the QEMU
+   command line arguments in /var/log/libvirt/qemu/$GUEST.log.
+   -->
+   ```
+   ./qemu-system-x86_64 -M q35 -m 4096 -enable-kvm -hda fedora32.qcow2
+   ```
+
+## Emulated/Virtualized environment
+ - Operating system: (Windows 10 21H1, Fedora 34, etc.)
+ - OS/kernel version: (For POSIX guests, use `uname -a`.)
+ - Architecture: (x86, ARM, s390x, etc.)
+
+
+## Description of problem
+<!-- Describe the problem, including any error/crash messages seen. -->
+
+## Steps to reproduce
+1.
+2.
+3.
+
+
+## Additional information
+
+<!--
+Attach logs, stack traces, screenshots, etc. Compress the files if necessary.
+If using libvirt, libvirt logs and XML domain information may be relevant.
+
+See https://qemu-project.gitlab.io/qemu/devel/tracing.html on how to
+configure additional QEMU logging.
+-->
+
+<!--
+The line below ensures that proper tags are added to the issue.
+Please do not remove it.
+-->
+/label ~"kind::Bug"
Signature · 1 line
2.30.2
#2 lore raw

Re: [PATCH v2 1/2] GitLab: Add "Bug" issue reporting template

.gitlab/issue_templates/bug.md line 6

Quoted 12 lines · John Snow
.gitlab/issue_templates/bug.md new file +6 -0
new file mode 100644
index 00000000000..67a02a3ffcf
@@ -0,0 +1,61 @@
+<!--
+This is the upstream QEMU issue tracker.
+
+Before submitting a bug, please attempt to reproduce your problem using
+the latest development version of QEMU obtained from
+https://gitlab.com/qemu-project/qemu/.

Please be specific about what "latest development version" means. I guess it means qemu.git/master?

If we are asking them to build QEMU then it would be nice to include a link with instructions on how to build from source.

.gitlab/issue_templates/bug.md line 19

Quoted 13 lines
.gitlab/issue_templates/bug.md new file +13 -0
+
+QEMU generally supports the last two releases advertised via
+https://www.qemu.org/. Problems with distro-packaged versions of QEMU
+older than this should be reported to the distribution instead.
+
+See https://www.qemu.org/contribute/report-a-bug/ for guidance.
+-->
+
+## Host environment
+ - Operating system: (Windows 10 21H1, Fedora 34, etc.)
+ - OS/kernel version: (For POSIX hosts, use `uname -a`)
+ - Architecture: (x86, ARM, s390x, etc.)
+ - QEMU flavor: (qemu-system-x86_64, qemu-aarch64, qemu-img, etc.)

Is this necessary since we ask for the command-line below?

.gitlab/issue_templates/bug.md line 54

Quoted 6 lines
.gitlab/issue_templates/bug.md new file +6 -0
+<!--
+Attach logs, stack traces, screenshots, etc. Compress the files if necessary.
+If using libvirt, libvirt logs and XML domain information may be relevant.
+
+See https://qemu-project.gitlab.io/qemu/devel/tracing.html on how to
+configure additional QEMU logging.

This sentence can be removed. Tracing is mostly for developers and requires knowledge of the source code. People who can use tracing already know about it and for the rest it doesn't count as "additional QEMU logging" because they won't be able to use it effectively.

author
#3 lore raw

Re: [PATCH v2 1/2] GitLab: Add "Bug" issue reporting template

Quoted 17 lines · Stefan Hajnoczi

.gitlab/issue_templates/bug.md line 6

Quoted 12 lines · John Snow
.gitlab/issue_templates/bug.md new file +6 -0
new file mode 100644
index 00000000000..67a02a3ffcf
@@ -0,0 +1,61 @@
+<!--
+This is the upstream QEMU issue tracker.
+
+Before submitting a bug, please attempt to reproduce your problem using
+the latest development version of QEMU obtained from
+https://gitlab.com/qemu-project/qemu/.

Please be specific about what "latest development version" means. I guess it means qemu.git/master?

I believe that's what I was asked to strongly encourage, yes. I'll make that clearer.

Quoted 3 lines

If we are asking them to build QEMU then it would be nice to include a link with instructions on how to build from source.

OK, good point. I am trying to keep it brief, so maybe I will point to a different wiki article. Some of our resources are a little too detailed, and I worry they won't get read at all.

We've got https://www.qemu.org/contribute/report-a-bug/ but I think it misses some items we want to address here. I could try to rework this page, or I could make a (very brief) "report a bug" wiki page instead.

Thoughts? (I am thinking I should at a minimum update the static page to be aware of the new tracker and these templates and help provide some clarifying instructions, but that more detailed steps ought to belong on the wiki, but am wary of link-rot if I link to subsections of a wiki article which could leave the static page links dangling.)

Quoted 7 lines
Quoted 7 lines
.gitlab/issue_templates/bug.md new file +7 -0
+
+QEMU generally supports the last two releases advertised via
+https://www.qemu.org/. Problems with distro-packaged versions of QEMU
+older than this should be reported to the distribution instead.
+
+See https://www.qemu.org/contribute/report-a-bug/ for guidance.
+-->
Quoted 9 lines

.gitlab/issue_templates/bug.md line 19

Quoted 6 lines
.gitlab/issue_templates/bug.md new file +6 -0
+
+## Host environment
+ - Operating system: (Windows 10 21H1, Fedora 34, etc.)
+ - OS/kernel version: (For POSIX hosts, use `uname -a`)
+ - Architecture: (x86, ARM, s390x, etc.)
+ - QEMU flavor: (qemu-system-x86_64, qemu-aarch64, qemu-img, etc.)

Is this necessary since we ask for the command-line below?

Not strictly, IF the entire form is filled out. I had noticed some bugs in gitlab where reporters seem to be aware of what kind of QEMU they are running, but are unable to procure the command line invocation. (it is being launched through docker, virsh, etc.) *

It's redundant, but I am operating on the belief that the CLI may not always be available. I don't expect people to not file a bug because they can't find it.

I think of it as a prompt to get a more detailed report on the first try. Is it worth keeping?

*(Aside: maybe a wiki "how to report a bug" page could have a small section on identifying the command line arguments when QEMU is being launched via vmm/boxes/virsh/docker and so on.)

Quoted 12 lines

.gitlab/issue_templates/bug.md line 54

Quoted 6 lines
.gitlab/issue_templates/bug.md new file +6 -0
+<!--
+Attach logs, stack traces, screenshots, etc. Compress the files if necessary.
+If using libvirt, libvirt logs and XML domain information may be relevant.
+
+See https://qemu-project.gitlab.io/qemu/devel/tracing.html on how to
+configure additional QEMU logging.

This sentence can be removed. Tracing is mostly for developers and requires knowledge of the source code. People who can use tracing already know about it and for the rest it doesn't count as "additional QEMU logging" because they won't be able to use it effectively.

OK, I agree. We can always provide instructions here as a follow-up if we deem it necessary. Fodder for a wiki page somewhere.

Thanks for looking!

--js

#4 lore raw

Re: [PATCH v2 1/2] GitLab: Add "Bug" issue reporting template

Quoted 20 lines · John Snow
Quoted 9 lines · Stefan Hajnoczi
Quoted 5 lines · John Snow

+## Host environment
+ - Operating system: (Windows 10 21H1, Fedora 34, etc.)
+ - OS/kernel version: (For POSIX hosts, use uname -a)
+ - Architecture: (x86, ARM, s390x, etc.)
+ - QEMU flavor: (qemu-system-x86_64, qemu-aarch64, qemu-img, etc.)

Is this necessary since we ask for the command-line below?

Not strictly, IF the entire form is filled out. I had noticed some bugs in gitlab where reporters seem to be aware of what kind of QEMU they are running, but are unable to procure the command line invocation. (it is being launched through docker, virsh, etc.) *

It's redundant, but I am operating on the belief that the CLI may not always be available. I don't expect people to not file a bug because they can't find it.

Quoted 6 lines

I think of it as a prompt to get a more detailed report on the first try. Is it worth keeping?

*(Aside: maybe a wiki "how to report a bug" page could have a small section on identifying the command line arguments when QEMU is being launched via vmm/boxes/virsh/docker and so on.)

It didn't occur to me that the fields were optional :).

For me personally, long bug reporting templates reduce the chance that I will report a bug.

Stefan

author
#5 lore raw

Re: [PATCH v2 1/2] GitLab: Add "Bug" issue reporting template

Quoted 28 lines · Stefan Hajnoczi
Quoted 20 lines · John Snow
Quoted 9 lines · Stefan Hajnoczi
Quoted 5 lines · John Snow

+## Host environment
+ - Operating system: (Windows 10 21H1, Fedora 34, etc.)
+ - OS/kernel version: (For POSIX hosts, use uname -a)
+ - Architecture: (x86, ARM, s390x, etc.)
+ - QEMU flavor: (qemu-system-x86_64, qemu-aarch64, qemu-img, etc.)

Is this necessary since we ask for the command-line below?

Not strictly, IF the entire form is filled out. I had noticed some bugs in gitlab where reporters seem to be aware of what kind of QEMU they are running, but are unable to procure the command line invocation. (it is being launched through docker, virsh, etc.) *

It's redundant, but I am operating on the belief that the CLI may not always be available. I don't expect people to not file a bug because they can't find it.

Quoted 6 lines

I think of it as a prompt to get a more detailed report on the first try. Is it worth keeping?

*(Aside: maybe a wiki "how to report a bug" page could have a small section on identifying the command line arguments when QEMU is being launched via vmm/boxes/virsh/docker and so on.)

Quoted 7 lines

It didn't occur to me that the fields were optional :).

For me personally, long bug reporting templates reduce the chance that I will report a bug.

Stefan

Yeah, it's a delicate balance. I want to imply they're mandatory. I don't want to call them optional, because then people may not feel compulsed to spend the effort to fill them out. I want them to feel a little compulsed. :)

On the other hand, sometimes these fields just won't apply, or there are reasons you can't fill them all out. A lot of reporters do not know how to build QEMU from source, or repeat a libvirt problem using 'raw' QEMU. Sometimes it's OK to file a less-than-perfect report. As you say, I don't want the barrier of entry to be too high.

Adding more instructions like "Hey, this field is optional if you have a CLI for us" just makes the template even longer and perhaps more intimidating, so I tried to keep it brief. Not my specialty ...

There's kind of a weird balance of implying things going on here. I suspect we will just have to try one approach and then change it as we observe how it gets used.

Don't think I'll solve it from the privacy of my own mind :)

Thanks for looking.
--js

author
#6 lore raw

PATCH v2 2/2 GitLab: Add "Feature Request" issue template.

In reply to John Snow

Based on Peter Krempa's libvirt template, feature.md.

CC Peter Krempa <[email protected]>
---
 .gitlab/issue_templates/feature_request.md | 32 ++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 .gitlab/issue_templates/feature_request.md
.gitlab/issue_templates/feature_request.md new file +32 -0
new file mode 100644
index 00000000000..fc58ca27634
@@ -0,0 +1,32 @@
+<!--
+This is the upstream QEMU issue tracker.
+
+Please note that QEMU, like most open source projects, relies on
+contributors who have motivation, skills and available time to work on
+implementing particular features.
+
+Feature requests can be helpful for determining demand and interest, but
+they are not a guarantee that a contributor will volunteer to implement
+it. We welcome and encourage even draft patches to implement a feature
+be sent to the mailing list where it can be discussed and developed
+further by the community.
+
+Thank you for your interest in helping us to make QEMU better!
+-->
+
+## Goal
+<!-- Describe the final result you want to achieve. Avoid design specifics. -->
+
+
+## Technical details
+<!-- Describe technical details, design specifics, suggestions, versions, etc. -->
+
+
+## Additional information
+
+
+<!--
+The line below ensures that proper tags are added to the issue.
+Please do not remove it.
+-->
+/label ~"kind::Feature Request"
Signature · 1 line
2.30.2
Reviewed-by on v2 2/2
#7 lore raw

Re: [PATCH v2 2/2] GitLab: Add "Feature Request" issue template.

Quoted 8 lines · John Snow

Based on Peter Krempa's libvirt template, feature.md.

CC Peter Krempa <[email protected]>
---
 .gitlab/issue_templates/feature_request.md | 32 ++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 .gitlab/issue_templates/feature_request.md
author
#8 lore raw
In reply to John Snow

ping -- Any objections?

Quoted 38 lines · John Snow

Add "Bug" and "Feature Request" templates to the Gitlab interface to help improve the quality of newly reported issues.

To see what this looks like, I've temporarily allowed my Gitlab fork to diverge with these files merged. See my fork's "new issue" page to see it in action: https://gitlab.com/jsnow/qemu/-/issues/new?issue

These patches do not add a "default" template, the user still has to select one from the list. I recommend that someone with permissions updates the default template:

1. https://gitlab.com/qemu-project/qemu/edit
2. ctrl+f "Default description template for issues"
3. Update the default to the (suggested) below:

```
<!-- Select "Type: Issue" and choose one of the Description templates above. -->
```

We can use this cover letter to discuss/review the wording on that default template which exists outside of repository data.

--js

V2:
- Updated both templates based on feedback from Peter, Daniel, and Thomas.

John Snow (2):
GitLab: Add "Bug" issue reporting template
GitLab: Add "Feature Request" issue template.

  .gitlab/issue_templates/bug.md             | 61 ++++++++++++++++++++++
  .gitlab/issue_templates/feature_request.md | 32 ++++++++++++
  2 files changed, 93 insertions(+)

create mode 100644 .gitlab/issue_templates/bug.md create mode 100644 .gitlab/issue_templates/feature_request.md