Re: [PATCH v2] docs: mention source of tasks in MyFirstContribution
"Rhythm Narula via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 14 quoted lines
> 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
Show 8 quoted lines
>
> - 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.
Show 9 quoted lines
> 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.
Rhythm Narula via GitGitGadget
