archive mirror
 help / color / mirror / Atom feed
From: Thorsten Leemhuis <>
To: Jonathan Corbet <>,
Cc: Linux Kernel Mailing List <>,
	Konstantin Ryabitsev <>
Subject: Re: [RFC PATCH v1 1/1] docs: add the new commit-msg tags 'Reported:' and 'Reviewed:'
Date: Tue, 30 Nov 2021 14:10:27 +0100	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

On 29.11.21 23:16, Jonathan Corbet wrote:
> Thorsten Leemhuis <> writes:
>> Introduce the tags 'Reported:' and 'Reviewed:' in addition to 'Link:',
>> as the latter is overloaded and hence doesn't indicate what the provided
>> URL is about. Documenting these also provides clarity, as a few
>> developers have used 'References:' to point to problem reports;
>> nevertheless 'Reported:' was chosen for this purpose, as it perfectly
>> matches up with the 'Reported-by:' tag commonly used already and needed
>> in this situation already.
>> Signed-off-by: Thorsten Leemhuis <>
>> To:
> Thanks for flooding my inbox during a holiday week :)

We didn't have one here. :-D But hey, it wasn't out of envy, I'm a
little ignorant to local holiday/festival seasons, too.

>  Just looking at this now.
>> v1/RFC:
>> - first, *rough version* to see how this idea is received in the
>>   community
>> ---
>>  Documentation/maintainer/configure-git.rst   |  6 +--
>>  Documentation/process/5.Posting.rst          | 54 ++++++++++++++------
>>  Documentation/process/submitting-patches.rst | 22 ++++----
>>  3 files changed, 53 insertions(+), 29 deletions(-)
>> diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst
>> index 80ae5030a590..8429d45d661c 100644
>> --- a/Documentation/maintainer/configure-git.rst
>> +++ b/Documentation/maintainer/configure-git.rst
>> @@ -40,12 +40,12 @@ Creating commit links to
>>  The web site is meant as a grand archive of all mail
>>  list traffic concerning or influencing the kernel development. Storing archives
>>  of patches here is a recommended practice, and when a maintainer applies a
>> -patch to a subsystem tree, it is a good idea to provide a Link: tag with a
>> +patch to a subsystem tree, it is a good idea to provide a Reviewed: tag with a
>>  reference back to the lore archive so that people that browse the commit
>>  history can find related discussions and rationale behind a certain change.
>>  The link tag will look like this:
>> -    Link:<message-id>
>> +    Reviewed:<message-id>
> The *link* tag will look like that?

Ha, good point, will fix that.

> [...]
>> +The tags in common use are:
>> +
>> + - ``Reported:`` points to a report of a problem fixed by this patch. The
>> +   provided URL thus might point to a entry in a bug tracker or a mail in a
>> +   mailing list archive. Typically this tag is followed by a "Reported-by:"
>> +   tag (see below).
>> +
>> + - ``Link:`` points to websites providing additional backgrounds or details,
>> +   for example a document with a specification implemented by the patch.
> So this is a serious change from how Link: is used now, and runs counter
> to the scripts used by a lot of maintainers.  I suspect that this thread
> is only as short as it is because a lot of people haven't seen this yet;
> it could be a hard change to sell.

Yeah, I'm aware of that. And to be honest: I don't have a strong
interest in this, just think it might be the right thing to do. And I
just got the impression that regzbot's dependence on the Link: tag for
linking to regression reports is making the ambiguity of the tag worse.
That lead to the thought: well, simply bring it up now and see what
people think; if they don't like it, I can tell myself "well, I tried to
improve it, but it was not welcomed" and sleep well at night. At least
as long as my cat allows me to. :-)

> Also, I think that documents like specs should be called out separately
> in the changelog, with text saying what they actually are.

I wonder a little if that is worth the trouble, but hey, why not, fine
with me.

>> + - ``Reviewed:`` ignore this, as maintainers add it when applying a patch, to
>> +   make the commit point to the latest public review of the patch.
> Another question would be: what's the interplay between the (quite
> similar) "Reviewed" and "Reviewed-by" tags (and the same for the report
> tags).

Hmmm, I liked the interplay for Reported/Reported-by, but yeah, for
Reviewed/Reviewed-by I see the problem now.

>  If there's a "Reviewed" do we still need "Reviewed-by"?  That
> should be spelled out, whichever way is wanted.

I didn't want to undermine or obsolete "Reviewed-by" at all. I sometimes
wonder if this and "Tested-by" should be stored somewhere else (in "git
notes" or something), so they can be extended after a change got
committed -- but that's a whole different topic and something I'm even
less interested in driving forward. :-D

Maybe "Reviewed" was simply the wrong term. Maybe "Review:", "Posted:",
or "MergeRequest:" would be better in general and avoid this problem.

> I do worry that the similarity is going to lead to a certain amount of
> confusion and use of the wrong tag.  People have a hard time getting all
> the tags we have now right; adding more that look almost like the
> existing ones seems like a recipe for trouble.
> For these reasons, I would be more inclined toward Konstantin's
> suggestion of adding notes to the existing Link: tags.

Yeah, maybe, but that results in long lines and forces people to type more.

>> +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
>>  The tags in common use are:
>> - - Signed-off-by: this is a developer's certification that he or she has
>> + - ``Signed-off-by:`` is a developer's certification that he or she has
> So this markup addition is a separate change that would belong in its
> own patch.


>  Do we really need it, though?  It clutters the text and
> irritates the anti-RST minority (which has been mercifully quiet
> recently) without really adding any benefit.

I'm not strongly attached to it. I added it after I noticed that it's at
least for me slightly unclear if the colon is part of the tag or used to
precede the explanation for the tag (in the 'Signed-off-by' case it's
both at the same time). And after adding the proposed tags the html view
imho looked a lot better.

Thx for the feedback!

Ciao, Thorsten

  reply	other threads:[~2021-11-30 13:10 UTC|newest]

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-11-22  7:33 [RFC PATCH v1 0/1] Create 'Reported:' and 'Reviewed:' tags for links in commit messages Thorsten Leemhuis
2021-11-22  7:33 ` [RFC PATCH v1 1/1] docs: add the new commit-msg tags 'Reported:' and 'Reviewed:' Thorsten Leemhuis
2021-11-22 16:29   ` Steven Rostedt
2021-11-22 18:50     ` Thorsten Leemhuis
2021-11-22 20:24       ` Steven Rostedt
2021-11-23  8:53         ` Thorsten Leemhuis
2021-11-23 18:52   ` Eric Wong
2021-11-24  1:37     ` Junio C Hamano
2021-11-24  6:12       ` Eric Wong
2021-11-26 12:49       ` Ævar Arnfjörð Bjarmason
2021-11-24  2:08     ` Ævar Arnfjörð Bjarmason
2021-11-26  7:29     ` Thorsten Leemhuis
2021-11-26 17:11       ` Eric Wong
2021-11-27 19:32         ` Thorsten Leemhuis
2021-11-27 19:52           ` Eric Wong
2021-11-27 20:20             ` Junio C Hamano
2021-11-29 12:03               ` Jani Nikula
2021-11-29 17:10                 ` Steven Rostedt
2021-11-29 17:18                 ` Junio C Hamano
2021-11-29 19:18                   ` Jani Nikula
2021-11-29 17:26                 ` Eric Wong
2021-11-29 19:20                   ` Jani Nikula
2021-11-30  8:24                   ` Geert Uytterhoeven
2021-12-08 13:41                     ` Thorsten Leemhuis
2021-12-08 17:02                       ` Eric Wong
2021-11-29 22:16   ` Jonathan Corbet
2021-11-30 13:10     ` Thorsten Leemhuis [this message]
2021-12-01 12:24       ` Geert Uytterhoeven
2021-11-22 15:12 ` [RFC PATCH v1 0/1] Create 'Reported:' and 'Reviewed:' tags for links in commit messages Konstantin Ryabitsev
2021-11-22 17:04   ` Steven Rostedt
2021-11-22 18:40     ` Thorsten Leemhuis
2021-11-22 18:48       ` Steven Rostedt

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:

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

  git send-email \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).