[PATCH 0/3] gitlab: Add issue templates
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
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@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
Try to motivate the users to describe what they want to achieve before diving down into technical specifics. Signed-off-by: Peter Krempa <pkrempa@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
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@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
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/faf1aee60675604a04cbe2e2441dcad... 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/faf1aee60675604a04cbe2e2441dcad...
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/faf1aee60675604a04cbe2e2441dcad...
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.
participants (4)
-
Daniel Henrique Barboza -
Daniel P. Berrangé -
Pavel Hrdina -
Peter Krempa