* [PATCH v1] docs: 5.Posting.rst: describe Fixes: and Link: tags
@ 2022-01-03 7:15 Thorsten Leemhuis
2022-01-03 7:36 ` Randy Dunlap
2022-01-03 22:51 ` Jonathan Corbet
0 siblings, 2 replies; 5+ messages in thread
From: Thorsten Leemhuis @ 2022-01-03 7:15 UTC (permalink / raw)
To: linux-doc
Cc: workflows, Linux Kernel Mailing List, Konstantin Ryabitsev,
Jonathan Corbet
Explain Fixes: and Link: tags in Documentation/process/5.Posting.rst,
which are missing in this file for unknown reasons and only described in
Documentation/process/submitting-patches.rst.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
---
Lo! If there is still a chance I'l like to get this patch into v5.17, as
during my work as regression tracker I noticed quite a few developers
seem to be unaware how the Link: tag should be used. Maybe in parts
that's because Documentation/process/5.Posting.rst doesn't describe it
yet, which described things from a another different angle than
Documentation/process/submitting-patches.rst.
Ciao, Thorsten
v1:
- First version as stand alone patch. It used to be the first patch of
this series that got abandoned after RFC/v2:
https://lore.kernel.org/all/cover.1639042966.git.linux@leemhuis.info/
Patch itself is unchanged, patch description slighly changed. Might
later submit other changes from that series seperately, too, still
unsure.
---
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..e7b919070210 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 who was involved in the development of
+the patch. Each of these uses this format::
tag: Full Name <email address> optional-other-stuff
base-commit: b36064425a18e29a3bad9c007b4dd1223f8aadc5
--
2.31.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v1] docs: 5.Posting.rst: describe Fixes: and Link: tags
2022-01-03 7:15 [PATCH v1] docs: 5.Posting.rst: describe Fixes: and Link: tags Thorsten Leemhuis
@ 2022-01-03 7:36 ` Randy Dunlap
2022-01-03 12:31 ` Thorsten Leemhuis
2022-01-03 22:51 ` Jonathan Corbet
1 sibling, 1 reply; 5+ messages in thread
From: Randy Dunlap @ 2022-01-03 7:36 UTC (permalink / raw)
To: Thorsten Leemhuis, linux-doc
Cc: workflows, Linux Kernel Mailing List, Konstantin Ryabitsev,
Jonathan Corbet
Hi--
On 1/2/22 23:15, Thorsten Leemhuis wrote:
> Explain Fixes: and Link: tags in Documentation/process/5.Posting.rst,
> which are missing in this file for unknown reasons and only described in
> Documentation/process/submitting-patches.rst.
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> ---
> Lo! If there is still a chance I'l like to get this patch into v5.17, as
I'd
> during my work as regression tracker I noticed quite a few developers
> seem to be unaware how the Link: tag should be used. Maybe in parts
> that's because Documentation/process/5.Posting.rst doesn't describe it
> yet, which described things from a another different angle than
> Documentation/process/submitting-patches.rst.
>
> Ciao, Thorsten
>
> v1:
> - First version as stand alone patch. It used to be the first patch of
> this series that got abandoned after RFC/v2:
> https://lore.kernel.org/all/cover.1639042966.git.linux@leemhuis.info/
> Patch itself is unchanged, patch description slighly changed. Might
slightly
> later submit other changes from that series seperately, too, still
separately,
> unsure.
> ---
> 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..e7b919070210 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 who was involved in the development of
of tag is used
> +the patch. Each of these uses this format::
>
> tag: Full Name <email address> optional-other-stuff
>
>
> base-commit: b36064425a18e29a3bad9c007b4dd1223f8aadc5
--
~Randy
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v1] docs: 5.Posting.rst: describe Fixes: and Link: tags
2022-01-03 7:36 ` Randy Dunlap
@ 2022-01-03 12:31 ` Thorsten Leemhuis
0 siblings, 0 replies; 5+ messages in thread
From: Thorsten Leemhuis @ 2022-01-03 12:31 UTC (permalink / raw)
To: Randy Dunlap, linux-doc
Cc: workflows, Linux Kernel Mailing List, Konstantin Ryabitsev,
Jonathan Corbet
Hi Randy! Thx for taking a look. Your helpful feedback made me CC you on
the RFC on a document about regressions I sent today as well. Feel free
to ignore it, if you're not interested.
On 03.01.22 08:36, Randy Dunlap wrote:
> On 1/2/22 23:15, Thorsten Leemhuis wrote:
>> Lo! If there is still a chance I'l like to get this patch into v5.17, as
> I'd
>
>> Patch itself is unchanged, patch description slighly changed. Might
> slightly
>
>> later submit other changes from that series seperately, too, still
> separately,
Note to self: avoid last minute changes. :-/
>> ---
>> Documentation/process/5.Posting.rst | 29 ++++++++++++++++++++++-------
>> 1 file changed, 22 insertions(+), 7 deletions(-)
> [...]
>> +A third kind of tags are used to document who was involved in the development of
> of tag is used
Many thx, fixed all of these locally for v2.
Ciao, Thorsten
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v1] docs: 5.Posting.rst: describe Fixes: and Link: tags
2022-01-03 7:15 [PATCH v1] docs: 5.Posting.rst: describe Fixes: and Link: tags Thorsten Leemhuis
2022-01-03 7:36 ` Randy Dunlap
@ 2022-01-03 22:51 ` Jonathan Corbet
2022-01-04 16:58 ` Thorsten Leemhuis
1 sibling, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2022-01-03 22:51 UTC (permalink / raw)
To: Thorsten Leemhuis, linux-doc
Cc: workflows, Linux Kernel Mailing List, Konstantin Ryabitsev
Thorsten Leemhuis <linux@leemhuis.info> writes:
> Explain Fixes: and Link: tags in Documentation/process/5.Posting.rst,
> which are missing in this file for unknown reasons and only described in
> Documentation/process/submitting-patches.rst.
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> ---
> Lo! If there is still a chance I'l like to get this patch into v5.17, as
I think that should be possible. Send me a version with Randy's
comments addressed; I also had one nit below...
> during my work as regression tracker I noticed quite a few developers
> seem to be unaware how the Link: tag should be used. Maybe in parts
> that's because Documentation/process/5.Posting.rst doesn't describe it
> yet, which described things from a another different angle than
> Documentation/process/submitting-patches.rst.
>
> Ciao, Thorsten
>
> v1:
> - First version as stand alone patch. It used to be the first patch of
> this series that got abandoned after RFC/v2:
> https://lore.kernel.org/all/cover.1639042966.git.linux@leemhuis.info/
> Patch itself is unchanged, patch description slighly changed. Might
> later submit other changes from that series seperately, too, still
> unsure.
> ---
> 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..e7b919070210 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::
I would s/had/introduced/
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v1] docs: 5.Posting.rst: describe Fixes: and Link: tags
2022-01-03 22:51 ` Jonathan Corbet
@ 2022-01-04 16:58 ` Thorsten Leemhuis
0 siblings, 0 replies; 5+ messages in thread
From: Thorsten Leemhuis @ 2022-01-04 16:58 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc
Cc: workflows, Linux Kernel Mailing List, Konstantin Ryabitsev
On 03.01.22 23:51, Jonathan Corbet wrote:
> Thorsten Leemhuis <linux@leemhuis.info> writes:
>
>> Explain Fixes: and Link: tags in Documentation/process/5.Posting.rst,
>> which are missing in this file for unknown reasons and only described in
>> Documentation/process/submitting-patches.rst.
>>
>> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
>> CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
>> ---
>> Lo! If there is still a chance I'l like to get this patch into v5.17, as
>
> I think that should be possible. Send me a version with Randy's
> comments addressed; I also had one nit below...
Sounds good. Comments and nit addressed and sent out again:
https://lore.kernel.org/linux-doc/c4a5f5e25fa84b26fd383bba6eafde4ab57c9de7.1641314856.git.linux@leemhuis.info/
Ciao, Thorsten
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2022-01-04 16:58 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-01-03 7:15 [PATCH v1] docs: 5.Posting.rst: describe Fixes: and Link: tags Thorsten Leemhuis
2022-01-03 7:36 ` Randy Dunlap
2022-01-03 12:31 ` Thorsten Leemhuis
2022-01-03 22:51 ` Jonathan Corbet
2022-01-04 16:58 ` Thorsten Leemhuis
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).