7:23 a.m.
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=&...
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
7:23 a.m.
New subject: [PATCH 1/3] gitlab: Add issue template for reporting a generic bug
When reporting an issue in gitlab, the project can define a template for
various scenarios which are meant to guide the users to add the relevant
information the project needs to the reported issue.
Add a template for a generic bug report against libvirt. The template
adds sections which motivate users to add version information and also
link to documentation about fetching logs and such.
Another section then motivates the users to describe the steps taken and
also the expected outcome if it's not obvious.
Finally a template also automatically applies one or more labels, so new
issues are already partially pre-triaged.
Note that markdown seems to be the only supported format for now.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
.gitlab/issue_templates/bug.md | 55 ++++++++++++++++++++++++++++++++++
1 file changed, 55 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 0000000000..f8f8ce2cef
--- /dev/null
+++ b/.gitlab/issue_templates/bug.md
@@ -0,0 +1,55 @@
+<!-- This issue describes a bug in libvirt -->
+
+<!--
+ Note: Sections like this one will be stripped out once you submit the issue.
+
+ Please describe the bug as much as possible and add any relevant information
+ you have. It allows us to deal with issues quicker.
+
+ A good bug report requires attaching of debug logs in a vast majority of cases,
+ please refer to [https://www.libvirt.org/kbase/debuglogs.html] for documentation
+ on how to obtain them.
+
+ Refer to [https://libvirt.org/bugs.html#quality] for further information regarding
+ reporting a bug.
+-->
+
+## Versions and environment
+<!--
+ Provide versions of libvirtd and possibly other relevant components if you
+ are able to narrow down the problem. Also describe any specialties in your setup.
+
+ Important:
+ Please make sure that the bug you are reporting can be reproduced with a
+ recent libvirt version (ideally upstream) to ensure that it wasn't fixed
+ already.
+-->
+ - libvirt:
+ -
+
+## Description of the bug
+<!-- Describe what happened and what's supposed to happen if that isn't
obvious -->
+
+## Steps to reproduce the bug
+<!-- Describe the steps necessary to reproduce the bug -->
+1.
+2.
+3.
+4.
+
+## Additional information
+<!--
+ Attach any relevant information:
+ - XML configuration documents of VMs or other objects
+ - log files (please attach compressed archive if you can't find the relevant
section)
+
+ If reporting a crash:
+ - stack trace of the crashed binary
+
+ Please don't post screenshots of text.
+-->
+
+
+
+<!-- The line below ensures that proper tags are added to the issue. -- >
+/label ~bug
--
2.28.0
7:23 a.m.
New subject: [PATCH 2/3] gitlab: Add issue template for a feature request
Try to motivate the users to describe what they want to achieve before
diving down into technical specifics.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
.gitlab/issue_templates/feature.md | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
create mode 100644 .gitlab/issue_templates/feature.md
diff --git a/.gitlab/issue_templates/feature.md b/.gitlab/issue_templates/feature.md
new file mode 100644
index 0000000000..ef97e65912
--- /dev/null
+++ b/.gitlab/issue_templates/feature.md
@@ -0,0 +1,26 @@
+<!-- This issue describes a feature request in libvirt -->
+
+<!--
+ Note: Sections like this one will be stripped out once you submit the issue.
+-->
+
+## Goal
+<!--
+ Please describe the final result you want to achieve. Try refrain from
+ design specifics.
+-->
+
+
+## Technical details
+<!--
+ Describe possible technical details, design specific, suggestions, versions
+ of components needed to support the feature, etc...
+-->
+
+
+## Additional information
+
+
+
+<!-- The line below ensures that proper tags are added to the issue. -- >
+/label ~enhancement
--
2.28.0
7:23 a.m.
New subject: [PATCH 3/3] gitlab: Add issue template for filing a bug in libvirt's qemu driver
Add a qemu-specific version of the bug report template. The additional
data section focuses on requesting VM xml, VM log file and debug logs
and adds the 'driver-qemu' label.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
.gitlab/issue_templates/bug-qemu.md | 56 +++++++++++++++++++++++++++++
1 file changed, 56 insertions(+)
create mode 100644 .gitlab/issue_templates/bug-qemu.md
diff --git a/.gitlab/issue_templates/bug-qemu.md b/.gitlab/issue_templates/bug-qemu.md
new file mode 100644
index 0000000000..5352ccef3c
--- /dev/null
+++ b/.gitlab/issue_templates/bug-qemu.md
@@ -0,0 +1,56 @@
+<!-- This issue describes a bug in the qemu driver of libvirt -->
+
+<!--
+ Note: Sections like this one will be stripped out once you submit the issue.
+
+ Please describe the bug as much as possible and add any relevant information
+ you have. It allows us to deal with issues quicker.
+
+ Refer to [https://libvirt.org/bugs.html#quality] for further information regarding
+ reporting a bug.
+-->
+
+## Versions and environment
+<!--
+ Provide versions of libvirtd, qemu and possibly other relevant components if you
+ are able to narrow down the problem. Also describe any specialties in your setup.
+
+ Important:
+ Please make sure that the bug you are reporting can be reproduced with a
+ recent libvirt version (ideally upstream) to ensure that it wasn't fixed
+ already.
+-->
+ - libvirt:
+ - qemu:
+
+## Description of the bug
+<!-- Describe what happened and what's supposed to happen if that isn't
obvious -->
+
+## Steps to reproduce the bug
+<!-- Describe the steps necessary to reproduce the bug -->
+1.
+2.
+3.
+4.
+
+## Additional information
+<!--
+ Attach any relevant information:
+ - XML configuration of the VM
+ - config files:
+ - /etc/libvirt/qemu.conf (If you've modified the settings)
+ - log files:
+ - libvirtd debug log file [https://www.libvirt.org/kbase/debuglogs.html]
+ - qemu VM log (/var/log/libvirt/qemu/$VMNAME.log)
+ - please attach compressed archive if you can't find the relevant section
+
+ If reporting a crash:
+ - stack trace of the crashed binary
+
+ Please don't post screenshots of text.
+-->
+
+
+
+<!-- The line below ensures that proper tags are added to the issue. -- >
+/label ~bug ~driver-qemu
--
2.28.0
12:59 p.m.
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=&...
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
1:51 p.m.
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=&...
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 :|
9:15 a.m.
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=&...
>
> 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.
10:50 a.m.
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=&...
> >
> > 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/faf1aee60675604a04cbe2e2441d...
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 :|
11:05 a.m.
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/faf1aee60675604a04cbe2e2441d...
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.
2:51 a.m.
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/faf1aee60675604a04cbe2e2441d...
>
> 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
3:44 a.m.
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.
1453
days inactive
1457
days old
10 comments
4 participants
participants (4)
-
Daniel Henrique Barboza -
Daniel P. Berrangé -
Pavel Hrdina -
Peter Krempa