To add to what Phillip said...

On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood [off-list ref] wrote:

Hi Josh

On 19/12/2023 08:41, Josh Soref via GitGitGadget wrote:

quoted

From: Josh Soref <redacted>

Add items with at least 100 uses:
- Co-authored-by
- Helped-by
- Mentored-by
- Suggested-by

Thanks for adding these, they are widely used and should be documented.
The patch also adds a mention for "Noticed-by:" - I'm less convinced by
the need for that as I explain below.

quoted

Updating the create suggestion to something less commonly used.

I'm not quite sure I understand what you mean by this sentence.

Same.

quoted

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 32e90238777..694a7bafb68 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches

@@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:

  . `Reported-by:` is used to credit someone who found the bug that
    the patch attempts to fix.
+. `Noticed-by:` liked `Reported-by:` indicates someone who noticed
+  the item being fixed.

I wonder if we really need a separate "Noticed-by" footer in addition to
"Reported-by". Personally I use the latter to acknowledge the person who
reported the issue being fix regards of weather I'm fixing a bug or some
other issue.

I'm not sure I'd mention both either; feels like we're making it hard
for users to choose.  Also, I think there's a minor distinction
between them, but it's hard to convey simply: To me, Reported-by
suggests someone sent a mail to the list specifically about the bug or
issue in question.  Also, to me, Noticed-by suggests that during a
back-and-forth discussion of some sort on another topic, a fellow Git
contributor noticed an issue and mentioned it as an aside.  But,
that's how _I_ would have used them, I didn't do any digging to find
out if that's really how they are used.

Either way, if we're going to define them as synonyms, I'd rather we
just left the less common one out.  If there's a distinction, and it's
not a pain to describe, then maybe it'd be worth adding both.

If we do add both, though, we at least need to fix "liked" to "like"
in your description.

quoted

  . `Acked-by:` says that the person who is more familiar with the area
    the patch attempts to modify liked the patch.
  . `Reviewed-by:`, unlike the other tags, can only be offered by the

@@ -355,9 +357,17 @@ If you like, you can put extra tags at the end:
    patch after a detailed analysis.
  . `Tested-by:` is used to indicate that the person applied the patch
    and found it to have the desired effect.
+. `Co-authored-by:` is used to indicate that multiple people
+  contributed to the work of a patch.

Junio's comments in [1] may be helpful here

     If co-authors closely worked together (possibly but not necessarily
     outside the public view), exchanging drafts and agreeing on the
     final version before sending it to the list, by one approving the
     other's final draft, Co-authored-by may be appropriate.

     I would prefer to see more use of Helped-by when suggestions for
     improvements were made, possibly but not necessarily in a concrete
     "squashable patch" form, the original author accepted before
     sending the new version out, and the party who made suggestions saw
     the updated version at the same time as the general public.

So I think we should be clear that "Co-authored-by:" means that multiple
authors worked closely together on the patch, rather than just
contributed to it.

[1] https://lore.kernel.org/git/xmqqmth8wwcf.fsf@gitster.g/ (local)

quoted

+. `Helped-by:` is used to credit someone with helping develop a
+  patch.
+. `Mentored-by:` is used to credit someone with helping develop a
+  patch.

I think we use "Montored-by:" specifically to credit the mentor on
patches written by GSoC or Outreachy interns and "Helped-by:" for the
general case of someone helping the patch author.

Yes; I'd like for these to be distinguished in this way or something similar.

quoted

+. `Suggested-by:` is used to credit someone with suggesting the idea
+  for a patch.

  You can also create your own tag or use one that's in common usage
-such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
+such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:".

What's the difference between "Improved-by:" and "Helped-by:"? In
general I'd prefer for us not to encourage new trailers where we already
have a suitable one in use.

Agreed.

Thanks for working on this, it will be good to have better descriptions
of our common trailers.

Agreed here as well; thanks for the work, Josh.