[PATCH v2 0/2] Gitlab: Add issue templates

[PATCH v2 0/2] Gitlab: Add issue templates

[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

-- 
2.30.2

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

[John Snow]

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

CC: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab/issue_templates/bug.md | 61 ++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 .gitlab/issue_templates/bug.md

diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md
new file mode 100644
index 00000000000..67a02a3ffcf
--- /dev/null
+++ b/.gitlab/issue_templates/bug.md
@@ -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"
-- 
2.30.2

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

[John Snow]

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

CC: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab/issue_templates/feature_request.md | 32 ++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 .gitlab/issue_templates/feature_request.md

diff --git a/.gitlab/issue_templates/feature_request.md b/.gitlab/issue_templates/feature_request.md
new file mode 100644
index 00000000000..fc58ca27634
--- /dev/null
+++ b/.gitlab/issue_templates/feature_request.md
@@ -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"
-- 
2.30.2

Re: [PATCH v2 0/2] Gitlab: Add issue templates

[John Snow]

ping -- Any objections?

On 5/21/21 1:38 PM, John Snow wrote:
> 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
> 

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

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1879 bytes --]

On Fri, May 21, 2021 at 01:38:17PM -0400, John Snow wrote:
> diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md
> new file mode 100644
> index 00000000000..67a02a3ffcf
> --- /dev/null
> +++ b/.gitlab/issue_templates/bug.md
> @@ -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.

> +
> +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?

> +<!--
> +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.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 448 bytes --]

On Fri, May 21, 2021 at 01:38:18PM -0400, John Snow wrote:
> Based on Peter Krempa's libvirt template, feature.md.
> 
> CC: Peter Krempa <pkrempa@redhat.com>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  .gitlab/issue_templates/feature_request.md | 32 ++++++++++++++++++++++
>  1 file changed, 32 insertions(+)
>  create mode 100644 .gitlab/issue_templates/feature_request.md

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[John Snow]

On 6/2/21 5:22 AM, Stefan Hajnoczi wrote:
> On Fri, May 21, 2021 at 01:38:17PM -0400, John Snow wrote:
>> diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md
>> new file mode 100644
>> index 00000000000..67a02a3ffcf
>> --- /dev/null
>> +++ b/.gitlab/issue_templates/bug.md
>> @@ -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.

> 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.)

>> +
>> +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?
> 

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.)

>> +<!--
>> +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

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

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1443 bytes --]

On Wed, Jun 02, 2021 at 12:09:47PM -0400, John Snow wrote:
> On 6/2/21 5:22 AM, Stefan Hajnoczi wrote:
> > On Fri, May 21, 2021 at 01:38:17PM -0400, John Snow wrote:
> > > +## 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.)

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[John Snow]

On 6/3/21 4:43 AM, Stefan Hajnoczi wrote:
> On Wed, Jun 02, 2021 at 12:09:47PM -0400, John Snow wrote:
>> On 6/2/21 5:22 AM, Stefan Hajnoczi wrote:
>>> On Fri, May 21, 2021 at 01:38:17PM -0400, John Snow wrote:
>>>> +## 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.)
> 
> 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