[libvirt PATCH] gitlab: Ask users not to attach screenshots to bug reports
Hopefully including this request in ALL CAPITAL LETTERS in the issue template will cut down on the number of screenshots that end up cluttering bug reports by at least a tiny bit. Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- .gitlab/issue_templates/bug.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md index f220671a06..b923be0ca0 100644 --- a/.gitlab/issue_templates/bug.md +++ b/.gitlab/issue_templates/bug.md @@ -17,3 +17,4 @@ ## Additional information <!-- Attach XML configs, logs, stack traces, etc. Compress the files if necessary --> <!-- See https://libvirt.org/kbase/debuglogs.html on how to configure logging --> +<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text --> -- 2.39.1
On a Friday in 2023, Andrea Bolognani wrote:
Hopefully including this request in ALL CAPITAL LETTERS in the
Using all caps on the internet can be interpreted as yelling and impolite.
issue template will cut down on the number of screenshots that end up cluttering bug reports by at least a tiny bit.
I think it won't help in majority of cases and therefore is not worth yelling and bug reporters. Jano
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- .gitlab/issue_templates/bug.md | 1 + 1 file changed, 1 insertion(+)
diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md index f220671a06..b923be0ca0 100644 --- a/.gitlab/issue_templates/bug.md +++ b/.gitlab/issue_templates/bug.md @@ -17,3 +17,4 @@ ## Additional information <!-- Attach XML configs, logs, stack traces, etc. Compress the files if necessary --> <!-- See https://libvirt.org/kbase/debuglogs.html on how to configure logging --> +<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text --> -- 2.39.1
On 2/10/23 10:34, Andrea Bolognani wrote:
Hopefully including this request in ALL CAPITAL LETTERS in the issue template will cut down on the number of screenshots that end up cluttering bug reports by at least a tiny bit.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- .gitlab/issue_templates/bug.md | 1 + 1 file changed, 1 insertion(+)
diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md index f220671a06..b923be0ca0 100644 --- a/.gitlab/issue_templates/bug.md +++ b/.gitlab/issue_templates/bug.md @@ -17,3 +17,4 @@ ## Additional information <!-- Attach XML configs, logs, stack traces, etc. Compress the files if necessary --> <!-- See https://libvirt.org/kbase/debuglogs.html on how to configure logging --> +<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text -->
Since we're changing our template, would it make sense to request users to at least attempt to reproduce on something recent? I've seen reports with ~3 years old libvirt. And given the pace libvirt's development is moving it's very likely that the issue is fixed. And even if it wasn't - we stop wasting our time trying to reproduce on current master only to find out the issue was fixed a while ago. I understand that some distros move slowly, but usually their users file bugs against distro bugzilla. Michal
On Fri, Feb 10, 2023 at 10:48:25AM +0100, Michal Prívozník wrote:
On 2/10/23 10:34, Andrea Bolognani wrote:
Hopefully including this request in ALL CAPITAL LETTERS in the issue template will cut down on the number of screenshots that end up cluttering bug reports by at least a tiny bit.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- .gitlab/issue_templates/bug.md | 1 + 1 file changed, 1 insertion(+)
diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md index f220671a06..b923be0ca0 100644 --- a/.gitlab/issue_templates/bug.md +++ b/.gitlab/issue_templates/bug.md @@ -17,3 +17,4 @@ ## Additional information <!-- Attach XML configs, logs, stack traces, etc. Compress the files if necessary --> <!-- See https://libvirt.org/kbase/debuglogs.html on how to configure logging --> +<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text -->
Since we're changing our template, would it make sense to request users to at least attempt to reproduce on something recent? I've seen reports with ~3 years old libvirt. And given the pace libvirt's development is moving it's very likely that the issue is fixed. And even if it wasn't - we stop wasting our time trying to reproduce on current master only to find out the issue was fixed a while ago.
We already link to: https://libvirt.org/bugs.html#how-to-file-high-quality-bug-reports which could be expanded with a suggestion that reproducing on latest upstream would be beneficial, rather than cluttering up the issue template With 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, Feb 10, 2023 at 10:48:25 +0100, Michal Prívozník wrote:
On 2/10/23 10:34, Andrea Bolognani wrote:
Hopefully including this request in ALL CAPITAL LETTERS in the issue template will cut down on the number of screenshots that end up cluttering bug reports by at least a tiny bit.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- .gitlab/issue_templates/bug.md | 1 + 1 file changed, 1 insertion(+)
diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md index f220671a06..b923be0ca0 100644 --- a/.gitlab/issue_templates/bug.md +++ b/.gitlab/issue_templates/bug.md @@ -17,3 +17,4 @@ ## Additional information <!-- Attach XML configs, logs, stack traces, etc. Compress the files if necessary --> <!-- See https://libvirt.org/kbase/debuglogs.html on how to configure logging --> +<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text -->
Since we're changing our template, would it make sense to request users to at least attempt to reproduce on something recent? I've seen reports with ~3 years old libvirt. And given the pace libvirt's development is moving it's very likely that the issue is fixed. And even if it wasn't - we stop wasting our time trying to reproduce on current master only to find out the issue was fixed a while ago.
I understand that some distros move slowly, but usually their users file bugs against distro bugzilla.
Originally I designed the bug template with way more prompts and during review we've agreed to do something minimal and link to a bigger document. This is so that users are not discouraged by a wall of text. I wonder whether we should do a better version of: https://libvirt.org/bugs.html#how-to-file-high-quality-bug-reports And add a more demanding prompt for users to read it. We can then include the wording to encourage only filing with recent versions on supported platforms, as well as ask to not attach screenshots. In the end in many cases issue reports are incomplete regardless of even the inline prompt which asks for VM XML and debug logs.
On Fri, Feb 10, 2023 at 10:34:11AM +0100, Andrea Bolognani wrote:
Hopefully including this request in ALL CAPITAL LETTERS in the issue template will cut down on the number of screenshots that end up cluttering bug reports by at least a tiny bit.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- .gitlab/issue_templates/bug.md | 1 + 1 file changed, 1 insertion(+)
diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md index f220671a06..b923be0ca0 100644 --- a/.gitlab/issue_templates/bug.md +++ b/.gitlab/issue_templates/bug.md @@ -17,3 +17,4 @@ ## Additional information <!-- Attach XML configs, logs, stack traces, etc. Compress the files if necessary --> <!-- See https://libvirt.org/kbase/debuglogs.html on how to configure logging --> +<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text -->
I think this is pretty user hostile. When filing bugs, the more rules a project imposes on the bug report, the less likely I am to go ahead with filing it, especially when the rules are worded in a very direct manner that makes it feel like you'll be flamed for getting it wrong. IMHO if someone provides a bug report with a screenshot and there is not sufficient accompanying information, just nicely ask them to explain the problem in a little more detail. We need todo that with plenty of bugs which don't have screenshots either, and screenshots can be helpful in some cases. With 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, Feb 10, 2023 at 09:50:25 +0000, Daniel P. Berrangé wrote:
On Fri, Feb 10, 2023 at 10:34:11AM +0100, Andrea Bolognani wrote:
Hopefully including this request in ALL CAPITAL LETTERS in the issue template will cut down on the number of screenshots that end up cluttering bug reports by at least a tiny bit.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- .gitlab/issue_templates/bug.md | 1 + 1 file changed, 1 insertion(+)
diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md index f220671a06..b923be0ca0 100644 --- a/.gitlab/issue_templates/bug.md +++ b/.gitlab/issue_templates/bug.md @@ -17,3 +17,4 @@ ## Additional information <!-- Attach XML configs, logs, stack traces, etc. Compress the files if necessary --> <!-- See https://libvirt.org/kbase/debuglogs.html on how to configure logging --> +<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text -->
I think this is pretty user hostile. When filing bugs, the more rules a project imposes on the bug report, the less likely I am to go ahead with filing it, especially when the rules are worded in a very direct manner that makes it feel like you'll be flamed for getting it wrong.
IMHO if someone provides a bug report with a screenshot and there is not sufficient accompanying information, just nicely ask them to explain the problem in a little more detail. We need todo that with plenty of bugs which don't have screenshots either, and screenshots can be helpful in some cases.
Screenshots indeed can be useful, it's just whent the user posts a screenshot of logs or the XML config which is extremely inconvenient. Thus I agree that disallowing screenshots is not something we want to do generally, but we should encourage users not to screenshot text/logs/xmls. As I wrote in a different subthread, we IMO need a minimalistic version of the page which instructs what to do without the extra clutter. Where we can write a bit more than here, but I agree that we should not add much more information here. The balance of simplicity vs putting all the required information is hard to strike as it's to see in the 'debuglogs' kbase page which grew a bit too much (by my hand unfortunately) after users were having repeated problems with configuring logging. At this point the article is a big wall of text and while there's guidance we IMO need also a minimal version of that page to go with the bug reporting howto.
On Fri, Feb 10, 2023 at 11:02:23AM +0100, Peter Krempa wrote:
On Fri, Feb 10, 2023 at 09:50:25 +0000, Daniel P. Berrangé wrote:
On Fri, Feb 10, 2023 at 10:34:11AM +0100, Andrea Bolognani wrote:
Hopefully including this request in ALL CAPITAL LETTERS in the issue template will cut down on the number of screenshots that end up cluttering bug reports by at least a tiny bit.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- .gitlab/issue_templates/bug.md | 1 + 1 file changed, 1 insertion(+)
diff --git a/.gitlab/issue_templates/bug.md b/.gitlab/issue_templates/bug.md index f220671a06..b923be0ca0 100644 --- a/.gitlab/issue_templates/bug.md +++ b/.gitlab/issue_templates/bug.md @@ -17,3 +17,4 @@ ## Additional information <!-- Attach XML configs, logs, stack traces, etc. Compress the files if necessary --> <!-- See https://libvirt.org/kbase/debuglogs.html on how to configure logging --> +<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text -->
I think this is pretty user hostile. When filing bugs, the more rules a project imposes on the bug report, the less likely I am to go ahead with filing it, especially when the rules are worded in a very direct manner that makes it feel like you'll be flamed for getting it wrong.
IMHO if someone provides a bug report with a screenshot and there is not sufficient accompanying information, just nicely ask them to explain the problem in a little more detail. We need todo that with plenty of bugs which don't have screenshots either, and screenshots can be helpful in some cases.
Screenshots indeed can be useful, it's just whent the user posts a screenshot of logs or the XML config which is extremely inconvenient.
Thus I agree that disallowing screenshots is not something we want to do generally, but we should encourage users not to screenshot text/logs/xmls.
Attaching screenshots of text/logs isn't really the common case though. We should be careful of not getting into the trap of optimizing for infrequent scenarios, such that we end up with a bunch of instructions which are irrelevant for the common case. If 30% of our bug reporters are getting something suboptimal, we should give guidance on it. If 2% of our bug reporters do something suboptimal, we should just deal with it after the fact. I feel like screenshots of XML docs are in the latter category.
As I wrote in a different subthread, we IMO need a minimalistic version of the page which instructs what to do without the extra clutter. Where we can write a bit more than here, but I agree that we should not add much more information here.
The balance of simplicity vs putting all the required information is hard to strike as it's to see in the 'debuglogs' kbase page which grew a bit too much (by my hand unfortunately) after users were having repeated problems with configuring logging. At this point the article is a big wall of text and while there's guidance we IMO need also a minimal version of that page to go with the bug reporting howto.
Yep, this is the trap I mention above. There is a natural tendency to add more docs every time someone gets something wrong, which over time ends up creating a huge set of instructions that no one will want to read. If we can optimize for the common case, and just accept that the infrequent problems can be dealt with when they happen, we should get a better balance With 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, Feb 10, 2023 at 09:50:25AM +0000, Daniel P. Berrangé wrote:
On Fri, Feb 10, 2023 at 10:34:11AM +0100, Andrea Bolognani wrote:
+<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text -->
I think this is pretty user hostile. When filing bugs, the more rules a project imposes on the bug report, the less likely I am to go ahead with filing it, especially when the rules are worded in a very direct manner that makes it feel like you'll be flamed for getting it wrong.
For the person reporting the bug, taking a screenshot and attaching it or copying and pasting the corresponding text shouldn't make any difference in terms of effort. If anything, the latter is probably going to be less work. Yeah, the wording I've proposed can perhaps be seen as hostile. Any suggestions on how to improve it, while still making it pop out so that users aren't likely to miss it?
IMHO if someone provides a bug report with a screenshot and there is not sufficient accompanying information, just nicely ask them to explain the problem in a little more detail. We need todo that with plenty of bugs which don't have screenshots either, and screenshots can be helpful in some cases.
Sure, but there's a difference between asking for more details, which can always be done as a follow-up, and asking users to provide information as plain text instead of screenshots. In the latter case, once the screenshot has been attached, that's it, there's no going back. -- Andrea Bolognani / Red Hat / Virtualization
On Fri, Feb 10, 2023 at 02:27:46AM -0800, Andrea Bolognani wrote:
On Fri, Feb 10, 2023 at 09:50:25AM +0000, Daniel P. Berrangé wrote:
On Fri, Feb 10, 2023 at 10:34:11AM +0100, Andrea Bolognani wrote:
+<!-- Please DO NOT ATTACH SCREENSHOTS to the bug report. Provide all information as plain text -->
I think this is pretty user hostile. When filing bugs, the more rules a project imposes on the bug report, the less likely I am to go ahead with filing it, especially when the rules are worded in a very direct manner that makes it feel like you'll be flamed for getting it wrong.
For the person reporting the bug, taking a screenshot and attaching it or copying and pasting the corresponding text shouldn't make any difference in terms of effort. If anything, the latter is probably going to be less work.
I wouldn't be so sure of that. I can very easily see people connecting to Linux hypervisors from a Windows terminal client and finding it easier to just hit 'PrtSr' key on their keyboard, instead of copying the files over with an scp client.
Yeah, the wording I've proposed can perhaps be seen as hostile. Any suggestions on how to improve it, while still making it pop out so that users aren't likely to miss it?
I'm not convinced the problem of screenshotting XML docs is frequent enough top justify explicitly mentioning, certain not in the issue template. As most something in the separate docs about how to improve issue reports.
IMHO if someone provides a bug report with a screenshot and there is not sufficient accompanying information, just nicely ask them to explain the problem in a little more detail. We need todo that with plenty of bugs which don't have screenshots either, and screenshots can be helpful in some cases.
Sure, but there's a difference between asking for more details, which can always be done as a follow-up, and asking users to provide information as plain text instead of screenshots. In the latter case, once the screenshot has been attached, that's it, there's no going back.
Why can't we ask users to add the XML as text afterwards ? I've often done just that when people have attached images, if it was useful to me to have it in text format. With 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, Feb 10, 2023 at 11:11:03AM +0000, Daniel P. Berrangé wrote:
On Fri, Feb 10, 2023 at 02:27:46AM -0800, Andrea Bolognani wrote:
On Fri, Feb 10, 2023 at 09:50:25AM +0000, Daniel P. Berrangé wrote:
IMHO if someone provides a bug report with a screenshot and there is not sufficient accompanying information, just nicely ask them to explain the problem in a little more detail. We need todo that with plenty of bugs which don't have screenshots either, and screenshots can be helpful in some cases.
Sure, but there's a difference between asking for more details, which can always be done as a follow-up, and asking users to provide information as plain text instead of screenshots. In the latter case, once the screenshot has been attached, that's it, there's no going back.
Why can't we ask users to add the XML as text afterwards ? I've often done just that when people have attached images, if it was useful to me to have it in text format.
That feels worse, from the user's point of view, than being asked to do that ahead of time, because it introduces friction and delays. Anyway, clearly people are not into this patch and I don't care enough about it to fiercely advocate for its inclusion, so let's all grab our favorite SNACK and move on :) -- Andrea Bolognani / Red Hat / Virtualization
participants (5)
-
Andrea Bolognani -
Daniel P. Berrangé -
Ján Tomko -
Michal Prívozník -
Peter Krempa