[PATCH 1/3] docs: submitting-patches: clarify Acked-by and introduce "# Suffix"

[Miguel Ojeda <ojeda@kernel.org>]

Acked-by is typically used by maintainers. However, sometimes it is
useful to be able to accept the tag from other stakeholders that may not
have done a deep technical review or may not be kernel developers. For
instance:

  - People with domain knowledge, such as the original author of the
    code being modified.

  - Userspace-side reviewers for a kernel uAPI patch, like in DRM --
    see Documentation/gpu/drm-uapi.rst:

    > The userspace-side reviewer should also provide an Acked-by on the
    > kernel uAPI patch indicating that they believe the proposed uAPI
    > is sound and sufficiently documented and validated for userspace's
    > consumption.

  - Key users of a feature, such as in [1].

Thus clarify that Acked-by may be used by other stakeholders (but most
commonly by maintainers).

Since, in these cases, it may be confusing why an Acked-by is/was
provided, allow and suggest to provide a "# Suffix" explaining it.

The "# Suffix" for Acked-by is already being used to clarify what part
of the patch a maintainer is acknowledging, thus also mention "# Suffix"
in the relevant paragraph.

Link: https://lore.kernel.org/rust-for-linux/CANiq72m4fea15Z0fFZauz8N2madkBJ0G7Dc094OwoajnXmROOA@mail.gmail.com/ [1]
Acked-by: Shuah Khan <skhan@linuxfoundation.org>
Acked-by: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 Documentation/process/submitting-patches.rst | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 1518bd57adab..c7a28af235f7 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -463,9 +463,17 @@ If a person was not directly involved in the preparation or handling of a
 patch but wishes to signify and record their approval of it then they can
 ask to have an Acked-by: line added to the patch's changelog.

-Acked-by: is often used by the maintainer of the affected code when that
+Acked-by: is meant to be used by those responsible for or involved with the
+affected code in one way or another.  Most commonly, the maintainer when that
 maintainer neither contributed to nor forwarded the patch.

+Acked-by: may also be used by other stakeholders, such as people with domain
+knowledge (e.g. the original author of the code being modified), userspace-side
+reviewers for a kernel uAPI patch or key users of a feature.  Optionally, in
+these cases, it can be useful to add a "# Suffix" to clarify its meaning::
+
+	Acked-by: The Stakeholder <stakeholder@example.org> # As primary user
+
 Acked-by: is not as formal as Signed-off-by:.  It is a record that the acker
 has at least reviewed the patch and has indicated acceptance.  Hence patch
 mergers will sometimes manually convert an acker's "yep, looks good to me"
@@ -477,7 +485,7 @@ For example, if a patch affects multiple subsystems and has an Acked-by: from
 one subsystem maintainer then this usually indicates acknowledgement of just
 the part which affects that maintainer's code.  Judgement should be used here.
 When in doubt people should refer to the original discussion in the mailing
-list archives.
+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.
--
2.48.0