[PATCH 0/2] improve bugreports

[PATCH 0/2] improve bugreports

[Rubén Justo]

Let's try to improve the readability of the bug reports we receive.

The first message should not receive many comments.  The second one
might.  I'm open to suggestions.

Thanks.

Rubén Justo (2):
  bugreport: add a new line between questions
  bugreport: add a mark to each proposed questions

 builtin/bugreport.c  | 16 ++++++++--------
 t/t0091-bugreport.sh | 12 ++++++++----
 2 files changed, 16 insertions(+), 12 deletions(-)

-- 
2.44.0.494.g7a0daf3e0d

[PATCH 1/2] bugreport: add a new line between questions

[Rubén Justo]

Occasionally, we receive reports where the user have filled in the blank
line we provide between each proposed question, without leaving any
space between the answer and the next question.  This makes reading the
report uncomfortable.

Perhaps we can suggest to the user to include a blank line if we
duplicate the empty line we provide.  Let's do that and see what
happens.

Signed-off-by: Rubén Justo <rjusto@gmail.com>
---
 builtin/bugreport.c  | 8 ++++----
 t/t0091-bugreport.sh | 4 ++++
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 25f860a0d9..01b72163b9 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -77,13 +77,13 @@ static int get_bug_template(struct strbuf *template)
 "Please answer the following questions to help us understand your issue.\n"
 "\n"
 "What did you do before the bug happened? (Steps to reproduce your issue)\n"
-"\n"
+"\n\n"
 "What did you expect to happen? (Expected behavior)\n"
-"\n"
+"\n\n"
 "What happened instead? (Actual behavior)\n"
-"\n"
+"\n\n"
 "What's different between what you expected and what actually happened?\n"
-"\n"
+"\n\n"
 "Anything else you want to add:\n"
 "\n"
 "Please review the rest of the bug report below.\n"
diff --git a/t/t0091-bugreport.sh b/t/t0091-bugreport.sh
index fca39048fe..f9c1ff9cb2 100755
--- a/t/t0091-bugreport.sh
+++ b/t/t0091-bugreport.sh
@@ -18,12 +18,16 @@ test_expect_success 'report contains wanted template (before first section)' '
 
 	What did you do before the bug happened? (Steps to reproduce your issue)
 
+
 	What did you expect to happen? (Expected behavior)
 
+
 	What happened instead? (Actual behavior)
 
+
 	What'\''s different between what you expected and what actually happened?
 
+
 	Anything else you want to add:
 
 	Please review the rest of the bug report below.
-- 
2.44.0.494.g7a0daf3e0d

[PATCH 2/2] bugreport: add a mark to each proposed questions

[Rubén Justo]

Include a mark in the questions we provide, to enhance the readability
of the reports we receive.

Of course, the user has the flexibility to choose a different format or
rewrite the report entirely.  However, including these marks in the
template may suggest that we value some structure in the message.

Signed-off-by: Rubén Justo <rjusto@gmail.com>
---
 builtin/bugreport.c  | 8 ++++----
 t/t0091-bugreport.sh | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/builtin/bugreport.c b/builtin/bugreport.c
index 01b72163b9..d60ec483fa 100644
--- a/builtin/bugreport.c
+++ b/builtin/bugreport.c
@@ -76,13 +76,13 @@ static int get_bug_template(struct strbuf *template)
 "Thank you for filling out a Git bug report!\n"
 "Please answer the following questions to help us understand your issue.\n"
 "\n"
-"What did you do before the bug happened? (Steps to reproduce your issue)\n"
+"== What did you do before the bug happened? (Steps to reproduce your issue)\n"
 "\n\n"
-"What did you expect to happen? (Expected behavior)\n"
+"== What did you expect to happen? (Expected behavior)\n"
 "\n\n"
-"What happened instead? (Actual behavior)\n"
+"== What happened instead? (Actual behavior)\n"
 "\n\n"
-"What's different between what you expected and what actually happened?\n"
+"== What's different between what you expected and what actually happened?\n"
 "\n\n"
 "Anything else you want to add:\n"
 "\n"
diff --git a/t/t0091-bugreport.sh b/t/t0091-bugreport.sh
index f9c1ff9cb2..9b3a2b0cd2 100755
--- a/t/t0091-bugreport.sh
+++ b/t/t0091-bugreport.sh
@@ -16,16 +16,16 @@ test_expect_success 'report contains wanted template (before first section)' '
 	Thank you for filling out a Git bug report!
 	Please answer the following questions to help us understand your issue.
 
-	What did you do before the bug happened? (Steps to reproduce your issue)
+	== What did you do before the bug happened? (Steps to reproduce your issue)
 
 
-	What did you expect to happen? (Expected behavior)
+	== What did you expect to happen? (Expected behavior)
 
 
-	What happened instead? (Actual behavior)
+	== What happened instead? (Actual behavior)
 
 
-	What'\''s different between what you expected and what actually happened?
+	== What'\''s different between what you expected and what actually happened?
 
 
 	Anything else you want to add:
-- 
2.44.0.494.g7a0daf3e0d

Re: [PATCH 0/2] improve bugreports

[Rubén Justo]

On Sat, Mar 23, 2024 at 06:32:35PM +0100, Rubén Justo wrote:
> Let's try to improve the readability of the bug reports we receive.
> 
> The first message should not receive many comments.  The second one
> might.  I'm open to suggestions.
> 
> Thanks.
> 
> Rubén Justo (2):
>   bugreport: add a new line between questions
>   bugreport: add a mark to each proposed questions
> 
>  builtin/bugreport.c  | 16 ++++++++--------
>  t/t0091-bugreport.sh | 12 ++++++++----
>  2 files changed, 16 insertions(+), 12 deletions(-)
> 
> -- 
> 2.44.0.494.g7a0daf3e0d

This series received no response.  One option may be because it went
unnoticed, another because it may not add value.  I'm going to give it
another try and I'll quietly :-) take silence as confirmation of the
second option. 

I'll try to increase the chances of getting a "looks good" by CC'ing
some folks involved in the bugreport tool.

Thanks.

Re: [PATCH 0/2] improve bugreports

[Eric Sunshine]

On Sun, Mar 31, 2024 at 3:04 AM Rubén Justo <rjusto@gmail.com> wrote:
> On Sat, Mar 23, 2024 at 06:32:35PM +0100, Rubén Justo wrote:
> > Let's try to improve the readability of the bug reports we receive.
>
> This series received no response.  One option may be because it went
> unnoticed, another because it may not add value.  I'm going to give it
> another try and I'll quietly :-) take silence as confirmation of the
> second option.
>
> I'll try to increase the chances of getting a "looks good" by CC'ing
> some folks involved in the bugreport tool.

For what it's worth, when I read the cover letter of this series, I
thought it was going to clean up the list of questions to eliminate
redundancy. In particular, of the three questions:

   What did you expect to happen?
   What happened instead?
   What's different between what you expected
        and what actually happened?

the final one seems to repeat what the first two ask, and it is common
when answering the third question for people to simply repeat what was
said in response to an earlier question.

Re: [PATCH 0/2] improve bugreports

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> redundancy. In particular, of the three questions:
>
>    What did you expect to happen?
>    What happened instead?
>    What's different between what you expected
>         and what actually happened?
>
> the final one seems to repeat what the first two ask, and it is common
> when answering the third question for people to simply repeat what was
> said in response to an earlier question.

The third one may need to be rephrased, but I think it should still
be there.  The intent is to make the reporter realize how unhelpful
their answers are when they answer the first two questions with

 - I expected it to work correctly
 - It did not work correctly

They hopefully would realize that "work correctly" needs to be
elaborated in order to answer the third question in a useful way.
If the first two questions have been answered in a usable way, the
third one is often redundant.

Re: [PATCH 0/2] improve bugreports

[Rubén Justo]

On Sun, Mar 31, 2024 at 11:09:02PM -0400, Eric Sunshine wrote:
> On Sun, Mar 31, 2024 at 3:04 AM Rubén Justo <rjusto@gmail.com> wrote:
> > On Sat, Mar 23, 2024 at 06:32:35PM +0100, Rubén Justo wrote:
> > > Let's try to improve the readability of the bug reports we receive.
> >
> > This series received no response.  One option may be because it went
> > unnoticed, another because it may not add value.  I'm going to give it
> > another try and I'll quietly :-) take silence as confirmation of the
> > second option.
> >
> > I'll try to increase the chances of getting a "looks good" by CC'ing
> > some folks involved in the bugreport tool.
> 
> For what it's worth, when I read the cover letter of this series, I
> thought it was going to clean up the list of questions to eliminate
> redundancy. In particular, of the three questions:
> 
>    What did you expect to happen?
>    What happened instead?
>    What's different between what you expected
>         and what actually happened?
> 
> the final one seems to repeat what the first two ask, and it is common
> when answering the third question for people to simply repeat what was
> said in response to an earlier question.

Certainly, a diagnostic questionnaire can always be improved.
Unfortunately I do not have a better wording to offer here to reduce
that sense of repetition.

Thanks for your response.

Re: [PATCH 2/2] bugreport: add a mark to each proposed questions

[Kristoffer Haugsbakk]

On Sat, Mar 23, 2024, at 18:36, Rubén Justo wrote:
> Include a mark in the questions we provide, to enhance the readability
> of the reports we receive.
>
> Of course, the user has the flexibility to choose a different format or
> rewrite the report entirely.  However, including these marks in the
> template may suggest that we value some structure in the message.
>
> Signed-off-by: Rubén Justo <rjusto@gmail.com>

I like this. The questions and the answers not being differentiated
makes things harder to read.

Re: [PATCH 2/2] bugreport: add a mark to each proposed questions

[Rubén Justo]

On 1/4/24 21:30, Kristoffer Haugsbakk wrote:
> On Sat, Mar 23, 2024, at 18:36, Rubén Justo wrote:
>> Include a mark in the questions we provide, to enhance the readability
>> of the reports we receive.
>>
>> Of course, the user has the flexibility to choose a different format or
>> rewrite the report entirely.  However, including these marks in the
>> template may suggest that we value some structure in the message.
>>
>> Signed-off-by: Rubén Justo <rjusto@gmail.com>
> 
> I like this. The questions and the answers not being differentiated
> makes things harder to read.

Thanks for your response.