[git-scm.com PATCH] community: advertise 'git-bugreport' tool

[git-scm.com PATCH] community: advertise 'git-bugreport' tool

[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 <emilyshaffer@google.com>
---

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(-)

diff --git a/app/views/community/index.html.erb b/app/views/community/index.html.erb
index 6927e19..bfcb089 100644
--- a/app/views/community/index.html.erb
+++ b/app/views/community/index.html.erb
@@ -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>
diff --git a/app/views/shared/ref/_debugging.html.erb b/app/views/shared/ref/_debugging.html.erb
index 286a690..4732b75 100644
--- a/app/views/shared/ref/_debugging.html.erb
+++ b/app/views/shared/ref/_debugging.html.erb
@@ -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>
-- 
2.27.0.rc0.183.gde8f92d652-goog

Re: [git-scm.com PATCH] community: advertise 'git-bugreport' tool

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

>    <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>.

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.

Re: [git-scm.com PATCH] community: advertise 'git-bugreport' tool

[Emily Shaffer]

On Thu, May 28, 2020 at 04:33:16PM -0700, Junio C Hamano wrote:
> 
> Emily Shaffer <emilyshaffer@google.com> writes:
> 
> >    <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>.
> 
> 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

Re: [git-scm.com PATCH] community: advertise 'git-bugreport' tool

[Jonathan Nieder]

Emily Shaffer wrote:

> 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 <emilyshaffer@google.com>
> ---
>  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.

> --- a/app/views/shared/ref/_debugging.html.erb
> +++ b/app/views/shared/ref/_debugging.html.erb
> @@ -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

Re: [git-scm.com PATCH] community: advertise 'git-bugreport' tool

[Philippe Blain]

Hi Emily,

> Le 28 mai 2020 à 19:16, Emily Shaffer <emilyshaffer@google.com> a écrit :
> 
> 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 <emilyshaffer@google.com>
> ---
> 
> 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.

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.

Re: [git-scm.com PATCH] community: advertise 'git-bugreport' tool

[Jeff King]

On Thu, May 28, 2020 at 05:27:57PM -0700, Jonathan Nieder wrote:

> > --- a/app/views/shared/ref/_debugging.html.erb
> > +++ b/app/views/shared/ref/_debugging.html.erb
> > @@ -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?

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

  https://git-scm.com/docs

in the section "debugging".

> 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

Re: [git-scm.com PATCH] community: advertise 'git-bugreport' tool

[Jeff King]

On Thu, May 28, 2020 at 09:49:51PM -0400, Philippe Blain wrote:

> > 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

Re: [git-scm.com PATCH] community: advertise 'git-bugreport' tool

[Jeff King]

On Thu, May 28, 2020 at 04:16:08PM -0700, Emily Shaffer wrote:

> 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.

> diff --git a/app/views/community/index.html.erb b/app/views/community/index.html.erb
> index 6927e19..bfcb089 100644
> --- a/app/views/community/index.html.erb
> +++ b/app/views/community/index.html.erb
> @@ -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