# [PATCH 0/2] improve bugreports 9 messages from 2024-03-23 to 2024-04-01. Participants: Rubén Justo, Eric Sunshine, Junio C Hamano, Kristoffer Haugsbakk. Thread: https://gitlist.dev/t/61188 ## Rubén Justo, 2024-03-23 17:32 Subject: [PATCH 0/2] improve bugreports Message-ID: <35de2d76-a03e-4a36-9bb7-6b6ffa4ea123@gmail.com> URL: https://gitlist.dev/e/35de2d76-a03e-4a36-9bb7-6b6ffa4ea123%40gmail.com ``` 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 ``` ## Rubén Justo, 2024-03-23 17:36 Subject: [PATCH 1/2] bugreport: add a new line between questions Message-ID: URL: https://gitlist.dev/e/bf1b2aef-2d8f-4b24-be2a-1a312f9f9f01%40gmail.com In-Reply-To: <35de2d76-a03e-4a36-9bb7-6b6ffa4ea123@gmail.com> ``` 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 --- 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 ``` ## Rubén Justo, 2024-03-23 17:36 Subject: [PATCH 2/2] bugreport: add a mark to each proposed questions Message-ID: <1117b5b1-fb9e-49b8-b1c3-47b985adce35@gmail.com> URL: https://gitlist.dev/e/1117b5b1-fb9e-49b8-b1c3-47b985adce35%40gmail.com In-Reply-To: <35de2d76-a03e-4a36-9bb7-6b6ffa4ea123@gmail.com> ``` 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 --- 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 ``` ## Rubén Justo, 2024-03-31 07:04 Subject: Re: [PATCH 0/2] improve bugreports Message-ID: <4f179986-6aca-405a-a122-d0dc058c60d8@gmail.com> URL: https://gitlist.dev/e/4f179986-6aca-405a-a122-d0dc058c60d8%40gmail.com In-Reply-To: <35de2d76-a03e-4a36-9bb7-6b6ffa4ea123@gmail.com> ``` 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. ``` ## Eric Sunshine, 2024-04-01 03:09 Subject: Re: [PATCH 0/2] improve bugreports Message-ID: URL: https://gitlist.dev/e/CAPig%2BcRFqddMqTxCENnknv3Agcq3_bxGmB1sQTmJNb%3DxNYg1aw%40mail.gmail.com In-Reply-To: <4f179986-6aca-405a-a122-d0dc058c60d8@gmail.com> ``` On Sun, Mar 31, 2024 at 3:04 AM Rubén Justo 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. ``` ## Junio C Hamano, 2024-04-01 09:29 Subject: Re: [PATCH 0/2] improve bugreports Message-ID: URL: https://gitlist.dev/e/xmqq5xx1e8hx.fsf%40gitster.g In-Reply-To: ``` Eric Sunshine 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. ``` ## Rubén Justo, 2024-04-01 19:27 Subject: Re: [PATCH 0/2] improve bugreports Message-ID: <5acafee5-dd65-49f1-bc2d-f959ed4bc9e1@gmail.com> URL: https://gitlist.dev/e/5acafee5-dd65-49f1-bc2d-f959ed4bc9e1%40gmail.com In-Reply-To: ``` 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 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. ``` ## Kristoffer Haugsbakk, 2024-04-01 19:30 Subject: Re: [PATCH 2/2] bugreport: add a mark to each proposed questions Message-ID: URL: https://gitlist.dev/e/bb4cd824-c9ca-4adb-8339-885273aed9bc%40app.fastmail.com In-Reply-To: <1117b5b1-fb9e-49b8-b1c3-47b985adce35@gmail.com> ``` 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 I like this. The questions and the answers not being differentiated makes things harder to read. ``` ## Rubén Justo, 2024-04-01 19:33 Subject: Re: [PATCH 2/2] bugreport: add a mark to each proposed questions Message-ID: <85769d41-e0b8-4f68-b709-511e97c82c37@gmail.com> URL: https://gitlist.dev/e/85769d41-e0b8-4f68-b709-511e97c82c37%40gmail.com In-Reply-To: ``` 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 > > I like this. The questions and the answers not being differentiated > makes things harder to read. Thanks for your response. ```