Gitlab allows projects to define templates for filing issues [1].
Libvirt didn't have them yet. We can use them to encourage users to
file better bug reports and feature requests.

You can test-drive the proposed templates in my test repo:

https://gitlab.com/pipo.sk/test/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=

Any suggestions on how to improve them further are very welcome.


[1] https://docs.gitlab.com/ee/user/project/description_templates.html

Peter Krempa (3):
  gitlab: Add issue template for reporting a generic bug
  gitlab: Add issue template for a feature request
  gitlab: Add issue template for filing a bug in libvirt's qemu driver

 .gitlab/issue_templates/bug-qemu.md | 56 +++++++++++++++++++++++++++++
 .gitlab/issue_templates/bug.md      | 55 ++++++++++++++++++++++++++++
 .gitlab/issue_templates/feature.md  | 26 ++++++++++++++
 3 files changed, 137 insertions(+)
 create mode 100644 .gitlab/issue_templates/bug-qemu.md
 create mode 100644 .gitlab/issue_templates/bug.md
 create mode 100644 .gitlab/issue_templates/feature.md

-- 
2.28.0

On 11/26/20 10:23 AM, Peter Krempa wrote:
> Gitlab allows projects to define templates for filing issues [1].
> Libvirt didn't have them yet. We can use them to encourage users to
> file better bug reports and feature requests.
> 
> You can test-drive the proposed templates in my test repo:
> 
> https://gitlab.com/pipo.sk/test/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=
> 
> Any suggestions on how to improve them further are very welcome.

They look good. Couple of suggestions:

- in the bug-qemu template: either add a 'host OS' or a 'host kernel'
field in the  'versions and environment' section. Having to know the
kernel version the user is rocking to determine the cause of a QEMU bug
is not uncommon. Most of the cases knowing the host OS suffices to
get the kernel version, so any of those works;

- for all templates: if the bug happens in an non-x86 arch we want to know
about it. I'd say that a text in the "Versions and environment" section
with something akin of:

"If the bug happens in an architecture other than x86_64, please inform it
below"

will not annoy x86_64 users while also contemplating that other archs are
also supported.


Thanks,


DHB




> 
> 
> [1] https://docs.gitlab.com/ee/user/project/description_templates.html
> 
> Peter Krempa (3):
>    gitlab: Add issue template for reporting a generic bug
>    gitlab: Add issue template for a feature request
>    gitlab: Add issue template for filing a bug in libvirt's qemu driver
> 
>   .gitlab/issue_templates/bug-qemu.md | 56 +++++++++++++++++++++++++++++
>   .gitlab/issue_templates/bug.md      | 55 ++++++++++++++++++++++++++++
>   .gitlab/issue_templates/feature.md  | 26 ++++++++++++++
>   3 files changed, 137 insertions(+)
>   create mode 100644 .gitlab/issue_templates/bug-qemu.md
>   create mode 100644 .gitlab/issue_templates/bug.md
>   create mode 100644 .gitlab/issue_templates/feature.md
> 

On Thu, Nov 26, 2020 at 02:23:17PM +0100, Peter Krempa wrote:
> Gitlab allows projects to define templates for filing issues [1].
> Libvirt didn't have them yet. We can use them to encourage users to
> file better bug reports and feature requests.
> 
> You can test-drive the proposed templates in my test repo:
> 
> https://gitlab.com/pipo.sk/test/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=
> 
> Any suggestions on how to improve them further are very welcome.

Looking at it live, I get a bit lost about where exactly I need
to enter the information, as the huge comments dominate the view
compared to the prompts for information. I worry that people will
enter information inside the comments, which then gets thrown away.

I wonder if we're better off just having the headings/prompts
and linking to an external page with verbose suggestions.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Thu, Nov 26, 2020 at 19:51:53 +0000, Daniel Berrange wrote:
> On Thu, Nov 26, 2020 at 02:23:17PM +0100, Peter Krempa wrote:
> > Gitlab allows projects to define templates for filing issues [1].
> > Libvirt didn't have them yet. We can use them to encourage users to
> > file better bug reports and feature requests.
> > 
> > You can test-drive the proposed templates in my test repo:
> > 
> > https://gitlab.com/pipo.sk/test/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=
> > 
> > Any suggestions on how to improve them further are very welcome.
> 
> Looking at it live, I get a bit lost about where exactly I need
> to enter the information, as the huge comments dominate the view
> compared to the prompts for information. I worry that people will
> enter information inside the comments, which then gets thrown away.

It's not completely thrown away. If you edit the bug description, you
still see the full source which was submitted.

Also the very first line mentions that the comments are not shown ...

> I wonder if we're better off just having the headings/prompts
> and linking to an external page with verbose suggestions.

... so if the user doesn't bother to read that, I doubt a link to full
description will help.

I can try to send a cut-down version, which will have only single-line
comments with the suggestions, but I still think that we are better off
having the request for data in the body of the bugreport than sending
them to some documentation elsewhere.

On Fri, Nov 27, 2020 at 04:15:44PM +0100, Peter Krempa wrote:
> On Thu, Nov 26, 2020 at 19:51:53 +0000, Daniel Berrange wrote:
> > On Thu, Nov 26, 2020 at 02:23:17PM +0100, Peter Krempa wrote:
> > > Gitlab allows projects to define templates for filing issues [1].
> > > Libvirt didn't have them yet. We can use them to encourage users to
> > > file better bug reports and feature requests.
> > > 
> > > You can test-drive the proposed templates in my test repo:
> > > 
> > > https://gitlab.com/pipo.sk/test/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=
> > > 
> > > Any suggestions on how to improve them further are very welcome.
> > 
> > Looking at it live, I get a bit lost about where exactly I need
> > to enter the information, as the huge comments dominate the view
> > compared to the prompts for information. I worry that people will
> > enter information inside the comments, which then gets thrown away.
> 
> It's not completely thrown away. If you edit the bug description, you
> still see the full source which was submitted.
> 
> Also the very first line mentions that the comments are not shown ...
> 
> > I wonder if we're better off just having the headings/prompts
> > and linking to an external page with verbose suggestions.
> 
> ... so if the user doesn't bother to read that, I doubt a link to full
> description will help.
> 
> I can try to send a cut-down version, which will have only single-line
> comments with the suggestions, but I still think that we are better off
> having the request for data in the body of the bugreport than sending
> them to some documentation elsewhere.

I pushed an example of a simpler template that is much more like the
view you get when using Bugzilla:

https://gitlab.com/berrange/libvirt/-/issues/new

https://gitlab.com/berrange/libvirt/-/commit/faf1aee60675604a04cbe2e2441dcad233963b86

IMHO, this kind of simpler template is less intimidating and clearer
as to what information to provide.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Fri, Nov 27, 2020 at 16:50:01 +0000, Daniel Berrange wrote:
> On Fri, Nov 27, 2020 at 04:15:44PM +0100, Peter Krempa wrote:
> > On Thu, Nov 26, 2020 at 19:51:53 +0000, Daniel Berrange wrote:
> > > On Thu, Nov 26, 2020 at 02:23:17PM +0100, Peter Krempa wrote:

[...]

> > I can try to send a cut-down version, which will have only single-line
> > comments with the suggestions, but I still think that we are better off
> > having the request for data in the body of the bugreport than sending
> > them to some documentation elsewhere.
> 
> I pushed an example of a simpler template that is much more like the
> view you get when using Bugzilla:
> 
> https://gitlab.com/berrange/libvirt/-/issues/new
> 
> https://gitlab.com/berrange/libvirt/-/commit/faf1aee60675604a04cbe2e2441dcad233963b86
> 
> IMHO, this kind of simpler template is less intimidating and clearer
> as to what information to provide.

I'm missing a section or hint to upload XMLs and logs if approrpiate.
In many cases users will just post the error and don't add any relevant
information. When later asked they won't be able to produce them as
they've torn down the setup.

Also given the amount of already fixed bugs I'd add a hint to try to
test it on latest version, but I'm not as keen on having this one as the
previous one.

On Fri, Nov 27, 2020 at 06:05:41PM +0100, Peter Krempa wrote:
> On Fri, Nov 27, 2020 at 16:50:01 +0000, Daniel Berrange wrote:
> > On Fri, Nov 27, 2020 at 04:15:44PM +0100, Peter Krempa wrote:
> > > On Thu, Nov 26, 2020 at 19:51:53 +0000, Daniel Berrange wrote:
> > > > On Thu, Nov 26, 2020 at 02:23:17PM +0100, Peter Krempa wrote:
> 
> [...]
> 
> > > I can try to send a cut-down version, which will have only single-line
> > > comments with the suggestions, but I still think that we are better off
> > > having the request for data in the body of the bugreport than sending
> > > them to some documentation elsewhere.
> > 
> > I pushed an example of a simpler template that is much more like the
> > view you get when using Bugzilla:
> > 
> > https://gitlab.com/berrange/libvirt/-/issues/new
> > 
> > https://gitlab.com/berrange/libvirt/-/commit/faf1aee60675604a04cbe2e2441dcad233963b86
> > 
> > IMHO, this kind of simpler template is less intimidating and clearer
> > as to what information to provide.
> 
> I'm missing a section or hint to upload XMLs and logs if approrpiate.
> In many cases users will just post the error and don't add any relevant
> information. When later asked they won't be able to produce them as
> they've torn down the setup.
> 
> Also given the amount of already fixed bugs I'd add a hint to try to
> test it on latest version, but I'm not as keen on having this one as the
> previous one.

Both of the proposals are improvement compared to the current situation.

I guess for the new_feature template there is nothing to discuss. I
guess we can remove the <!-- Note: ... --> comment. It's not necessary
to have it in the template and if users remove the other comments before
submitting the issue it will do no harm as well.

For the qemu bug report I'm not so sure about having separate template
for QEMU, I don't see that much value in having it and it might confuse
users or users of other hypervisors might start asking for adding a
template for them as well.

The generic bug report I would go for something in between the two
proposals. The one from Peter has a lot of comments at the beginning
which might be confusing for the users and they can get easily lost
in the template. The one from Dan is missing additional details like
XML of the VM or device, debug logs or any logs.

When I was discussing this with Peter I suggested using some command
examples on how to get the specific details but looking into it right
now it is mostly not necessary. The only place where it could help
would be to describe how to enable debug logs but that would make
the template way too long and probably confusing for the users because
enabling debug logs is not that trivial and there are some caveats
described in the document like returning back to the original logging
settings and the difference between runtime and persistent setting and
so on.

Taking both proposals for the template I would go with something like
this:

------------------------------------------------------------------------

<!-- See https://libvirt.org/bugs.html#quality for guidance -->

## Software environment
 - Operating system:
 - Architecture:
 - kernel version:
 - libvirt version:
 - Hypervisor and version:

## Description of problem

## Steps to reproduce
1.
2.
3.

## Expected behavior

## Additional information

<!-- 
  Please provide additional details. This list is not complete and
  contains what we usually ask the reporter if missing:

   - XML configuration of VMs or other objects
   - log files (please attach compressed archive if you can't find the relevant section)
   - stack trace of the crashed binary

  See https://libvirt.org/kbase/debuglogs.html for details how to
  configure debug logs.

<!-- The line below ensures that proper tags are added to the issue. -- >
/label ~bug

------------------------------------------------------------------------

I've added a kernel version line and the additional info section.

All of this combines the ideas from Peter and Dan.

Pavel

On Mon, Nov 30, 2020 at 09:51:26 +0100, Pavel Hrdina wrote:
> On Fri, Nov 27, 2020 at 06:05:41PM +0100, Peter Krempa wrote:
> > On Fri, Nov 27, 2020 at 16:50:01 +0000, Daniel Berrange wrote:

[...]

> ------------------------------------------------------------------------
> 
> <!-- See https://libvirt.org/bugs.html#quality for guidance -->
> 
> ## Software environment
>  - Operating system:
>  - Architecture:
>  - kernel version:
>  - libvirt version:
>  - Hypervisor and version:
> 
> ## Description of problem
> 
> ## Steps to reproduce
> 1.
> 2.
> 3.
> 
> ## Expected behavior
> 
> ## Additional information
> 
> <!-- 
>   Please provide additional details. This list is not complete and
>   contains what we usually ask the reporter if missing:
> 
>    - XML configuration of VMs or other objects
>    - log files (please attach compressed archive if you can't find the relevant section)
>    - stack trace of the crashed binary
> 
>   See https://libvirt.org/kbase/debuglogs.html for details how to
>   configure debug logs.

Missing end of comment.

> 
> <!-- The line below ensures that proper tags are added to the issue. -- >
> /label ~bug

I like this as it explicitly asks for configs. Also a bonus is that it's
lean on comments at the top, which is shown first.

I think that we should add the note of commit being stripped to the
multiline comment though, to be a bit safer.