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
