From: Thorsten Leemhuis <firstname.lastname@example.org> To: email@example.com, Greg KH <firstname.lastname@example.org>, Linus Torvalds <email@example.com> Cc: firstname.lastname@example.org, Linux Kernel Mailing List <email@example.com>, Konstantin Ryabitsev <firstname.lastname@example.org>, Jonathan Corbet <email@example.com> Subject: [RFC PATCH v2 0/2] Create 'Posted:' and 'Reviewed:' tags for links in commit messages Date: Thu, 9 Dec 2021 10:52:15 +0100 [thread overview] Message-ID: <firstname.lastname@example.org> (raw) [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://email@example.com/ - 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
next reply other threads:[~2021-12-09 9:52 UTC|newest] Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-12-09 9:52 Thorsten Leemhuis [this message] 2021-12-09 9:52 ` [RFC PATCH v2 1/2] docs: 5.Posting.rst: describe Fixes: and Link: tags Thorsten Leemhuis 2021-12-09 9:52 ` [RFC PATCH v2 2/2] docs: introduce the commit message tags 'Reported:' and 'Posted:' Thorsten Leemhuis 2021-12-09 11:26 ` [RFC PATCH v2 0/2] Create 'Posted:' and 'Reported:' tags for links in commit messages Thorsten Leemhuis 2021-12-10 12:35 ` [RFC PATCH v2 0/2] Create 'Posted:' and 'Reviewed:' " Dan Carpenter
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: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [RFC PATCH v2 0/2] Create '\''Posted:'\'' and '\''Reviewed:'\'' tags for links in commit messages' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
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).