[Preface: sorry, this likely will cause some bikeshedding; but I got the feeling
I should bring this up, as my Regression tracking bot relies on the Link: tag
and thus making its ambiguity worse]
The following patch proposes to create two new tags for stating URLs in commit
messages. They are meant to make it obvious what provided links are about. This
is useful for both users and scripts analyzing commits, as right now they have
no simple way to see what a provided URL is about – they thus have to guess from
the URLs or follow each one to check.
The proposed tag 'Posted:' should point to the last public review posting of the
patch in question, while 'Reported:' is meant to be used for linking to bug
reports. The 'Link:' tag, which until now covered these two aspects, stays
around for other kind of links, for example for links to PDFs or webpages with
background information relevant for the patch.
This submission partly is triggered by regzbot, my Linux kernel regression
tracking bot (https://linux-regtracking.leemhuis.info/regzbot/ ). It
automatically marks a tracked regression as resolved when it notices a commit
with a 'Link:' pointing to the report of the tracked regression; it also uses
this to detect when a proposed fix is posted for review. In preparation for this
I recently improved the kernel's documentation on 'Link:' to the best of my
understanding in commit 1f57bd42b77c ("docs: submitting-patches: make
section about the Link: tag more explicit"). I also started pointing out that
usage to various people when I noticed it was missing. Quite a few developers
didn't know that 'Link:' was supposed to be like this or completely unaware they
were supposed to links bug reports. Developers from the DRM subsystem were using
'References:' instead; some developer also simply used footnotes.
Regzbot doesn't need a 'Reported:' and could continue to work as it does right
now -- with me continuing to educate developers, no big deal. But I wondered if
I was making the "Link: is ambiguous" problem worse. This lead to this
submissions, as I always found it a bit confusing that 'Link:' is used for
different purposes – and hence felt like I should bring this up now, as I then
can sleep well even if this bolt proposal is rejected. :-D
Obviously two new tags will force developers and maintainers to adjust habits
and scripts, so it's nothing that should be done lighthearted. But sticking with
an ambiguous Link: tag for the foreseeable future might not be the best idea
anyway, as we live in times where people analyze commits with scripts for
studies and statistics on reviews and bug reporting.
For 'Posted:' the change hopefully shouldn't be much work for people anyway, as
many just need to update their `git am` hook or switch to a hypothetical new
version of `b4` that was adjusted to place 'Reviewed:' tags instead of 'Link:'.
It's a bit more of a hassle when it comes to 'Reported:', as some people will
need to update their muscle memory. But the similarity to the 'Reported-by:' tag
(to be used in the same situation) should help here; and quite a bit of
education in this area is needed anyway (see above). And 'Link:' stays around,
so there is no harm done if it takes the world a while to adapt.
FWIW, this is already v2, as I sent v1/RFC to workflows list and LKML only to
test the waters and get some feedback. Due to that I chose to switched from the
"Reviewed:" tag I proposed in v1 to the "Posted:" in v2.
Among the feedback I got was also a suggestion from Konstantin, who proposed to
continue with the Link: tag, but add hashtags after the URL to specify what it's
about:
Link: https://bugzilla.kernel.org/show_bug.cgi?id=215101 #report
Link: https://lore.kernel.org/r/fobarbaz.5551212@localhost #review
This shouldn't break existing scripts, as that is already allowed -- but it was
hardly used, hence some scripts nevertheless might break. Downsides of this
approach IMHO are: is easy to forget these hashtags when they have to be placed
manually (e.g., in the Reported: case), require people to type more, and make a
line that often is quite long already even longer. But FWIW, it's totally fine
for me if it's decided to go down that route, then I'll adjust the patch
accordingly.
There were also a few suggestions to use tags closer to what users of Git forges
are used to, but I didn't see anything that would be a good fit. If you know
something (instead of "Posted:" maybe "MergeRequest:"?), let me know.
Furthermore, the question came up if we still need the "Reported:" tag if we
link to the report, as the information is available from the link. I left it, as
show gratitude to the reporter, which motivates people.
FWIW, If this bold proposal gets rejected, I'll simply submit the first patch of
this series to improve the documentation of the status quo.
Ciao, Thorsten
---
v2/RFC: (this version)
- split the non-controversial parts out into a preparatory patch
- s/Reviewed:/Posted:/
- a few minor changes due to review feedback from various people
- mention some of the feedback from v1 in the cover letter
v1/RFC: https://lore.kernel.org/lkml/[email protected]/
- first, *rough version* to see how this idea is received in the
community
Thorsten Leemhuis (2):
docs: 5.Posting.rst: describe Fixes: and Link: tags
docs: introduce the commit message tags 'Reported:' and 'Posted:'
Documentation/maintainer/configure-git.rst | 8 ++---
Documentation/process/5.Posting.rst | 37 ++++++++++++++++----
Documentation/process/submitting-patches.rst | 22 ++++++------
3 files changed, 46 insertions(+), 21 deletions(-)
base-commit: 065db2d90c6b8384c9072fe55f01c3eeda16c3c0
--
2.31.1
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 <[email protected]>
---
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
/me grumbles
Stupid me mixed up the the subject when editing, which should read
'Posted:' and 'Reported:', as can be seen from the body of the cover
letter and the subject of v2. Sorry.
/me wanders off to find a place to hide in shame
On 09.12.21 10:52, Thorsten Leemhuis wrote:
> [Preface: sorry, this likely will cause some bikeshedding; but I got the feeling
> I should bring this up, as my Regression tracking bot relies on the Link: tag
> and thus making its ambiguity worse]
>
> The following patch proposes to create two new tags for stating URLs in commit
> messages. They are meant to make it obvious what provided links are about. This
> is useful for both users and scripts analyzing commits, as right now they have
> no simple way to see what a provided URL is about – they thus have to guess from
> the URLs or follow each one to check.
>
> The proposed tag 'Posted:' should point to the last public review posting of the
> patch in question, while 'Reported:' is meant to be used for linking to bug
> reports. The 'Link:' tag, which until now covered these two aspects, stays
> around for other kind of links, for example for links to PDFs or webpages with
> background information relevant for the patch.
>
> This submission partly is triggered by regzbot, my Linux kernel regression
> tracking bot (https://linux-regtracking.leemhuis.info/regzbot/ ). It
> automatically marks a tracked regression as resolved when it notices a commit
> with a 'Link:' pointing to the report of the tracked regression; it also uses
> this to detect when a proposed fix is posted for review. In preparation for this
> I recently improved the kernel's documentation on 'Link:' to the best of my
> understanding in commit 1f57bd42b77c ("docs: submitting-patches: make
> section about the Link: tag more explicit"). I also started pointing out that
> usage to various people when I noticed it was missing. Quite a few developers
> didn't know that 'Link:' was supposed to be like this or completely unaware they
> were supposed to links bug reports. Developers from the DRM subsystem were using
> 'References:' instead; some developer also simply used footnotes.
>
> Regzbot doesn't need a 'Reported:' and could continue to work as it does right
> now -- with me continuing to educate developers, no big deal. But I wondered if
> I was making the "Link: is ambiguous" problem worse. This lead to this
> submissions, as I always found it a bit confusing that 'Link:' is used for
> different purposes – and hence felt like I should bring this up now, as I then
> can sleep well even if this bolt proposal is rejected. :-D
>
> Obviously two new tags will force developers and maintainers to adjust habits
> and scripts, so it's nothing that should be done lighthearted. But sticking with
> an ambiguous Link: tag for the foreseeable future might not be the best idea
> anyway, as we live in times where people analyze commits with scripts for
> studies and statistics on reviews and bug reporting.
>
> For 'Posted:' the change hopefully shouldn't be much work for people anyway, as
> many just need to update their `git am` hook or switch to a hypothetical new
> version of `b4` that was adjusted to place 'Reviewed:' tags instead of 'Link:'.
> It's a bit more of a hassle when it comes to 'Reported:', as some people will
> need to update their muscle memory. But the similarity to the 'Reported-by:' tag
> (to be used in the same situation) should help here; and quite a bit of
> education in this area is needed anyway (see above). And 'Link:' stays around,
> so there is no harm done if it takes the world a while to adapt.
>
> FWIW, this is already v2, as I sent v1/RFC to workflows list and LKML only to
> test the waters and get some feedback. Due to that I chose to switched from the
> "Reviewed:" tag I proposed in v1 to the "Posted:" in v2.
>
> Among the feedback I got was also a suggestion from Konstantin, who proposed to
> continue with the Link: tag, but add hashtags after the URL to specify what it's
> about:
>
> Link: https://bugzilla.kernel.org/show_bug.cgi?id=215101 #report
> Link: https://lore.kernel.org/r/fobarbaz.5551212@localhost #review
>
> This shouldn't break existing scripts, as that is already allowed -- but it was
> hardly used, hence some scripts nevertheless might break. Downsides of this
> approach IMHO are: is easy to forget these hashtags when they have to be placed
> manually (e.g., in the Reported: case), require people to type more, and make a
> line that often is quite long already even longer. But FWIW, it's totally fine
> for me if it's decided to go down that route, then I'll adjust the patch
> accordingly.
>
> There were also a few suggestions to use tags closer to what users of Git forges
> are used to, but I didn't see anything that would be a good fit. If you know
> something (instead of "Posted:" maybe "MergeRequest:"?), let me know.
>
> Furthermore, the question came up if we still need the "Reported:" tag if we
> link to the report, as the information is available from the link. I left it, as
> show gratitude to the reporter, which motivates people.
>
> FWIW, If this bold proposal gets rejected, I'll simply submit the first patch of
> this series to improve the documentation of the status quo.
>
> Ciao, Thorsten
>
> ---
> v2/RFC: (this version)
> - split the non-controversial parts out into a preparatory patch
> - s/Reviewed:/Posted:/
> - a few minor changes due to review feedback from various people
> - mention some of the feedback from v1 in the cover letter
>
> v1/RFC: https://lore.kernel.org/lkml/[email protected]/
> - first, *rough version* to see how this idea is received in the
> community
>
> Thorsten Leemhuis (2):
> docs: 5.Posting.rst: describe Fixes: and Link: tags
> docs: introduce the commit message tags 'Reported:' and 'Posted:'
>
> Documentation/maintainer/configure-git.rst | 8 ++---
> Documentation/process/5.Posting.rst | 37 ++++++++++++++++----
> Documentation/process/submitting-patches.rst | 22 ++++++------
> 3 files changed, 46 insertions(+), 21 deletions(-)
>
>
> base-commit: 065db2d90c6b8384c9072fe55f01c3eeda16c3c0
>
Yeah. Now that we're all using b4 then having a message-id is nice.
Perhaps this is something which could be added to patchwork so that it
can be added automatically.
regards,
dan carpenter