Re: [RFC PATCH 2/4] doc: gitbreaking-changes: replace msg-ids with URLs

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 4, 2026, 02:31 UTC
Message-ID: <xmqq8q4ew604.fsf@gitster.g>
In-Reply-To: <533e2f52-2c9c-459a-9fa1-dff3ef4bb2f9@app.fastmail.com>

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

Show 14 quoted lines

>> Having said that, I am somewhat negative on what this particular
>> patch does.  We should instead give both, having something like
>>
>>  cf.
>> https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/[<xmqqa59i45wc.fsf@gitster.g>^]
>>
>> in the source, and render a readable link text with reachable href
>> when shown in the browser.
>
> With that I get a regular `href` and a `mailto` href.
>
>     <div class="paragraph"><p>cf. <a href="https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g/">&lt;<a href="mailto:xmqqa59i45wc.fsf@gitster.g">xmqqa59i45wc.fsf@gitster.g</a>&gt;^</a></p></div>
>
> The `mailto` wins and prepares to send an email.

Ouch.

Our primary goal is to give readers ready access to the messages we refer to. With that mailto glitch, it would be unusable, so let's scrap the idea of using the Message-ID as the link text for the link that leads to the lore archive, unless we can tell Asciidoctor to do what we want. Quite honestly, I did not know Asciidoctor was that broken.

Also, if readers do not recognize "Message-ID used as link text" as clickable links, that also defeats the purpose.

The secondary goal of my suggestion was to avoid repeating the disaster we faced after gmane stopped offering HTTP access to its archive. We ended up with a bunch of references like $gmane/217 to refer to their article numbers in our historical commit log messages, and of course, once we could no longer rely on them, we had no way of knowing what message article 217 referred to [*]. The URL to the lore archive does contain an encoded Message-ID, so the situation is much better than that of gmane from long ago. However, if you live in an environment where it is easier to feed the Message-ID directly to your e-mail program or newsreader than having to visit the web and then come back to your e-mail environment to continue your work, having a readily cut-and-pasteable Message-ID that is not encoded as part of a URL is definitely superior to having the lore URL alone.

But the important point is that this was a secondary goal. If the format using Message-IDs as link texts to go to the lore archive does not work (either because we cannot bypass the mailto behavior, or because readers would not recognize that Message-IDs are clickable links), I am perfectly fine with leaving only the HTTP link that is so obviously a URL (even though I find them rather ugly, but I am not the primary target audience).

Thanks for testing this and finding the issues before we went too far.

[References]

 * It is <Pine.LNX.4.58.0504150753440.7211@ppc970.osdl.org>, which I
   think is still one of the most important messages on the list ;-)