To add to what Phillip said... On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood <phillip.wood123@xxxxxxxxx> wrote: > > Hi Josh > > On 19/12/2023 08:41, Josh Soref via GitGitGadget wrote: > > From: Josh Soref <jsoref@xxxxxxxxx> > > > > 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. Same. > > 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. > > . `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. Yes; I'd like for these to be distinguished in this way or something similar. > > +. `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.
