The following patch proposes to create two new tags for mentioning links in
commit messages. They are meant to make it obvious what provided links are
about, which is useful for both users and scripts studying commits.
The new tag 'Reported:' is meant to be used for linking to bug reports, while
'Reviewed:' should point to the last review of the patch in question. They
supplement 'Link:', which until now has been used for these two as well as other
purposes; it stays around for the latter use case, for example for links to PDFs
or webpages with background information relevant for the patch.
This submission partly got indirectly 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. In preparation
for this I recently improved the kernel's documentation on 'Link:' to the best
of my understanding in commit 1f57bd42b77c
(https://git.kernel.org/linus/1f57bd42b77c ). I also started pointing out that
usage to various people when I noticed the links were missing. Some didn't know
that 'Link:' was supposed to be like this, while developers from the DRM
subsystem were using 'References:' instead; some developer also simply used
footnotes style and there are also quite a few developers unaware they are
supposed to add links to bug reports.
I could continue down that path and further educating developers, no big deal.
But I wondered if I was making a problem worse, as I always found it a bit
confusing that 'Link:' is used for different purposes and thus ambiguous. The
situation thus made me wonder if this wouldn't be a good time to improve the
whole situation by going a step further. That's how the proposed patch (still a
bit rough) came to light.
Obviously such a change will force developers and maintainers to adjust, so it's
nothing that should be done lighthearted. But I guess in the long-run it's worth
it. And for 'Review:' the conversion shouldn't be much work for people, 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).
In both use cases there is no real harm done if it takes the world a while to
adapt, as 'Link:' stays around.
I won't mind at all if this bold move gets rejected, if that's the case I'll
simply modify the patch a bit to properly describe the 'Link:' tag in
Documentation/process/5.Posting.rst, as it's not mentioning it at all right now.
But I think proposing this was worth a shot, as having distant tags for various
types of links might be handy for other purposes in the long-run as well.
Ciao, Thorsten
P.S.: I'm sending v1/RFC to workflows list and LKML only to test the waters and
hopefully collect some supportive arguments. If this doesn't get shot down there
I'll post a v2/RFC to wider audience including Linus and Greg; not sure yet if
I'll to Cc ksummit then as well, as it would be abusing the list somewhat, but
OTOH is a good way to reach a lot of core people that might care about this.
Thorsten Leemhuis (1):
docs: add the new commit-msg tags 'Reported:' and 'Reviewed:'
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(-)
base-commit: b96ff02ab2be1791248237b1bf318aaf62e8b701
--
2.31.1
On Mon, Nov 22, 2021 at 08:33:41AM +0100, Thorsten Leemhuis wrote:
> The following patch proposes to create two new tags for mentioning links in
> commit messages. They are meant to make it obvious what provided links are
> about, which is useful for both users and scripts studying commits.
>
> The new tag 'Reported:' is meant to be used for linking to bug reports, while
> 'Reviewed:' should point to the last review of the patch in question. They
> supplement 'Link:', which until now has been used for these two as well as other
> purposes; it stays around for the latter use case, for example for links to PDFs
> or webpages with background information relevant for the patch.
As an alternative, I can offer that we continue to use Link: trailers with
extra data following the hashtag, as is already done for other trailers:
Link: https://bugzilla.kernel.org/show_bug.cgi?id=215101 #report
Link: https://lore.kernel.org/r/fobarbaz.5551212@localhost #review
Note, that this merely for completeness, not in opposition to the proposal. I
find the "Link:" trailer to be semantically redundant, since what follows is
already clearly a hyperlink. Adding "Link: " in front of it is only necessary
for consistency and machine parsing reasons.
Regards,
-K
On Mon, 22 Nov 2021 10:12:33 -0500
Konstantin Ryabitsev <[email protected]> wrote:
> As an alternative, I can offer that we continue to use Link: trailers with
> extra data following the hashtag, as is already done for other trailers:
>
> Link: https://bugzilla.kernel.org/show_bug.cgi?id=215101 #report
> Link: https://lore.kernel.org/r/fobarbaz.5551212@localhost #review
>
> Note, that this merely for completeness, not in opposition to the proposal. I
> find the "Link:" trailer to be semantically redundant, since what follows is
> already clearly a hyperlink. Adding "Link: " in front of it is only necessary
> for consistency and machine parsing reasons.
Machine parsing is the main reason for the Link: tag. I have scripts that
key off of that tag and ignore any other "http" reference.
Perhaps the above is better, as it means we don't need to update our
scripts for that parsing.
-- Steve
On 22.11.21 18:04, Steven Rostedt wrote:
> On Mon, 22 Nov 2021 10:12:33 -0500
> Konstantin Ryabitsev <[email protected]> wrote:
>
>> As an alternative, I can offer that we continue to use Link: trailers with
>> extra data following the hashtag, as is already done for other trailers:
>>
>> Link: https://bugzilla.kernel.org/show_bug.cgi?id=215101 #report
>> Link: https://lore.kernel.org/r/fobarbaz.5551212@localhost #review
>>
>> Note, that this merely for completeness, not in opposition to the proposal.
Thx, I'll mention those as a alternative in v2
>> I
>> find the "Link:" trailer to be semantically redundant, since what follows is
>> already clearly a hyperlink. Adding "Link: " in front of it is only necessary
>> for consistency and machine parsing reasons.
>
> Machine parsing is the main reason for the Link: tag. I have scripts that
> key off of that tag and ignore any other "http" reference.
>
> Perhaps the above is better, as it means we don't need to update our
> scripts for that parsing.
Hmmm. I'm not opposed, but I wonder if 'Reported:' and 'Reviewed:' are
this tiny bit easier to handle (both for placing and analyzing scripts)
that makes the difference between "nice idea, but fails to be used in
the field" and "after some tradition phase this becomes the new normal"
in the end.
Whatever, will mention that and point to this post in the next round.
Thx for the feedback!
Ciao, Thorsten
On Mon, 22 Nov 2021 19:40:46 +0100
Thorsten Leemhuis <[email protected]> wrote:
> Hmmm. I'm not opposed, but I wonder if 'Reported:' and 'Reviewed:' are
> this tiny bit easier to handle (both for placing and analyzing scripts)
> that makes the difference between "nice idea, but fails to be used in
> the field" and "after some tradition phase this becomes the new normal"
> in the end.
Either way is fine for me. My scripts are trivial and easy to update. I'm
more worried about what other people may use.
-- Steve