[PATCH] docs: suggest "Helped-by" rather than "Thanks-to"

[PATCH] docs: suggest "Helped-by" rather than "Thanks-to"

[Adam Dinwoodie]

The SubmittingPatches doc suggests adding "tags" in the style of
"Signed-off-by" to commit messages, and suggests some in common usage.
However, based on usage on the Git mailing list (and in particular,
Junio C Hamano's email to René Genz on 23 April), the suggested
"Thanks-to" is not common usage, and should instead be "Helped-by".

Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 558d465b6..2de42b3fa 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -319,7 +319,7 @@ If you like, you can put extra tags at the end:
    and found it to have the desired effect.
 
 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 "Helped-by:", "Based-on-patch-by:", or "Mentored-by:".
 
 ------------------------------------------------
 Subsystems with dedicated maintainers
-- 
2.12.3

Re: [PATCH] docs: suggest "Helped-by" rather than "Thanks-to"

[Stefan Beller]

On Mon, Jun 5, 2017 at 3:53 AM, Adam Dinwoodie <adam@dinwoodie.org> wrote:
> The SubmittingPatches doc suggests adding "tags" in the style of
> "Signed-off-by" to commit messages, and suggests some in common usage.
> However, based on usage on the Git mailing list (and in particular,
> Junio C Hamano's email to René Genz on 23 April), the suggested
> "Thanks-to" is not common usage, and should instead be "Helped-by".
>

One data point is sure nice (and it matches my perception),
but can we do data at project scale?

The quickest hack I could come up with is

  $ git log |grep Thanks-to |wc -l
  57
  $ git log |grep Helped-by |wc -l
  676

which reinforces the underlying data.

--
So I was wondering if there is a command that shows all trailers?
Similar to a "shortlog -sne" I would want to have a list of all trailers.
This is because there might be an even more popular trailer than
"Helped-by", but we would not know when using the hack above.

While I do not think so, it would sure be interesting to have a list
of all these trailers available.

Thanks,
Stefan

Re: [PATCH] docs: suggest "Helped-by" rather than "Thanks-to"

[Adam Dinwoodie]

On Mon, Jun 05, 2017 at 11:42:31AM -0700, Stefan Beller wrote:
> So I was wondering if there is a command that shows all trailers?
> Similar to a "shortlog -sne" I would want to have a list of all trailers.
> This is because there might be an even more popular trailer than
> "Helped-by", but we would not know when using the hack above.
> 
> While I do not think so, it would sure be interesting to have a list
> of all these trailers available.

I just did a quick search with the following knocked-together command:

    git log --remotes --format=format:%B | sed -rn 's/^([A-Za-z0-9-]+): .* <.*@.*>.*/\1/p' | sort | uniq -c | sort -nr

The top 10 such tags according to this (which is coincidentally the same
list as the list of all tags used more than 100 times), with
frequencies, are:

  61535 Signed-off-by
   1641 Acked-by
    984 Reviewed-by
    673 Helped-by
    497 Reported-by
    180 Cc
    174 Suggested-by
    159 Tested-by
    158 Mentored-by
    128 Noticed-by

As you might expect, there are a number of entertaining ones that have
only been used once or twice, such as "Looks-fine-to-me-by",
"Worriedly-Acked-by", "More-Spots-Found-By", "Looks-right-to-me-by",
"Hopefully-signed-off-by"...

Re: [PATCH] docs: suggest "Helped-by" rather than "Thanks-to"

[Junio C Hamano]

Adam Dinwoodie <adam@dinwoodie.org> writes:

> On Mon, Jun 05, 2017 at 11:42:31AM -0700, Stefan Beller wrote:
>> So I was wondering if there is a command that shows all trailers?
>> Similar to a "shortlog -sne" I would want to have a list of all trailers.
>> This is because there might be an even more popular trailer than
>> "Helped-by", but we would not know when using the hack above.
>> 
>> While I do not think so, it would sure be interesting to have a list
>> of all these trailers available.
>
> I just did a quick search with the following knocked-together command:
>
>     git log --remotes --format=format:%B | sed -rn 's/^([A-Za-z0-9-]+): .* <.*@.*>.*/\1/p' | sort | uniq -c | sort -nr
>
> The top 10 such tags according to this (which is coincidentally the same
> list as the list of all tags used more than 100 times), with
> frequencies, are:
>
>   61535 Signed-off-by
>    1641 Acked-by
>     984 Reviewed-by
>     673 Helped-by
>     497 Reported-by
>     180 Cc
>     174 Suggested-by
>     159 Tested-by
>     158 Mentored-by
>     128 Noticed-by
>
> As you might expect, there are a number of entertaining ones that have
> only been used once or twice, such as "Looks-fine-to-me-by",
> "Worriedly-Acked-by", "More-Spots-Found-By", "Looks-right-to-me-by",
> "Hopefully-signed-off-by"...

Thanks for an interesting list.  Your replacing (totally
unconventional) Thanks-to with more common Helped-by is certainly an
improvement, but I wonder if we should encourage people to be
"original" in this area by having that "You can also invent"
paragraph in the first place.

Re: [PATCH] docs: suggest "Helped-by" rather than "Thanks-to"

[Adam Dinwoodie]

(Resending to everyone after only sending to Junio by mistake.)

On Wed, Jun 07, 2017 at 08:44:08AM +0900, Junio C Hamano wrote:
> Adam Dinwoodie <adam@dinwoodie.org> writes:
> 
> > On Mon, Jun 05, 2017 at 11:42:31AM -0700, Stefan Beller wrote:
> >> So I was wondering if there is a command that shows all trailers?
> >> Similar to a "shortlog -sne" I would want to have a list of all trailers.
> >> This is because there might be an even more popular trailer than
> >> "Helped-by", but we would not know when using the hack above.
> >> 
> >> While I do not think so, it would sure be interesting to have a list
> >> of all these trailers available.
> >
> > I just did a quick search with the following knocked-together command:
> >
> >     git log --remotes --format=format:%B | sed -rn 's/^([A-Za-z0-9-]+): .* <.*@.*>.*/\1/p' | sort | uniq -c | sort -nr
> >
> > The top 10 such tags according to this (which is coincidentally the same
> > list as the list of all tags used more than 100 times), with
> > frequencies, are:
> >
> >   61535 Signed-off-by
> >    1641 Acked-by
> >     984 Reviewed-by
> >     673 Helped-by
> >     497 Reported-by
> >     180 Cc
> >     174 Suggested-by
> >     159 Tested-by
> >     158 Mentored-by
> >     128 Noticed-by
> >
> > As you might expect, there are a number of entertaining ones that have
> > only been used once or twice, such as "Looks-fine-to-me-by",
> > "Worriedly-Acked-by", "More-Spots-Found-By", "Looks-right-to-me-by",
> > "Hopefully-signed-off-by"...
> 
> Thanks for an interesting list.  Your replacing (totally
> unconventional) Thanks-to with more common Helped-by is certainly an
> improvement, but I wonder if we should encourage people to be
> "original" in this area by having that "You can also invent"
> paragraph in the first place.

I would expect we could never come up with a list that will cover every
possible scenario. I suppose the question is whether it's worse for
people to feel like it's encouraged to come up with non-standard options
or for them to feel they can't deviate from a given list if none of the
available options suits them.

And I definitely don't feel I have a good enough grasp of what these
lines are used for in practice to make any sort of informed comment, so
I shall leave it to people with more experience than I to propose the
patch or not.

Re: [PATCH] docs: suggest "Helped-by" rather than "Thanks-to"

[Junio C Hamano]

Adam Dinwoodie <adam@dinwoodie.org> writes:

>> Thanks for an interesting list.  Your replacing (totally
>> unconventional) Thanks-to with more common Helped-by is certainly an
>> improvement, but I wonder if we should encourage people to be
>> "original" in this area by having that "You can also invent"
>> paragraph in the first place.
>
> I would expect we could never come up with a list that will cover every
> possible scenario. I suppose the question is whether it's worse for
> people to feel like it's encouraged to come up with non-standard options
> or for them to feel they can't deviate from a given list if none of the
> available options suits them.

I do not think we want to even aim for a canonical "this is the ones
you must choose from" in the first place.  I felt that the current
text overly encourages to be "creative" there.  I am wondering if an
update like this, that explicitly says that "Helped-by:" is the
catch all for other kinds of help, would be sufficient?

 Documentation/SubmittingPatches | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 558d465b65..b49372b875 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -305,7 +305,8 @@ the change to its true author (see (2) above).
 Also notice that a real name is used in the Signed-off-by: line. Please
 don't hide your real name.
 
-If you like, you can put extra tags at the end:
+If you like, you can put extra tags at the end.  Here are the ones
+that are commonly used in this project:
 
 1. "Reported-by:" is used to credit someone who found the bug that
    the patch attempts to fix.
@@ -317,9 +318,11 @@ If you like, you can put extra tags at the end:
    detailed review.
 4. "Tested-by:" is used to indicate that the person applied the patch
    and found it to have the desired effect.
-
-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:".
+5. "Mentored-by:" is often used by new contributors to give credits to
+   a more experienced member of the list after privately getting help
+   polishing the patches from, before showing the patch to the list.
+6. "Helped-by:" is used to give credit to others involved in the
+   discussion of the patch in other meaningful ways.
 
 ------------------------------------------------
 Subsystems with dedicated maintainers