[PATCH] docs: update contributing guide to refer current bugs and feature requests

[PATCH] docs: update contributing guide to refer current bugs and feature requests

[Rhythm Narula via GitGitGadget]

From: Rhythm-26 <rhythm.narula26@gmail.com>

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.

CC: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Rhythm-26 <rhythm.narula26@gmail.com>
---
    docs: updates MyFirstContribution guide to refer current bugs and
    feature requests

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1867%2FRhythm-26%2FupdateContirbutingDocumentation-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1867/Rhythm-26/updateContirbutingDocumentation-v1
Pull-Request: https://github.com/git/git/pull/1867

 Documentation/MyFirstContribution.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index e41654c00a6..3b26a5265b2 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -109,6 +109,14 @@ 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: git+subscribe@vger.kernel.org
+
+Here's where you can find bugs and feature requests existing in the system:
+
+ - 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/
+ - Unofficial bug trackers - https://github.com/gitgitgadget/git/issues, https://git.issues.gerritcodereview.com/
+
 [[setup-workspace]]
 === Set Up Your Workspace
 

base-commit: 1b4e9a5f8b5f048972c21fe8acafe0404096f694
-- 
gitgitgadget

Re: [PATCH] docs: update contributing guide to refer current bugs and feature requests

[Carlo Marcelo Arenas Belón]

On Sun, Jan 05, 2025 at 12:35:17PM -0800, Rhythm Narula via GitGitGadget wrote:
> From: Rhythm-26 <rhythm.narula26@gmail.com>
> 
> 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.

The commit message (as described in `Documentation/SubmittingPatches`)
should explain the problem in the codebase and then describe (in imperative
mode) how the patch proposes to fix it.

Subject line is also meant to be very short so maybe somethihg like:

  docs: mention source of tasks in MyFirstContribution

> +:mailinglist: git+subscribe@vger.kernel.org
> +
> +Here's where you can find bugs and feature requests existing in the system:

mentioning bugs with quotes might be a good idea, considering that GGG
(your first link below) specifically mentions that only feature requests
should be filed there.

something that encourages people to use the mailing list for reports and
discussion probably worth adding as well.


> + - Unofficial bug trackers - https://github.com/gitgitgadget/git/issues, https://git.issues.gerritcodereview.com/

see #1432

Carlo

CC: +Emily as the original authour of "MyFirstContribution" for feedback

Re: [PATCH] docs: update contributing guide to refer current bugs and feature requests

[Emily Shaffer]

On Sun, Jan 5, 2025 at 4:35 AM Rhythm Narula via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Rhythm-26 <rhythm.narula26@gmail.com>
>
> 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.
>
> CC: Johannes Schindelin <johannes.schindelin@gmx.de>
> Signed-off-by: Rhythm-26 <rhythm.narula26@gmail.com>
> ---
>     docs: updates MyFirstContribution guide to refer current bugs and
>     feature requests
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1867%2FRhythm-26%2FupdateContirbutingDocumentation-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1867/Rhythm-26/updateContirbutingDocumentation-v1
> Pull-Request: https://github.com/git/git/pull/1867
>
>  Documentation/MyFirstContribution.txt | 8 ++++++++
>  1 file changed, 8 insertions(+)
>
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index e41654c00a6..3b26a5265b2 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -109,6 +109,14 @@ 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: git+subscribe@vger.kernel.org

What's the purpose of adding this attribute? Did you mean to use it to
linkify "mailing list" in the first bullet below? Note that the
mailing list and how to subscribe to it is also described above under
"Getting Help", maybe it makes more sense to refer back to that
header...? Not sure.

> +
> +Here's where you can find bugs and feature requests existing in the system:

I like the placement. The patch context doesn't make it super clear,
but this is sitting at the end of the "Identify a Problem to Solve"
step, so it's handy if folks are still following along in this guide
on their first couple of real patches until they build muscle memory
:) Initially I had thought this might make more sense to sit at the
end of the tutorial, as a sort of "what do I do next?", but I think
this placement is very good too.

> +
> + - 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/
> + - Unofficial bug trackers - https://github.com/gitgitgadget/git/issues, https://git.issues.gerritcodereview.com/
> +



It could be nice to say something like "For next time, here's where
you can find..." but I don't think it's necessary - my personal taste
just thinks it could flow better.

Nice idea, though. With a couple tweaks I'd like to see it land.
Thanks for sending the patch.
 - Emily

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

[Rhythm Narula via GitGitGadget]

From: Rhythm-26 <rhythm.narula26@gmail.com>

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 <johannes.schindelin@gmx.de>
Signed-off-by: Rhythm-26 <rhythm.narula26@gmail.com>
---
    docs: updates MyFirstContribution guide to refer current bugs and
    feature requests
    
    cc: Carlo Marcelo Arenas Belón carenas@gmail.com cc: Emily Shaffer
    nasamuffin@google.com

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1867%2FRhythm-26%2FupdateContirbutingDocumentation-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1867/Rhythm-26/updateContirbutingDocumentation-v2
Pull-Request: https://github.com/git/git/pull/1867

Range-diff vs v1:

 1:  d3e264b1cc5 ! 1:  d1e83439133 docs: update contributing guide to refer current bugs and feature requests
     @@ Metadata
      Author: Rhythm-26 <rhythm.narula26@gmail.com>
      
       ## Commit message ##
     -    docs: update contributing guide to refer current bugs and feature requests
     +    docs: mention source of tasks in MyFirstContribution
      
     -    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.
      
          CC: Johannes Schindelin <johannes.schindelin@gmx.de>
          Signed-off-by: Rhythm-26 <rhythm.narula26@gmail.com>
     @@ Documentation/MyFirstContribution.txt: of invocation during users' typical daily
       
      +:mailinglist: git+subscribe@vger.kernel.org
      +
     -+Here's where you can find bugs and feature requests existing in the system:
     ++For future reference, here's where you can find bugs and feature requests existing in the system:
      +
      + - 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/
     -+ - Unofficial bug trackers - https://github.com/gitgitgadget/git/issues, https://git.issues.gerritcodereview.com/
     ++   like #leftoverbits in the archives: https://lore.kernel.org/git/. 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.
     ++ - Unofficial bug trackers - https://github.com/gitgitgadget/git/issues [NOTE: This is for feature requests only],
     ++   https://git.issues.gerritcodereview.com/
      +
       [[setup-workspace]]
       === Set Up Your Workspace


 Documentation/MyFirstContribution.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

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: git+subscribe@vger.kernel.org
+
+For future reference, here's where you can find bugs and feature requests existing in the system:
+
+ - 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/. 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.
+ - Unofficial bug trackers - https://github.com/gitgitgadget/git/issues [NOTE: This is for feature requests only],
+   https://git.issues.gerritcodereview.com/
+
 [[setup-workspace]]
 === Set Up Your Workspace
 

base-commit: 1b4e9a5f8b5f048972c21fe8acafe0404096f694
-- 
gitgitgadget

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

[Junio C Hamano]

"Rhythm Narula via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Rhythm-26 <rhythm.narula26@gmail.com>
>
> 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 <johannes.schindelin@gmx.de>
> Signed-off-by: Rhythm-26 <rhythm.narula26@gmail.com>
> ---
>     docs: updates MyFirstContribution guide to refer current bugs and
>     feature requests
>     
>     cc: Carlo Marcelo Arenas Belón carenas@gmail.com cc: Emily Shaffer
>     nasamuffin@google.com

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: git+subscribe@vger.kernel.org

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=ed0GOkhx7w0PhVc2FmcbVL6jWQ@mail.gmail.com/


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.