Re: [PATCH 4/8] SubmittingPatches: update extra tags list

[Phillip Wood <phillip.wood123@gmail.com>]

Hi Josh

On 19/12/2023 08:41, Josh Soref via GitGitGadget wrote:
> From: Josh Soref <jsoref@gmail.com>
> 
> 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.

> Updating the create suggestion to something less commonly used.

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

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

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

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

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

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

Best Wishes

Phillip