[PATCH v4] docs: clarify rules wrt tagging other people

[PATCH v4] docs: clarify rules wrt tagging other people

[Thorsten Leemhuis]

Point out that explicit permission is usually needed to tag other people
in changes, but mention that implicit permission can be sufficient in
certain cases. This fixes slight inconsistencies between Reported-by:
and Suggested-by: and makes the usage more intuitive.

While at it, explicitly mention the dangers of our bugzilla instance, as
it makes it easy to forget that email addresses visible there are only
shown to logged-in users.

The latter is not a theoretical issue, as one maintainer mentioned that
his employer received a EU GDPR (general data protection regulation)
complaint after exposing a email address used in bugzilla through a tag
in a patch description.

Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Simona Vetter <simona.vetter@ffwll.ch>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---

Jonathan, what do you think of this? I felt somewhat unsure about this a
few weeks ago, but I guess I was overly careful. If you think this
change is fine and shouldn't cause any trouble for anyone, feel free to
merge this. And if not, please speak up.

Note: this triggers a few checkpatch.pl complaints that are irrelevant
when when to comes to changes like this.

v4:
- slight wording change to make a implicity aspect explicit, as pointed
  out by Mauro
- Add reviewed-bys from Mauro and Shuah
- The number of reviewed-bys is still smal, nevertheless drop the
  DONOTMERGE and hole that Jonathan will speak up if he thinks this is
  a stupid move.

v3: https://lore.kernel.org/all/c29ef5fa12e37c3a289e46d4442b069af94e5b05.1733127212.git.linux@leemhuis.info/
- try yet again from a slightly different angle which loosens the rules
  slightly. This from review feedback to earlier versions is apparently
  what other developers want and from their "no lawyer" perspective
  consider to be okay. As IANAL myself I don't feel totally comfortable
  with this and have no idea if this legally is sound, so tag patch with
  "DONOTMERGE" for now; will remove this for v4 if enough people add a
  "Reviewed-by". Otherwise the story of this patch might end here, unless
  someone else submits it for inclusion (you are free to do so!).
- remote patch adding Suggested-by: tag to 5.Posting and submit it
  separately

v2: https://lore.kernel.org/all/cover.1731749544.git.linux@leemhuis.info/
- Retry differently. This slightly hardens the rule for Reported-by:
  while slightly lessening it for Suggested-by:. Those in the end are
  quite similar, so it does not make much sense to apply different ones.
  I considered using an approach along the lines of "if you reported it
  in pubic by mail, implicit permission to use in a tag is granted"; but
  I abstained from it, as I assume there are good reasons for the
  existing approach regarding Suggested-by:.
- CC all the people that provided feedback on the text changes in v1

v1: https://lore.kernel.org/all/f5bc0639a20d6fac68062466d5e3dd0519588d08.1731486825.git.linux@leemhuis.info/
- initial version
---
 Documentation/process/5.Posting.rst          | 13 +++++--
 Documentation/process/submitting-patches.rst | 39 ++++++++++++++------
 2 files changed, 36 insertions(+), 16 deletions(-)

diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index dbb763a8de901d..22fa925353cf54 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -268,10 +268,15 @@ The tags in common use are:
  - Cc: the named person received a copy of the patch and had the
    opportunity to comment on it.
 
-Be careful in the addition of tags to your patches, as only Cc: is appropriate
-for addition without the explicit permission of the person named; using
-Reported-by: is fine most of the time as well, but ask for permission if
-the bug was reported in private.
+Be careful in the addition of the aforementioned tags to your patches, as all
+except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
+person named. For those three implicit permission is sufficient if the person
+contributed to the Linux kernel using that name and email address according
+to the lore archives or the commit history -- and in case of Reported-by:
+and Suggested-by: did the reporting or suggestion in public. Note,
+bugzilla.kernel.org is a public place in this sense, but email addresses
+used there are private; so do not expose them in tags, unless the person
+used them in earlier contributions.
 
 
 Sending the patch
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 8fdc0ef3e604f4..72f6de419ccc4c 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -495,10 +495,10 @@ list archives.  A "# Suffix" may also be used in this case to clarify.
 
 If a person has had the opportunity to comment on a patch, but has not
 provided such comments, you may optionally add a ``Cc:`` tag to the patch.
-This is the only tag which might be added without an explicit action by the
-person it names - but it should indicate that this person was copied on the
-patch.  This tag documents that potentially interested parties
-have been included in the discussion.
+This tag documents that potentially interested parties have been included in
+the discussion. Note, this is one of only three tags you might be able to use
+without explicit permission of the person named (see 'Tagging people requires
+permission' below for details).
 
 Co-developed-by: states that the patch was co-created by multiple developers;
 it is used to give attribution to co-authors (in addition to the author
@@ -544,9 +544,9 @@ hopefully inspires them to help us again in the future. The tag is intended for
 bugs; please do not use it to credit feature requests. The tag should be
 followed by a Closes: tag pointing to the report, unless the report is not
 available on the web. The Link: tag can be used instead of Closes: if the patch
-fixes a part of the issue(s) being reported. Please note that if the bug was
-reported in private, then ask for permission first before using the Reported-by
-tag.
+fixes a part of the issue(s) being reported. Note, the Reported-by tag is one
+of only three tags you might be able to use without explicit permission of the
+person named (see 'Tagging people requires permission' below for details).
 
 A Tested-by: tag indicates that the patch has been successfully tested (in
 some environment) by the person named.  This tag informs maintainers that
@@ -596,11 +596,11 @@ Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned
 in the patch changelog (after the '---' separator).
 
 A Suggested-by: tag indicates that the patch idea is suggested by the person
-named and ensures credit to the person for the idea. Please note that this
-tag should not be added without the reporter's permission, especially if the
-idea was not posted in a public forum. That said, if we diligently credit our
-idea reporters, they will, hopefully, be inspired to help us again in the
-future.
+named and ensures credit to the person for the idea: if we diligently credit
+our idea reporters, they will, hopefully, be inspired to help us again in the
+future. Note, this is one of only three tags you might be able to use without
+explicit permission of the person named (see 'Tagging people requires
+permission' below for details).
 
 A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
 is used to make it easy to determine where a bug originated, which can help
@@ -618,6 +618,21 @@ Finally, while providing tags is welcome and typically very appreciated, please
 note that signers (i.e. submitters and maintainers) may use their discretion in
 applying offered tags.
 
+.. _tagging_people:
+
+Tagging people requires permission
+----------------------------------
+
+Be careful in the addition of the aforementioned tags to your patches, as all
+except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
+person named. For those three implicit permission is sufficient if the person
+contributed to the Linux kernel using that name and email address according
+to the lore archives or the commit history -- and in case of Reported-by:
+and Suggested-by: did the reporting or suggestion in public. Note,
+bugzilla.kernel.org is a public place in this sense, but email addresses
+used there are private; so do not expose them in tags, unless the person
+used them in earlier contributions.
+
 .. _the_canonical_patch_format:
 
 The canonical patch format

base-commit: e8bcda12176c47f2ce6c5104955845d028a640e8
-- 
2.45.0

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 6129 bytes --]

On Thu, Feb 06, 2025 at 03:30:10PM +0100, Thorsten Leemhuis wrote:
> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
> index dbb763a8de901d..22fa925353cf54 100644
> --- a/Documentation/process/5.Posting.rst
> +++ b/Documentation/process/5.Posting.rst
> @@ -268,10 +268,15 @@ The tags in common use are:
>   - Cc: the named person received a copy of the patch and had the
>     opportunity to comment on it.
>  
> -Be careful in the addition of tags to your patches, as only Cc: is appropriate
> -for addition without the explicit permission of the person named; using
> -Reported-by: is fine most of the time as well, but ask for permission if
> -the bug was reported in private.
> +Be careful in the addition of the aforementioned tags to your patches, as all
> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
> +person named. For those three implicit permission is sufficient if the person
> +contributed to the Linux kernel using that name and email address according
> +to the lore archives or the commit history -- and in case of Reported-by:
> +and Suggested-by: did the reporting or suggestion in public. Note,
> +bugzilla.kernel.org is a public place in this sense, but email addresses
> +used there are private; so do not expose them in tags, unless the person
> +used them in earlier contributions.

So for example I can only include Tested-by: when a contributor who tested
my patch explicitly offer the tag by replying to it i.e. with the tag, right?

>  
>  
>  Sending the patch
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index 8fdc0ef3e604f4..72f6de419ccc4c 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -495,10 +495,10 @@ list archives.  A "# Suffix" may also be used in this case to clarify.
>  
>  If a person has had the opportunity to comment on a patch, but has not
>  provided such comments, you may optionally add a ``Cc:`` tag to the patch.
> -This is the only tag which might be added without an explicit action by the
> -person it names - but it should indicate that this person was copied on the
> -patch.  This tag documents that potentially interested parties
> -have been included in the discussion.
> +This tag documents that potentially interested parties have been included in
> +the discussion. Note, this is one of only three tags you might be able to use
> +without explicit permission of the person named (see 'Tagging people requires
> +permission' below for details).
>  
>  Co-developed-by: states that the patch was co-created by multiple developers;
>  it is used to give attribution to co-authors (in addition to the author
> @@ -544,9 +544,9 @@ hopefully inspires them to help us again in the future. The tag is intended for
>  bugs; please do not use it to credit feature requests. The tag should be
>  followed by a Closes: tag pointing to the report, unless the report is not
>  available on the web. The Link: tag can be used instead of Closes: if the patch
> -fixes a part of the issue(s) being reported. Please note that if the bug was
> -reported in private, then ask for permission first before using the Reported-by
> -tag.
> +fixes a part of the issue(s) being reported. Note, the Reported-by tag is one
> +of only three tags you might be able to use without explicit permission of the
> +person named (see 'Tagging people requires permission' below for details).
>  
>  A Tested-by: tag indicates that the patch has been successfully tested (in
>  some environment) by the person named.  This tag informs maintainers that
> @@ -596,11 +596,11 @@ Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned
>  in the patch changelog (after the '---' separator).
>  
>  A Suggested-by: tag indicates that the patch idea is suggested by the person
> -named and ensures credit to the person for the idea. Please note that this
> -tag should not be added without the reporter's permission, especially if the
> -idea was not posted in a public forum. That said, if we diligently credit our
> -idea reporters, they will, hopefully, be inspired to help us again in the
> -future.
> +named and ensures credit to the person for the idea: if we diligently credit
> +our idea reporters, they will, hopefully, be inspired to help us again in the
> +future. Note, this is one of only three tags you might be able to use without
> +explicit permission of the person named (see 'Tagging people requires
> +permission' below for details).
>  
>  A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
>  is used to make it easy to determine where a bug originated, which can help
> @@ -618,6 +618,21 @@ Finally, while providing tags is welcome and typically very appreciated, please
>  note that signers (i.e. submitters and maintainers) may use their discretion in
>  applying offered tags.
>  
> +.. _tagging_people:
> +
> +Tagging people requires permission
> +----------------------------------
> +
> +Be careful in the addition of the aforementioned tags to your patches, as all
> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
> +person named. For those three implicit permission is sufficient if the person
> +contributed to the Linux kernel using that name and email address according
> +to the lore archives or the commit history -- and in case of Reported-by:
> +and Suggested-by: did the reporting or suggestion in public. Note,
> +bugzilla.kernel.org is a public place in this sense, but email addresses
> +used there are private; so do not expose them in tags, unless the person
> +used them in earlier contributions.
> +
>  .. _the_canonical_patch_format:
>  
>  The canonical patch format
> 
> base-commit: e8bcda12176c47f2ce6c5104955845d028a640e8

The wording looks OK.

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Thorsten Leemhuis]

On 07.02.25 02:42, Bagas Sanjaya wrote:
> On Thu, Feb 06, 2025 at 03:30:10PM +0100, Thorsten Leemhuis wrote:
>> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
>> index dbb763a8de901d..22fa925353cf54 100644
>> --- a/Documentation/process/5.Posting.rst
>> +++ b/Documentation/process/5.Posting.rst
>> @@ -268,10 +268,15 @@ The tags in common use are:
>>   - Cc: the named person received a copy of the patch and had the
>>     opportunity to comment on it.
>>  
>> -Be careful in the addition of tags to your patches, as only Cc: is appropriate
>> -for addition without the explicit permission of the person named; using
>> -Reported-by: is fine most of the time as well, but ask for permission if
>> -the bug was reported in private.
>> +Be careful in the addition of the aforementioned tags to your patches, as all
>> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
>> +person named. For those three implicit permission is sufficient if the person
>> +contributed to the Linux kernel using that name and email address according
>> +to the lore archives or the commit history -- and in case of Reported-by:
>> +and Suggested-by: did the reporting or suggestion in public. Note,
>> +bugzilla.kernel.org is a public place in this sense, but email addresses
>> +used there are private; so do not expose them in tags, unless the person
>> +used them in earlier contributions.
> 
> So for example I can only include Tested-by: when a contributor who tested
> my patch explicitly offer the tag by replying to it i.e. with the tag, right?

At some point a text must leave the interpretation up to the reader. I
would say a "yes, that's okay" to the question "is it okay to add a
'tested-by' tag in the patch description; note, your name and email
address will then end up in the commit history and can not be removed
there" is sufficient "permission" as well.

> The wording looks OK.
> 
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

Thx!

Ciao, Thorsten

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Mauro Carvalho Chehab]

Em Fri, 7 Feb 2025 09:24:56 +0100
Thorsten Leemhuis <linux@leemhuis.info> escreveu:

> On 07.02.25 02:42, Bagas Sanjaya wrote:
> > On Thu, Feb 06, 2025 at 03:30:10PM +0100, Thorsten Leemhuis wrote:  
> >> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
> >> index dbb763a8de901d..22fa925353cf54 100644
> >> --- a/Documentation/process/5.Posting.rst
> >> +++ b/Documentation/process/5.Posting.rst
> >> @@ -268,10 +268,15 @@ The tags in common use are:
> >>   - Cc: the named person received a copy of the patch and had the
> >>     opportunity to comment on it.
> >>  
> >> -Be careful in the addition of tags to your patches, as only Cc: is appropriate
> >> -for addition without the explicit permission of the person named; using
> >> -Reported-by: is fine most of the time as well, but ask for permission if
> >> -the bug was reported in private.
> >> +Be careful in the addition of the aforementioned tags to your patches, as all
> >> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
> >> +person named. For those three implicit permission is sufficient if the person
> >> +contributed to the Linux kernel using that name and email address according
> >> +to the lore archives or the commit history -- and in case of Reported-by:
> >> +and Suggested-by: did the reporting or suggestion in public. Note,
> >> +bugzilla.kernel.org is a public place in this sense, but email addresses
> >> +used there are private; so do not expose them in tags, unless the person
> >> +used them in earlier contributions.  
> > 
> > So for example I can only include Tested-by: when a contributor who tested
> > my patch explicitly offer the tag by replying to it i.e. with the tag, right?  
> At some point a text must leave the interpretation up to the reader. I
> would say a "yes, that's okay" to the question "is it okay to add a
> 'tested-by' tag in the patch description; note, your name and email
> address will then end up in the commit history and can not be removed
> there" is sufficient "permission" as well.

For me, it sounds reasonable to accept a public reply about someone
testing a patch as a reason to add a tested-by tag. Yet, I don't add 
tested-by myself based on replies. What I do when someone sends 
a reply saying that the patch was tested is to request the tester to 
reply with a tested-by with a short description about the test scenario.

IMO it is important to ask it to the tester, not only to have an explicit
tag, but also because as a simple tested-by without a test scenario is 
usually not very useful. 

Regards,
Mauro

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Thorsten Leemhuis]

On 10.02.25 17:16, Mauro Carvalho Chehab wrote:
> Em Fri, 7 Feb 2025 09:24:56 +0100
> Thorsten Leemhuis <linux@leemhuis.info> escreveu:
> 
>> On 07.02.25 02:42, Bagas Sanjaya wrote:
>>> On Thu, Feb 06, 2025 at 03:30:10PM +0100, Thorsten Leemhuis wrote:  
>>>> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
>>>> index dbb763a8de901d..22fa925353cf54 100644
>>>> --- a/Documentation/process/5.Posting.rst
>>>> +++ b/Documentation/process/5.Posting.rst
>>>> @@ -268,10 +268,15 @@ The tags in common use are:
>>>>   - Cc: the named person received a copy of the patch and had the
>>>>     opportunity to comment on it.
>>>>  
>>>> -Be careful in the addition of tags to your patches, as only Cc: is appropriate
>>>> -for addition without the explicit permission of the person named; using
>>>> -Reported-by: is fine most of the time as well, but ask for permission if
>>>> -the bug was reported in private.
>>>> +Be careful in the addition of the aforementioned tags to your patches, as all
>>>> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
>>>> +person named. For those three implicit permission is sufficient if the person
>>>> +contributed to the Linux kernel using that name and email address according
>>>> +to the lore archives or the commit history -- and in case of Reported-by:
>>>> +and Suggested-by: did the reporting or suggestion in public. Note,
>>>> +bugzilla.kernel.org is a public place in this sense, but email addresses
>>>> +used there are private; so do not expose them in tags, unless the person
>>>> +used them in earlier contributions.  
>>>
>>> So for example I can only include Tested-by: when a contributor who tested
>>> my patch explicitly offer the tag by replying to it i.e. with the tag, right?  
>> At some point a text must leave the interpretation up to the reader. I
>> would say a "yes, that's okay" to the question "is it okay to add a
>> 'tested-by' tag in the patch description; note, your name and email
>> address will then end up in the commit history and can not be removed
>> there" is sufficient "permission" as well.
> 
> For me, it sounds reasonable to accept a public reply about someone
> testing a patch as a reason to add a tested-by tag. Yet, I don't add 
> tested-by myself based on replies. What I do when someone sends 
> a reply saying that the patch was tested is to request the tester to 
> reply with a tested-by with a short description about the test scenario.
> 
> IMO it is important to ask it to the tester, not only to have an explicit
> tag, but also because as a simple tested-by without a test scenario is 
> usually not very useful. 

I see your point, but I'd say it is useful enough: if that patch causes
a regression you immediately know whom to CC to test a fix for that
regression.

But maybe my view is just biased here. ;-)

Ciao, Thorsten

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Laurent Pinchart]

Hi Thorsten,

Thank you for the patch.

On Thu, Feb 06, 2025 at 03:30:10PM +0100, Thorsten Leemhuis wrote:
> Point out that explicit permission is usually needed to tag other people
> in changes, but mention that implicit permission can be sufficient in
> certain cases. This fixes slight inconsistencies between Reported-by:
> and Suggested-by: and makes the usage more intuitive.
> 
> While at it, explicitly mention the dangers of our bugzilla instance, as
> it makes it easy to forget that email addresses visible there are only
> shown to logged-in users.
> 
> The latter is not a theoretical issue, as one maintainer mentioned that
> his employer received a EU GDPR (general data protection regulation)
> complaint after exposing a email address used in bugzilla through a tag
> in a patch description.
> 
> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Cc: Simona Vetter <simona.vetter@ffwll.ch>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> 
> Jonathan, what do you think of this? I felt somewhat unsure about this a
> few weeks ago, but I guess I was overly careful. If you think this
> change is fine and shouldn't cause any trouble for anyone, feel free to
> merge this. And if not, please speak up.
> 
> Note: this triggers a few checkpatch.pl complaints that are irrelevant
> when when to comes to changes like this.
> 
> v4:
> - slight wording change to make a implicity aspect explicit, as pointed
>   out by Mauro
> - Add reviewed-bys from Mauro and Shuah
> - The number of reviewed-bys is still smal, nevertheless drop the
>   DONOTMERGE and hole that Jonathan will speak up if he thinks this is
>   a stupid move.
> 
> v3: https://lore.kernel.org/all/c29ef5fa12e37c3a289e46d4442b069af94e5b05.1733127212.git.linux@leemhuis.info/
> - try yet again from a slightly different angle which loosens the rules
>   slightly. This from review feedback to earlier versions is apparently
>   what other developers want and from their "no lawyer" perspective
>   consider to be okay. As IANAL myself I don't feel totally comfortable
>   with this and have no idea if this legally is sound, so tag patch with
>   "DONOTMERGE" for now; will remove this for v4 if enough people add a
>   "Reviewed-by". Otherwise the story of this patch might end here, unless
>   someone else submits it for inclusion (you are free to do so!).
> - remote patch adding Suggested-by: tag to 5.Posting and submit it
>   separately
> 
> v2: https://lore.kernel.org/all/cover.1731749544.git.linux@leemhuis.info/
> - Retry differently. This slightly hardens the rule for Reported-by:
>   while slightly lessening it for Suggested-by:. Those in the end are
>   quite similar, so it does not make much sense to apply different ones.
>   I considered using an approach along the lines of "if you reported it
>   in pubic by mail, implicit permission to use in a tag is granted"; but
>   I abstained from it, as I assume there are good reasons for the
>   existing approach regarding Suggested-by:.
> - CC all the people that provided feedback on the text changes in v1
> 
> v1: https://lore.kernel.org/all/f5bc0639a20d6fac68062466d5e3dd0519588d08.1731486825.git.linux@leemhuis.info/
> - initial version
> ---
>  Documentation/process/5.Posting.rst          | 13 +++++--
>  Documentation/process/submitting-patches.rst | 39 ++++++++++++++------
>  2 files changed, 36 insertions(+), 16 deletions(-)
> 
> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
> index dbb763a8de901d..22fa925353cf54 100644
> --- a/Documentation/process/5.Posting.rst
> +++ b/Documentation/process/5.Posting.rst
> @@ -268,10 +268,15 @@ The tags in common use are:
>   - Cc: the named person received a copy of the patch and had the
>     opportunity to comment on it.
>  
> -Be careful in the addition of tags to your patches, as only Cc: is appropriate
> -for addition without the explicit permission of the person named; using
> -Reported-by: is fine most of the time as well, but ask for permission if
> -the bug was reported in private.
> +Be careful in the addition of the aforementioned tags to your patches, as all
> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
> +person named. For those three implicit permission is sufficient if the person
> +contributed to the Linux kernel using that name and email address according
> +to the lore archives or the commit history -- and in case of Reported-by:
> +and Suggested-by: did the reporting or suggestion in public. Note,
> +bugzilla.kernel.org is a public place in this sense, but email addresses
> +used there are private; so do not expose them in tags, unless the person
> +used them in earlier contributions.

I like this text very much, it's concise and clear. My only possible
concern is that "explicit permission" isn't defined. I assume that
someone sendubg a Reviewed-by or Acked-by tag in a public mail thread
counts as permission, but strictly speaking it's not explicit.

Regardless of that, I think we can clarify what explicit permission
means in a follow-up patch. If you would like to merge this one as-is,

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

You have my explicit permission to include this tag in the commit :-D

>  Sending the patch
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index 8fdc0ef3e604f4..72f6de419ccc4c 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -495,10 +495,10 @@ list archives.  A "# Suffix" may also be used in this case to clarify.
>  
>  If a person has had the opportunity to comment on a patch, but has not
>  provided such comments, you may optionally add a ``Cc:`` tag to the patch.
> -This is the only tag which might be added without an explicit action by the
> -person it names - but it should indicate that this person was copied on the
> -patch.  This tag documents that potentially interested parties
> -have been included in the discussion.
> +This tag documents that potentially interested parties have been included in
> +the discussion. Note, this is one of only three tags you might be able to use
> +without explicit permission of the person named (see 'Tagging people requires
> +permission' below for details).
>  
>  Co-developed-by: states that the patch was co-created by multiple developers;
>  it is used to give attribution to co-authors (in addition to the author
> @@ -544,9 +544,9 @@ hopefully inspires them to help us again in the future. The tag is intended for
>  bugs; please do not use it to credit feature requests. The tag should be
>  followed by a Closes: tag pointing to the report, unless the report is not
>  available on the web. The Link: tag can be used instead of Closes: if the patch
> -fixes a part of the issue(s) being reported. Please note that if the bug was
> -reported in private, then ask for permission first before using the Reported-by
> -tag.
> +fixes a part of the issue(s) being reported. Note, the Reported-by tag is one
> +of only three tags you might be able to use without explicit permission of the
> +person named (see 'Tagging people requires permission' below for details).
>  
>  A Tested-by: tag indicates that the patch has been successfully tested (in
>  some environment) by the person named.  This tag informs maintainers that
> @@ -596,11 +596,11 @@ Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned
>  in the patch changelog (after the '---' separator).
>  
>  A Suggested-by: tag indicates that the patch idea is suggested by the person
> -named and ensures credit to the person for the idea. Please note that this
> -tag should not be added without the reporter's permission, especially if the
> -idea was not posted in a public forum. That said, if we diligently credit our
> -idea reporters, they will, hopefully, be inspired to help us again in the
> -future.
> +named and ensures credit to the person for the idea: if we diligently credit
> +our idea reporters, they will, hopefully, be inspired to help us again in the
> +future. Note, this is one of only three tags you might be able to use without
> +explicit permission of the person named (see 'Tagging people requires
> +permission' below for details).
>  
>  A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
>  is used to make it easy to determine where a bug originated, which can help
> @@ -618,6 +618,21 @@ Finally, while providing tags is welcome and typically very appreciated, please
>  note that signers (i.e. submitters and maintainers) may use their discretion in
>  applying offered tags.
>  
> +.. _tagging_people:
> +
> +Tagging people requires permission
> +----------------------------------
> +
> +Be careful in the addition of the aforementioned tags to your patches, as all
> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
> +person named. For those three implicit permission is sufficient if the person
> +contributed to the Linux kernel using that name and email address according
> +to the lore archives or the commit history -- and in case of Reported-by:
> +and Suggested-by: did the reporting or suggestion in public. Note,
> +bugzilla.kernel.org is a public place in this sense, but email addresses
> +used there are private; so do not expose them in tags, unless the person
> +used them in earlier contributions.
> +
>  .. _the_canonical_patch_format:
>  
>  The canonical patch format
> 
> base-commit: e8bcda12176c47f2ce6c5104955845d028a640e8

-- 
Regards,

Laurent Pinchart

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Thorsten Leemhuis]

On 07.02.25 10:05, Laurent Pinchart wrote:
> Thank you for the patch.

Thx for saying that!

> On Thu, Feb 06, 2025 at 03:30:10PM +0100, Thorsten Leemhuis wrote:
>> Point out that explicit permission is usually needed to tag other people
>> in changes, but mention that implicit permission can be sufficient in
>> certain cases. This fixes slight inconsistencies between Reported-by:
>> and Suggested-by: and makes the usage more intuitive.
>>
>> While at it, explicitly mention the dangers of our bugzilla instance, as
>> it makes it easy to forget that email addresses visible there are only
>> shown to logged-in users.
>>
>> The latter is not a theoretical issue, as one maintainer mentioned that
>> his employer received a EU GDPR (general data protection regulation)
>> complaint after exposing a email address used in bugzilla through a tag
>> in a patch description.
> [...]
>> -Be careful in the addition of tags to your patches, as only Cc: is appropriate
>> -for addition without the explicit permission of the person named; using
>> -Reported-by: is fine most of the time as well, but ask for permission if
>> -the bug was reported in private.
>> +Be careful in the addition of the aforementioned tags to your patches, as all
>> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
>> +person named. For those three implicit permission is sufficient if the person
>> +contributed to the Linux kernel using that name and email address according
>> +to the lore archives or the commit history -- and in case of Reported-by:
>> +and Suggested-by: did the reporting or suggestion in public. Note,
>> +bugzilla.kernel.org is a public place in this sense, but email addresses
>> +used there are private; so do not expose them in tags, unless the person
>> +used them in earlier contributions.
> 
> I like this text very much, it's concise and clear.

Glad to hear!

> My only possible
> concern is that "explicit permission" isn't defined. I assume that
> someone sendubg a Reviewed-by or Acked-by tag in a public mail thread
> counts as permission, but strictly speaking it's not explicit.
> 
> Regardless of that, I think we can clarify what explicit permission
> means in a follow-up patch. If you would like to merge this one as-is,

Hmmmm. Not totally sure that I exactly understand what you mean, but I
think I see it. But I'm not sure how to solve that. Would simply
dropping the "explicit" solve this? Or should I start the section like this:

""
Be careful in the addition of the aforementioned tags to your patches,
almost all need permission by the person named; one can be assumed if
the person provided that tag in a reply or acknowledged its inclusion
after being made aware that name and email address will end up in public
places where they can't be removed.

The tags Cc:, Reported-by:, and Suggested-by: are an exception: for
those three implicit permission is sufficient, ...
"""

Ciao, Thorsten

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Laurent Pinchart]

On Sat, Feb 08, 2025 at 04:36:47PM +0100, Thorsten Leemhuis wrote:
> On 07.02.25 10:05, Laurent Pinchart wrote:
> > Thank you for the patch.
> 
> Thx for saying that!
> 
> > On Thu, Feb 06, 2025 at 03:30:10PM +0100, Thorsten Leemhuis wrote:
> >> Point out that explicit permission is usually needed to tag other people
> >> in changes, but mention that implicit permission can be sufficient in
> >> certain cases. This fixes slight inconsistencies between Reported-by:
> >> and Suggested-by: and makes the usage more intuitive.
> >>
> >> While at it, explicitly mention the dangers of our bugzilla instance, as
> >> it makes it easy to forget that email addresses visible there are only
> >> shown to logged-in users.
> >>
> >> The latter is not a theoretical issue, as one maintainer mentioned that
> >> his employer received a EU GDPR (general data protection regulation)
> >> complaint after exposing a email address used in bugzilla through a tag
> >> in a patch description.
> > [...]
> >> -Be careful in the addition of tags to your patches, as only Cc: is appropriate
> >> -for addition without the explicit permission of the person named; using
> >> -Reported-by: is fine most of the time as well, but ask for permission if
> >> -the bug was reported in private.
> >> +Be careful in the addition of the aforementioned tags to your patches, as all
> >> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
> >> +person named. For those three implicit permission is sufficient if the person
> >> +contributed to the Linux kernel using that name and email address according
> >> +to the lore archives or the commit history -- and in case of Reported-by:
> >> +and Suggested-by: did the reporting or suggestion in public. Note,
> >> +bugzilla.kernel.org is a public place in this sense, but email addresses
> >> +used there are private; so do not expose them in tags, unless the person
> >> +used them in earlier contributions.
> > 
> > I like this text very much, it's concise and clear.
> 
> Glad to hear!
> 
> > My only possible
> > concern is that "explicit permission" isn't defined. I assume that
> > someone sendubg a Reviewed-by or Acked-by tag in a public mail thread
> > counts as permission, but strictly speaking it's not explicit.
> > 
> > Regardless of that, I think we can clarify what explicit permission
> > means in a follow-up patch. If you would like to merge this one as-is,
> 
> Hmmmm. Not totally sure that I exactly understand what you mean, but I
> think I see it.

What I meant is that I interpret "explicit" as requiring an explicit
mention of permission (e.g. "You can add my tag to the commit"), while
replying to a patch with a tag on a public list seems to me to convey an
implicit permission instead.

> But I'm not sure how to solve that. Would simply
> dropping the "explicit" solve this? Or should I start the section like this:

Dropping "explicit" seems to be the simplest solution, but the next
sentence mentions "implicit permission" which would then sound weird.

> ""
> Be careful in the addition of the aforementioned tags to your patches,
> almost all need permission by the person named; one can be assumed if
> the person provided that tag in a reply or acknowledged its inclusion

"in a reply to a public list"

> after being made aware that name and email address will end up in public
> places where they can't be removed.
> 
> The tags Cc:, Reported-by:, and Suggested-by: are an exception: for
> those three implicit permission is sufficient, ...
> """

This sounds good to me.

-- 
Regards,

Laurent Pinchart

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Thorsten Leemhuis]

On 10.02.25 12:15, Laurent Pinchart wrote:
> On Sat, Feb 08, 2025 at 04:36:47PM +0100, Thorsten Leemhuis wrote:
>> On 07.02.25 10:05, Laurent Pinchart wrote:
>>> On Thu, Feb 06, 2025 at 03:30:10PM +0100, Thorsten Leemhuis wrote:
>>> [...]
>>>> +Be careful in the addition of the aforementioned tags to your patches, as all
>>>> +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
>>>> +person named. For those three implicit permission is sufficient if the person
>>>> +contributed to the Linux kernel using that name and email address according
>>>> +to the lore archives or the commit history -- and in case of Reported-by:
>>>> +and Suggested-by: did the reporting or suggestion in public. Note,
>>>> +bugzilla.kernel.org is a public place in this sense, but email addresses
>>>> +used there are private; so do not expose them in tags, unless the person
>>>> +used them in earlier contributions.
> [...]
>> But I'm not sure how to solve that. Would simply
>> dropping the "explicit" solve this? Or should I start the section like this:
> 
> Dropping "explicit" seems to be the simplest solution, but the next
> sentence mentions "implicit permission" which would then sound weird.

TBH: a bit, yes, but I think I'd prefer that a tiny bit over making that
section yet again a few lines longer. But I don't care much. Maybe
someone else (Jonathan?) can weight in on this?

>> ""
>> Be careful in the addition of the aforementioned tags to your patches,
>> almost all need permission by the person named; one can be assumed if
>> the person provided that tag in a reply or acknowledged its inclusion
> 
> "in a reply to a public list"

Yes, albeit I'd go with "public reply" (shorter, and does not exclude a
reply in a public bug tracker comment).

>> after being made aware that name and email address will end up in public
>> places where they can't be removed.
>>
>> The tags Cc:, Reported-by:, and Suggested-by: are an exception: for
>> those three implicit permission is sufficient, ...
>> """
> This sounds good to me.

Thx!

Ciao, Thorsten

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Jonathan Corbet]

Thorsten Leemhuis <linux@leemhuis.info> writes:

> Point out that explicit permission is usually needed to tag other people
> in changes, but mention that implicit permission can be sufficient in
> certain cases. This fixes slight inconsistencies between Reported-by:
> and Suggested-by: and makes the usage more intuitive.
>
> While at it, explicitly mention the dangers of our bugzilla instance, as
> it makes it easy to forget that email addresses visible there are only
> shown to logged-in users.
>
> The latter is not a theoretical issue, as one maintainer mentioned that
> his employer received a EU GDPR (general data protection regulation)
> complaint after exposing a email address used in bugzilla through a tag
> in a patch description.
>
> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Cc: Simona Vetter <simona.vetter@ffwll.ch>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>
> Jonathan, what do you think of this? I felt somewhat unsure about this a
> few weeks ago, but I guess I was overly careful. If you think this
> change is fine and shouldn't cause any trouble for anyone, feel free to
> merge this. And if not, please speak up.


I have a couple of thoughts, neither of which is sufficient for me to
oppose the change if there is consensus for it:

- You're saying that people need to grep email addresses out of the git
  history before crediting them in a tag; that's not a step we have
  required of people before and seems like a bit much..?

- It would be awfully nice if we could provide this advice in exactly
  one place in the document.  This is one of our most important docs,
  and it is far too long to expect new contributors to read through and
  absorb.  Avoiding making it longer and more repetitive would be
  better, if we can.

- I wonder if it would make sense to say that, if an implicit-permission
  tag has been added, the person named in it should get at least one
  copy of the change before it is merged?

OK, three thoughts, you know what they say about off-by-one errors :)

Thanks,

jon

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Thorsten Leemhuis]

On 10.02.25 19:12, Jonathan Corbet wrote:
> Thorsten Leemhuis <linux@leemhuis.info> writes:
>> Point out that explicit permission is usually needed to tag other people
>> in changes, but mention that implicit permission can be sufficient in
>> certain cases. This fixes slight inconsistencies between Reported-by:
>> and Suggested-by: and makes the usage more intuitive.
>>
>> While at it, explicitly mention the dangers of our bugzilla instance, as
>> it makes it easy to forget that email addresses visible there are only
>> shown to logged-in users.
>>
>> The latter is not a theoretical issue, as one maintainer mentioned that
>> his employer received a EU GDPR (general data protection regulation)
>> complaint after exposing a email address used in bugzilla through a tag
>> in a patch description.
> [...]
>> Jonathan, what do you think of this? I felt somewhat unsure about this a
>> few weeks ago, but I guess I was overly careful. If you think this
>> change is fine and shouldn't cause any trouble for anyone, feel free to
>> merge this. And if not, please speak up.
> 
> I have a couple of thoughts, neither of which is sufficient for me to
> oppose the change if there is consensus for it:
> 
> - You're saying that people need to grep email addresses out of the git
>   history before crediting them in a tag; that's not a step we have
>   required of people before and seems like a bit much..?

Do I? I don't think so. The phrase used is "name and email address
according to the lore archives *or* the commit history". I'd say that is
no extra work in most cases, as developers frequently interact with the
same set of people. And when not: most development happens by mail, so
all that is needed is a simply simple "is some list archived on lore
among the recipients". But sure, if you deal with someone in bugzilla or
say gitlab.freedesktop.org it becomes somewhat harder.


> - It would be awfully nice if we could provide this advice in exactly
>   one place in the document.  This is one of our most important docs,
>   and it is far too long to expect new contributors to read through and
>   absorb.  Avoiding making it longer and more repetitive would be
>   better, if we can.

Well, in 5.Posting.rst that was possible. In submitting-patches.rst that
conflicted with existing text in three areas, so some changes were
needed; in one case the new text even got a little shorter, but overall
those changes did not add a single new line.

But sure, the new paragraph added a few lines. And it is identical in
both documents. But that is a more complex and existing situation this
patch can't solve. But of course I could avoid adding the new paragraph
to submitting-patches.rst and change the "(see 'Tagging people requires
permission' below for details)" added there already into "(see 'Tagging
people requires permission' in Documentation/process/5.Posting.rst for
details)". Given that people requested a even more detailed paragraph
(see the other reply I just sent to Laurent) that might be wise; OTOH
submitting-patches.rst right now AFAICS tries to be stand-alone, so it
feels wrong at the same time.

IOW: both is fine for me. Could you let me please know what you prefer?

> - I wonder if it would make sense to say that, if an implicit-permission
>   tag has been added, the person named in it should get at least one
>   copy of the change before it is merged?

Hah, that is where I'd start to say "that seems like a bit much". And it
does not help, as the cat is out of the bag once that copy is out, as
the name and the email address someone might prefer to keep private
would have made it to mailing list archives then already.

> OK, three thoughts, you know what they say about off-by-one errors :)

:-D

Ciao, Thorsten

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Jonathan Corbet]

Sorry, fell behind on things again...

Thorsten Leemhuis <linux@leemhuis.info> writes:

>> - It would be awfully nice if we could provide this advice in exactly
>>   one place in the document.  This is one of our most important docs,
>>   and it is far too long to expect new contributors to read through and
>>   absorb.  Avoiding making it longer and more repetitive would be
>>   better, if we can.
>
> Well, in 5.Posting.rst that was possible. In submitting-patches.rst that
> conflicted with existing text in three areas, so some changes were
> needed; in one case the new text even got a little shorter, but overall
> those changes did not add a single new line.
>
> But sure, the new paragraph added a few lines. And it is identical in
> both documents. But that is a more complex and existing situation this
> patch can't solve. But of course I could avoid adding the new paragraph
> to submitting-patches.rst and change the "(see 'Tagging people requires
> permission' below for details)" added there already into "(see 'Tagging
> people requires permission' in Documentation/process/5.Posting.rst for
> details)". Given that people requested a even more detailed paragraph
> (see the other reply I just sent to Laurent) that might be wise; OTOH
> submitting-patches.rst right now AFAICS tries to be stand-alone, so it
> feels wrong at the same time.
>
> IOW: both is fine for me. Could you let me please know what you prefer?

Adding more cross references certainly won't help, I guess we'll leave
it as-is for now.

>> - I wonder if it would make sense to say that, if an implicit-permission
>>   tag has been added, the person named in it should get at least one
>>   copy of the change before it is merged?
>
> Hah, that is where I'd start to say "that seems like a bit much". And it
> does not help, as the cat is out of the bag once that copy is out, as
> the name and the email address someone might prefer to keep private
> would have made it to mailing list archives then already.

The cat is out of the bag but not in the repository; the thought was
that it's polite to give the person involved a heads-up that their name
is being taken in vain.  Certainly I've seen enough "what, no, I don't
want that tag there" reactions over the years to think it would
occasionally head off a use that the owner of the name doesn't want.

jon

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Thorsten Leemhuis]

On 18.02.25 21:42, Jonathan Corbet wrote:
> Sorry, fell behind on things again...

No worries at all. And fun fact: I put this aside myself for some time
as I was unsure about the way forward...

> Thorsten Leemhuis <linux@leemhuis.info> writes:
> [...]
> Adding more cross references certainly won't help, I guess we'll leave
> it as-is for now.

+1

>>> - I wonder if it would make sense to say that, if an implicit-permission
>>>   tag has been added, the person named in it should get at least one
>>>   copy of the change before it is merged?
>>
>> Hah, that is where I'd start to say "that seems like a bit much". And it
>> does not help, as the cat is out of the bag once that copy is out, as
>> the name and the email address someone might prefer to keep private
>> would have made it to mailing list archives then already.
> 
> The cat is out of the bag but not in the repository; the thought was
> that it's polite to give the person involved a heads-up that their name
> is being taken in vain.  Certainly I've seen enough "what, no, I don't
> want that tag there" reactions over the years to think it would
> occasionally head off a use that the owner of the name doesn't want.

Hmmm, have a point there. How about a "s/contributed/routinely
contributes/" in this sentence:

"""
For those three implicit permission is sufficient if the person
contributed to the Linux kernel using that name and email address
according to the lore archives or the commit history
"""

This has downsides as well (some of which were discussed in replies to
earlier versions of this patch, iirc), but might be a better middle
ground that is really short. Ohh, and I'm not attached to the word
"routinely", but for me it seemed like a better fit that "regularly".
But maybe I'm wrong – or maybe there is even a better word.

Ciao, Thorsten

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Jonathan Corbet]

Thorsten Leemhuis <linux@leemhuis.info> writes:

> On 18.02.25 21:42, Jonathan Corbet wrote:
>> Sorry, fell behind on things again...
>
> No worries at all. And fun fact: I put this aside myself for some time
> as I was unsure about the way forward...
>
>> Thorsten Leemhuis <linux@leemhuis.info> writes:
>> [...]
>> Adding more cross references certainly won't help, I guess we'll leave
>> it as-is for now.
>
> +1
>
>>>> - I wonder if it would make sense to say that, if an implicit-permission
>>>>   tag has been added, the person named in it should get at least one
>>>>   copy of the change before it is merged?
>>>
>>> Hah, that is where I'd start to say "that seems like a bit much". And it
>>> does not help, as the cat is out of the bag once that copy is out, as
>>> the name and the email address someone might prefer to keep private
>>> would have made it to mailing list archives then already.
>> 
>> The cat is out of the bag but not in the repository; the thought was
>> that it's polite to give the person involved a heads-up that their name
>> is being taken in vain.  Certainly I've seen enough "what, no, I don't
>> want that tag there" reactions over the years to think it would
>> occasionally head off a use that the owner of the name doesn't want.
>
> Hmmm, have a point there. How about a "s/contributed/routinely
> contributes/" in this sentence:
>
> """
> For those three implicit permission is sufficient if the person
> contributed to the Linux kernel using that name and email address
> according to the lore archives or the commit history
> """

Sorry for being slow ... but also, I guess, for not communicating my
point very well.  My concern wasn't about somebody not wanting to appear
in the repository at all; it was more with somebody not wanting their
tag in a specific patch where they had not offered it.

It seems I'm the only one who is worried about this, though.  It seems
like we should go ahead and get this change in before the merge window
hits.

Thanks,

jon

Re: [PATCH v4] docs: clarify rules wrt tagging other people

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> Sorry for being slow ... but also, I guess, for not communicating my
> point very well.  My concern wasn't about somebody not wanting to appear
> in the repository at all; it was more with somebody not wanting their
> tag in a specific patch where they had not offered it.
>
> It seems I'm the only one who is worried about this, though.  It seems
> like we should go ahead and get this change in before the merge window
> hits.

OK, I have gone ahead and applied it ... though I'm still not 100%
comfortable with the wording as it is... :)

Thanks,

jon