A policy for Link tags

Certain source-code management systems are able to track a change through multiple versions by assigning a "change ID" to the work. Git does not do that, though, so the kernel community does not have an easy way to look at the history of a patch. In a discussion prior to the 2019 Kernel Summit, Shuah Kahn asked whether the community should adopt some sort of change-ID convention to track work heading into the kernel. Doug Anderson proposed something similar a month later. The extended discussions that followed did not lead to the adoption of a change ID, but they did bring about a related change.

Specifically, Thomas Gleixner suggested the use of a Link tag that would contain an archive URL for the posting of each commit on the mailing lists:

What's really useful is when the commit has a Link tag:

   https://lore.kernel.org/lkml/$MESSAGE-ID

and if the submitters provide the same kind of link in their V(N) submission pointing to the V(N-1) in the cover letter:

    https://lore.kernel.org/lkml/$MESSAGE-ID-V(N-1)

If it's a single patch the link can be in the patch itself after the --- separator. That allows a quick lookup of the history.

The Link tag was not new; its first appearance in the kernel repository is in this 2011 commit. That commit, along with 56 others containing Link tags, went into the 2.6.39 release. This tag was mostly used for commits to the x86 and core-kernel subsystems initially, showing up in 3-500 commits per release. As this plot shows, the use of Link tags grew slowly over time, until something happened:

The "something" that happened partway through the 5.2 development cycle was, of course, the above-mentioned discussion. There seemed to be widespread agreement that the addition of Link tags to commits would be helpful. Kees Cook posted a Git hook configuration that would add the tag automatically whenever a patch was applied with git am. Linus Walleij updated the kernel documentation to suggest using this hook; the b4 tool later gained a flag to add Link tags as well. The addition of Link tags grew accordingly; in the 6.16 release, 11,030 commits (75% of the total) included Link tags.

(It is worth noting that the other part of Gleixner's suggestion — including a link to the previous posting whenever a patch series is updated — has not been adopted as widely, though many developers do indeed include those links. These backward links are important, as any LWN kernel writer will attest, if one wishes to look at the history of a change through multiple iterations.)

During the 2019 discussion, Torvalds was lukewarm to the idea of including Link tags; he certainly did not oppose it, and said it was better than trying to create some sort of change ID. By 2022, though, he was beginning to complain about them:

I _really_ wish the -tip tree had more links to the actual problem reports and explanations, rather than links to the patch submission.

One has the actual issue. The other just has the information that is already in the commit, and the "Link:" adds almost no actual value.

This refrain would become more common over the years, culminating in some strongly worded complaints in the middle of discussions on virtual filesystem layer and io_uring patch sets. The core problem remained the same: he does not like it if he follows the URL in a Link tag, hoping to learn more about the change in question, and only finds the same information that is already contained in the changelog itself. That slows his workflow down and increases his grumpiness level.

Various developers have sought to defend the use of these tags in these discussions. Christian Brauner said: "I care that I can git log at mainline and figure out where that patch was discussed, pull down the discussion via b4 or other tooling, without having to search lore". Konstantin Ryabitsev pointed out that it is not always easy to find patch submissions by searching the archives. Jens Axboe said that the tags can help to find the cover letter for a patch series, and that they can also help to turn up discussion that happens after a patch is applied. Greg Kroah-Hartman argued for keeping the tags, saying "they work well for those that have to spelunk into our git branches all the time".

Torvalds, though, has been unmoved by these arguments and steadfastly opposed to the use of Link tags except in cases where there is something "interesting" behind the link. In the recent discussions, Axboe asked repeatedly for a proclamation from Torvalds on what the rules for Link tags should actually be (and suggested summoning LWN for a summary). Torvalds appears to have answered that request in the notes for the 6.17-rc5 release:

So if a link doesn't have any extra relevant information in it, just don't add it at all in some misguided hope that tomorrow it will be useful.

Make "Link:" tags be something to celebrate, not something to curse because they are worthless and waste peoples time.

Please?

Many maintainers are unlikely to celebrate the fact that they have to end the automatic addition of Link tags and think, for each commit, whether such a tag is "interesting" or not. But they can celebrate the fact that the time spent on that exercise will save some time responding to grumpy emails from the Chief Penguin. While the new policy may not be entirely popular among maintainers, there is at least now something approaching an actual policy around the use of these tags.