community: advertise 'git-bugreport' tool
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
@@ -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
@@ -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
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 forapp/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.
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 forapp/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
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.
Signed-off-by Emily Shaffer <[email protected]>--- 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
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:
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
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.
Signed-off-by Emily Shaffer <[email protected]>---
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.
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.erbwould be a better fit ? That's the section at the top of the page, withgit,helpandconfig, 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
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
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