Subject: Re: [PATCH v2] docs: mention source of tasks in MyFirstContribution

From: Junio C Hamano <[email-masked]>
Date: Tue, 14 Jan 2025 09:24:13 -0800

"Rhythm Narula via GitGitGadget" <[email-masked]> writes:

> From: Rhythm-26 <[email-masked]>
>
> MyFirstContribution guide lacks clear guidance on where to access
> list of bugs or feature requests. Improve visibility for contributors
> on where to find open issues and features that need attention.
>
> CC: Johannes Schindelin <[email-masked]>
> Signed-off-by: Rhythm-26 <[email-masked]>
> ---
>     docs: updates MyFirstContribution guide to refer current bugs and
>     feature requests
>     
>     cc: Carlo Marcelo Arenas Belón [email-masked] cc: Emily Shaffer
>     [email-masked]

Let me remind you of Documentation/SubmittingPatches[[real-name]],
in case your name is not "26".  We want to see "From:" (you used
Gitgitgadget, and it placed an in-body "From:" at the beginning of
the message, which is expected---there is a name there and we want
it to match the name used on the "Signed-off-by:" line below) and
"Signed-off-by:" use the same name that we can say, when the court
asks if we stole a part of this software from somebody else, "no,
we didn't steal it. this person (with his or her real name) sent a
contribution to us and here is our record".

>      -    docs: update contributing guide to refer current bugs and feature requests
>      +    docs: mention source of tasks in MyFirstContribution

Nice.

>       
>      -    The contributing guide is updated to include references to the current
>      -    open bugs and feature requests. This update aims to improve visibility
>      -    for contributors on where to find open issues and features that need
>      -    attention.
>      +    MyFirstContribution guide lacks clear guidance on where to access
>      +    list of bugs or feature requests. Improve visibility for contributors
>      +    on where to find open issues and features that need attention.

"MyFirstContribution guide" -> "MyFirstContribution" would be
sufficient; it also allows us to avoid "guide ... guidance"
duplication.

If I were writing it, I would also do "access list of" -> "find
unresolved".  We do not have "the official and curated list of bugs
and feature requests", so such a thing by definition cannot be
accessed.

> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index e41654c00a6..630a68b650c 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -109,6 +109,16 @@ of invocation during users' typical daily workflow.
>  (We've seen some other effort in this space with the implementation of popular
>  commands such as `sl`.)
>  
> +:mailinglist: [email-masked]

I recall seeing that Emily asked about this line and do not remember
ever seeing an answer to it.

https://lore.kernel.org/git/CAJoAoZmzLOMNCNP-X-=QTSb=[email-masked]/

The paragraph below is overly wide.  Please make sure that the
resulting document _before_ passing AsciiDoc can comfortably be read
on 80-column terminals.  We usually try to limit the line width to a
tad shorter than that limit, because we review via e-mail ...

> +For future reference, here's where you can find bugs and feature requests existing in the system:

... and quoted lines will be indented to lose a handful of columns
on the left edge.  From here on, I'll liberally fold your original
before commenting.

> For future reference, here's where you can find bugs and feature
> requests existing in the system:

It is a bit funny to phrase requests to "exist in the system".  It
is still outside of the system and that is why they are requests.

Since this is the "my first *contribution*" document, phrasing it
more like "unresolved bugs and feature requests you can work on"
would fit the purpose of the doucment better, perhaps?

    If you are interested, here are a few ways to find unresolved
    bugs and feature requests you can work on:

or something like that.

> - Git uses a mailing list for discussion on bugs, features and
>   patches. Search for relevant topics or tagged issues like
>   #leftoverbits in the archives: https://lore.kernel.org/git/.

I am of two minds about #leftoverbits.  It certainly is an easy way
to leave notes for later investigation for writers, and it is an
easy way to find them later when somebody is bored enough to find
things to work on.  On the mailing list, however, anybody can say
anything [*], so an ancient uttering made by somebody with the
"#leftoverbits" mark may just be a feature request that turned out
not make sense at all.

>   If
>   you encounter a bug, have a feature request, or wish to discuss or
>   share suggestions, please use the mailing list. You can find more
>   details in the <<getting-help>> section.

This is great.  We should also suggest "search the list archive for
similar issues", but that needs to be phrased with finesse, because
it probably is not useful use of potential contributor's time [*]
and may raise the bar to report potential issues if we require it.

Making it entirely optional, but still encouraging, to dig in the
archive, here is what I came up with, but it is overly long.  If
somebody agrees with the direction, we need to spend time to make it
more concise:

    You may find a bug or have a feature request.  Since Git has a
    huge user base, it is not all that unlikely that somebody else
    has already encountered the same bug.  Looking for similar
    reports on the mailing list may even find that the bug has
    already been fixed.

    But looking for similar bugs and feature requests on the mailing
    list take certain spelunking skills; do not be afraid of sending
    a bug report that turns out to be a duplicate.  If somebody
    recently worked on the same bug or a similar new feature, they
    may respond a lot faster than you can dig recent exchanges out
    of the list archive (in other words, inadvertent duplicate
    reports are encouraged).

> - Unofficial bug trackers 
>   - https://github.com/gitgitgadget/git/issues [NOTE: This is for
>     feature requests only]
>   - https://git.issues.gerritcodereview.com/

OK.

Thanks.

[Footnotes]

* Of course, community guidelines apply and rude folks may be kicked
  out, but it should be clear that I am not talking about that kind
  of "can say anything" in the context of this message ;-).

* But if we say that, a new question "is it worth the time for
  established community members to do the list search for them,
  then?" arises (and the answer is usually "No").  But if somebody
  already knows that a similar issue was reported, or better yet,
  that the issue has already been resolved, then exposing the
  duplicate issue this new person found to the list and let the
  duplicate report noticed by that somebody would be an overall win.