Skip to contentSkip to conversation

community: advertise 'git-bugreport' tool

PATCH In review Emily Shaffer 5 participants 8 messages May 28, 2020 – May 29, 2020

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 community: advertise 'git-bugreport' tool

Starting with 2.27.0, 'git bugreport' can gather diagnostic info and drop the user into an editor with a template for a useful bugreport. Advertise this feature to users who want to report a bug in Git.

---

Hi all,

Since this patch deals with some prominent information about how to contact the community, I figured it was worth passing through the list for feedback rather than just sending a PR to the website repo. Discussion prior to this patch here:
https://github.com/git/git-scm.com/issues/1464

In the index.html.erb diff I'm interested in wordsmithing feedback; this is the page which appears at https://git-scm.com/community. The diff in _debugging.html.erb is modifying the list of references in
https://git-scm.com/docs - I'm interested in feedback on whether this is the best header to include git-bugreport under.

Thanks and sorry for the off-repo noise.

- Emily

 app/views/community/index.html.erb       | 11 +++++++----
 app/views/shared/ref/_debugging.html.erb |  1 +
 2 files changed, 8 insertions(+), 4 deletions(-)
app/views/community/index.html.erb +7 -4
index 6927e19..bfcb089 100644
@@ -36,10 +36,13 @@
 
   <p>
     Bugs in git can be reported directly to the mailing list (see above for
-    details). Note that you do not need to subscribe to the list to send
-    to it. You can help us out by attempting to reproduce the bug in the latest
-    released version of git, or if you're willing to build git from source, the
-    <a href="https://github.com/git/git/tree/next"><code>next</code> branch</a>.
+    details). Note that you do not need to subscribe to the list to send to it.
+    If you are using git 2.27.0 or later, you can run <code>git bugreport</code>,
+    which generates a template to guide you through writing a useful bug report
+    and gathers some diagnostic information about your environment. You can
+    help us out by attempting to reproduce the bug in the latest released
+    version of git, or if you're willing to build git from source, the
+    <a href="https:/break/github.com/git/git/tree/next"><code>next</code> branch</a>.
     Sometimes an attempted fix may be pending in this branch, in which case
     your feedback as to whether the fix worked for you will be appreciated.
   </p>
app/views/shared/ref/_debugging.html.erb +1 -0
index 286a690..4732b75 100644
@@ -2,5 +2,6 @@
 <ul class='unstyled'>
   <li><%= man('git-bisect') %></li>
   <li><%= man('git-blame') %></li>
+  <li><%= man('git-bugreport') %></li>
   <li><%= man('git-grep') %></li>
 </ul>
Signature · 1 line
2.27.0.rc0.183.gde8f92d652-goog
#1 lore raw

app/views/community/index.html.erb line 45

Quoted 13 lines · Emily Shaffer

<p>
Bugs in git can be reported directly to the mailing list (see above for

app/views/community/index.html.erb +7 -4
-    details). Note that you do not need to subscribe to the list to send
-    to it. You can help us out by attempting to reproduce the bug in the latest
-    released version of git, or if you're willing to build git from source, the
-    <a href="https://github.com/git/git/tree/next"><code>next</code> branch</a>.
+    details). Note that you do not need to subscribe to the list to send to it.
+    If you are using git 2.27.0 or later, you can run <code>git bugreport</code>,
+    which generates a template to guide you through writing a useful bug report
+    and gathers some diagnostic information about your environment. You can
+    help us out by attempting to reproduce the bug in the latest released
+    version of git, or if you're willing to build git from source, the
+    <a href="https:/break/github.com/git/git/tree/next"><code>next</code> branch</a>.

It took me a bit more then necessary to spot this due to rewrapping of the string, but I do not think you meant "https:/break/" there.

Care to share how it happened (what tool has the tendency to introduce this particular breakage)?

Thanks.

#2 lore raw
Quoted 17 lines · Junio C Hamano

app/views/community/index.html.erb line 45

Quoted 13 lines · Emily Shaffer

<p>
Bugs in git can be reported directly to the mailing list (see above for

app/views/community/index.html.erb +7 -4
-    details). Note that you do not need to subscribe to the list to send
-    to it. You can help us out by attempting to reproduce the bug in the latest
-    released version of git, or if you're willing to build git from source, the
-    <a href="https://github.com/git/git/tree/next"><code>next</code> branch</a>.
+    details). Note that you do not need to subscribe to the list to send to it.
+    If you are using git 2.27.0 or later, you can run <code>git bugreport</code>,
+    which generates a template to guide you through writing a useful bug report
+    and gathers some diagnostic information about your environment. You can
+    help us out by attempting to reproduce the bug in the latest released
+    version of git, or if you're willing to build git from source, the
+    <a href="https:/break/github.com/git/git/tree/next"><code>next</code> branch</a>.
Quoted 5 lines

It took me a bit more then necessary to spot this due to rewrapping of the string, but I do not think you meant "https:/break/" there.

Care to share how it happened (what tool has the tendency to introduce this particular breakage)?

Yes, I noticed it late. I have no idea how it happened - I imagine I leaned on my touchpad (middle mouse paste) while typing or otherwise mashed some keys in Vim. In other words, the tool was me :) Have fixed it locally, thanks for spying it.

- Emily

#3 lore raw
In reply to Emily Shaffer
Quoted 7 lines · Emily Shaffer

Starting with 2.27.0, 'git bugreport' can gather diagnostic info and drop the user into an editor with a template for a useful bugreport. Advertise this feature to users who want to report a bug in Git.

---
 app/views/community/index.html.erb       | 11 +++++++----

Modulo the link issue that Junio mentioned, LGTM. I think the section on the page you chose is a good place to mention the command.

app/views/shared/ref/_debugging.html.erb line 7

Quoted 9 lines
app/views/shared/ref/_debugging.html.erb +1 -0
@@ -2,5 +2,6 @@
 <ul class='unstyled'>
   <li><%= man('git-bisect') %></li>
   <li><%= man('git-blame') %></li>
+  <li><%= man('git-bugreport') %></li>
   <li><%= man('git-grep') %></li>
 </ul>

Where does this show up on the rendered page? Is it
https://git-scm.com/book/en/v2/Appendix-C:-Git-Commands-Debugging?
Is there a way to preview how it renders?

That page appears to be about commands used to debug your own codebase, so for everyone except us Git developers, it's the wrong place to mention git bugreport. ;-)

Within the book, I think
https://git-scm.com/book/en/v2/Getting-Started-Getting-Help and the corresponding
https://git-scm.com/book/en/v2/Appendix-C%3A-Git-Commands-Setup-and-Config
page might make sense.

Thanks,
Jonathan

#4 lore raw
Quoted 4 lines · Jonathan Nieder
Quoted 4 lines
app/views/shared/ref/_debugging.html.erb +0 -0
@@ -2,5 +2,6 @@
 <ul class='unstyled'>
Quoted 8 lines

app/views/shared/ref/_debugging.html.erb line 7

Quoted 5 lines
app/views/shared/ref/_debugging.html.erb +1 -0
   <li><%= man('git-bisect') %></li>
   <li><%= man('git-blame') %></li>
+  <li><%= man('git-bugreport') %></li>
   <li><%= man('git-grep') %></li>
 </ul>

Where does this show up on the rendered page? Is it
https://git-scm.com/book/en/v2/Appendix-C:-Git-Commands-Debugging?

No, it's in the command-list in:

https://git-scm.com/docs

in the section "debugging".

Quoted 1 line

Is there a way to preview how it renders?

Yes. :) You can clone the repo and build using the instructions in the README (including importing at least one version's worth of manpages to render). It's a minor-ish pain to do so if you're not used to working with Ruby or Rails.

We also spin up a staging deploy for any PRs opened against that repo, though I _think_ it won't do so for PRs opened from another fork (since it can read the production database; we don't care for our project, which contains no secrets, but many projects would).

-Peff

#5 lore raw
In reply to Emily Shaffer

Hi Emily,

Quoted 17 lines · Emily Shaffer

Starting with 2.27.0, 'git bugreport' can gather diagnostic info and drop the user into an editor with a template for a useful bugreport. Advertise this feature to users who want to report a bug in Git.

---

Hi all,

Since this patch deals with some prominent information about how to contact the community, I figured it was worth passing through the list for feedback rather than just sending a PR to the website repo. Discussion prior to this patch here:
https://github.com/git/git-scm.com/issues/1464

Quoted 5 lines

In the index.html.erb diff I'm interested in wordsmithing feedback; this is the page which appears at https://git-scm.com/community. The diff in _debugging.html.erb is modifying the list of references in
https://git-scm.com/docs - I'm interested in feedback on whether this is the best header to include git-bugreport under.

I think maybe app/views/shared/ref/_setup.html.erb would be a better fit ? That's the section at the top of the page, with git, help and config, called "Setup and Config"...

The wording on the community page looks good.

Thanks,

Philippe.

#6 lore raw
Quoted 9 lines · Philippe Blain
Quoted 5 lines

In the index.html.erb diff I'm interested in wordsmithing feedback; this is the page which appears at https://git-scm.com/community. The diff in _debugging.html.erb is modifying the list of references in
https://git-scm.com/docs - I'm interested in feedback on whether this is the best header to include git-bugreport under.

I think maybe app/views/shared/ref/_setup.html.erb would be a better fit ? That's the section at the top of the page, with git, help and config, called "Setup and Config"...

Good suggestion. Most of "debugging" is about debugging your own code. And I think it's good to have this up near the top, where people are more likely to stumble into it while trying to figure out how to report a bug. :)

-Peff

#7 lore raw
In reply to Emily Shaffer
Quoted 5 lines · Emily Shaffer

Since this patch deals with some prominent information about how to contact the community, I figured it was worth passing through the list for feedback rather than just sending a PR to the website repo. Discussion prior to this patch here:
https://github.com/git/git-scm.com/issues/1464

Thanks for doing that. I'd echo my sentiment in that issue that if anybody from list community is interested in suggesting changes to the Community page, we're happy to take patches. The bug-reporting advice there has been slowly added over the years, and fresh eyes may produce useful insights.

Quoted 5 lines
app/views/community/index.html.erb +0 -0
index 6927e19..bfcb089 100644

app/views/community/index.html.erb line 40

Quoted 9 lines
app/views/community/index.html.erb +2 -4
@@ -36,10 +36,13 @@
 
   <p>
     Bugs in git can be reported directly to the mailing list (see above for
-    details). Note that you do not need to subscribe to the list to send
-    to it. You can help us out by attempting to reproduce the bug in the latest
-    released version of git, or if you're willing to build git from source, the
-    <a href="https://github.com/git/git/tree/next"><code>next</code> branch</a>.
+    details). Note that you do not need to subscribe to the list to send to it.
+    If you are using git 2.27.0 or later, you can run <code>git bugreport</code>,

Perhaps make this a link to /docs/git-bugreport? That's not active yet, but will be when we release v2.27 (scheduled for Monday). We could hold this patch until then.

Other than that, looks good to me, modulo the /break/ thing mentioned elsewhere.

-Peff