On Wed, Dec 20, 2023 at 8:09 AM Josh Soref <jsoref@xxxxxxxxx> wrote: > > On Wed, Dec 20, 2023 at 10:30 AM Elijah Newren <newren@xxxxxxxxx> wrote: > > On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood <phillip.wood123@xxxxxxxxx> wrote: > > > 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. > > Tentatively rewritten as: > Updating the "create your own tag" suggestion as 'Mentored-by' has been > promoted. > > This commit is adding bulleted items including promoting 'Mentored-by', > which means that the suggestion of "invent your own" would really need > a new suggestion. > > Personally I'm not a fan of "invent your own", but I'm trying to > follow "when in Rome" (which is a big thing in the Git process > documentation covered by the two files subject to this series). More > on this later. Yeah, well it appears that those of us who have been here in Rome for a while aren't a fan of it anymore either; see also Junio's response in this thread about that. > > > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > > > > index 32e90238777..694a7bafb68 100644 > > > > @@ -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. > > Given that Noticed-by is more common than Co-authored-by, I have a > hard time arguing that it shouldn't be included. Not if you look at the last three years; there Co-authored-by is more than 17 times more common than Noticed-by. > You could see that I struggled with it based on my lousy first drafts [1]. > > Anyway, tentatively: > > . `Noticed-by:` like `Reported-by:` indicates a Git contributor who > called the item (being fixed) out as an aside. > > Here, I'm struggling with the tension between "noticed-by probably > hints that something is being fixed" and "noticed-by is addressing who > suggested it and why we're attributing it to them" > > "as an aside" is itself an ellipsis for something like "as an aside to > some unrelated discussion and didn't really circle back to it as a top > level discussion point, but here we're closing the loop" -- but this > is obviously way too long-winded to be the written form Given the large drop-off in usage of the Noticed-by trailer, I'd suggest just leaving it out. > > 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. > > Right, it's a "first draft" [1]... :-) [...] > I personally agree. I think encouraging non-core contributors to > invent their own is not a good idea. It leads to various things > (including inconsistently cased items because users fail to review the > current set / understand them/their-construction). > > Saying that it's ok for core contributors to suggest a new tag and > that if a core contributor suggests a new tag that the person writing > the current series should just accept the tag and trust that it'll be > ok. > > Note: I'm not going to draft wording to this effect on my own, and if > I were to provide such a change, it'd be its own commit prior to the > one here, because it's a significant process change as opposed to > clarifying the list of recommended tags. Perhaps replace 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:". with While you can also create your own trailer if the situation warrants it, we encourage you to instead use one of the common trailers in this project highlighted above. ?
