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

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Oct 6, 2026, 16:38 UTC
Message-ID: <c85f5906-630b-4335-a7ae-09af665bb335@app.fastmail.com>
In-Reply-To: <xmqq8q4ew604.fsf@gitster.g>

On Sun, Oct 4, 2026, at 04:31, Junio C Hamano wrote:

Show 18 quoted lines

> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>>>[snip]
>>
>> 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.

Surprised I was not.

Show 12 quoted lines

>
> 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.

Yes, I find it frustrating to read Gmane-era list messages.

But now these references are already forever in the Git history. So even if I end up obfuscating them with a URL encoding, it will be clear from the history... for those who go to the trouble of looking.

But see later in this message about how to retain the original msg-ids.

Show 7 quoted lines

> 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.

Yeah I suspected that email-only users would have such a slick setup. Thanks for explaining.

Show 7 quoted lines

> 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).

What if we used footnotes for all of the original msg-ids?

    <URL>[1]

    [...]

    [1]: <msg-id>

Or maybe just for the ones that need URL encoding? I personally think it would be better to use them for all if we go for this approach.

>[snip]