ksummit.lists.linux.dev archive mirror
 help / color / mirror / Atom feed
From: Thorsten Leemhuis <linux@leemhuis.info>
To: workflows@vger.kernel.org, Greg KH <gregkh@linuxfoundation.org>,
	Linus Torvalds <torvalds@linux-foundation.org>
Cc: ksummit@lists.linux.dev,
	Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
	Konstantin Ryabitsev <konstantin@linuxfoundation.org>,
	Jonathan Corbet <corbet@lwn.net>
Subject: [RFC PATCH v2 1/2] docs: 5.Posting.rst: describe Fixes: and Link: tags
Date: Thu,  9 Dec 2021 10:52:16 +0100	[thread overview]
Message-ID: <e890d9fbee38e26ab4ed330badf46c7e21f06ad6.1639042966.git.linux@leemhuis.info> (raw)
In-Reply-To: <cover.1639042966.git.linux@leemhuis.info>

Explain Fixes: and Link: tags in Documentation/process/5.Posting.rst,
which for unknown reasons were not described yet in this file.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
v2/RFC:
- first version, split off from another patch to make this a preparatory
  patch that can be applied even if the other patch is not
---
 Documentation/process/5.Posting.rst | 29 ++++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index 855a70b80269..46635310c7c5 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -197,14 +197,29 @@ the build process, for example, or editor backup files) in the patch.  The
 file "dontdiff" in the Documentation directory can help in this regard;
 pass it to diff with the "-X" option.
 
-The tags mentioned above are used to describe how various developers have
-been associated with the development of this patch.  They are described in
-detail in
-the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
-document; what follows here is a brief summary.  Each of these lines has
-the format:
+The tags already briefly mentioned above are used to provide insights how
+the patch came into being. They are described in detail in the
+:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
+document; what follows here is a brief summary.
 
-::
+One tag is used to refer to earlier commits which had problems fixed by
+the patch::
+
+	Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
+
+Another tag is used for linking web pages with additional backgrounds or
+details, for example a report about a bug fixed by the patch or a document
+with a specification implemented by the patch::
+
+	Link: https://example.com/somewhere.html  optional-other-stuff
+
+Many maintainers when applying a patch also add this tag to link to the
+latest public review posting of the patch; often this is automatically done
+by tools like b4 or a git hook like the one described in
+'Documentation/maintainer/configure-git.rst'.
+
+A third kind of tags are used to document which developers were involved in
+the development of the patch. Each of these uses this format::
 
 	tag: Full Name <email address>  optional-other-stuff
 
-- 
2.31.1


  reply	other threads:[~2021-12-09  9:52 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-12-09  9:52 [RFC PATCH v2 0/2] Create 'Posted:' and 'Reviewed:' tags for links in commit messages Thorsten Leemhuis
2021-12-09  9:52 ` Thorsten Leemhuis [this message]
2021-12-09  9:52 ` [RFC PATCH v2 2/2] docs: introduce the commit message tags 'Reported:' and 'Posted:' Thorsten Leemhuis
2021-12-09 11:26 ` [RFC PATCH v2 0/2] Create 'Posted:' and 'Reported:' tags for links in commit messages Thorsten Leemhuis
2021-12-10 12:35 ` [RFC PATCH v2 0/2] Create 'Posted:' and 'Reviewed:' " Dan Carpenter

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=e890d9fbee38e26ab4ed330badf46c7e21f06ad6.1639042966.git.linux@leemhuis.info \
    --to=linux@leemhuis.info \
    --cc=corbet@lwn.net \
    --cc=gregkh@linuxfoundation.org \
    --cc=konstantin@linuxfoundation.org \
    --cc=ksummit@lists.linux.dev \
    --cc=linux-kernel@vger.kernel.org \
    --cc=torvalds@linux-foundation.org \
    --cc=workflows@vger.kernel.org \
    --subject='Re: [RFC PATCH v2 1/2] docs: 5.Posting.rst: describe Fixes: and Link: tags' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).