Re: Markdown release notes

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Feb 9, 2023, 22:31 UTC
Message-ID: <Y+V0Mu/v/FO5318/@tapette.crustytoothpaste.net>
In-Reply-To: <CABBAUF+acoMScQfHFQGooPx9eng2FBeb-Z2619DsnCt5QmhQPQ@mail.gmail.com>

On 2023-02-09 at 22:15:59, Michael Rienstra wrote:

> Release notes are currently plain text files -- and that option should
> surely remain for backwards compatibility -- but it would be nice to
> have them in a format that facilitates cross-linking.

Despite the .txt extension, these files are actually in AsciiDoc, which is our preferred text format, just like the documentation. AsciiDoc tends to work much better than Markdown for things like manual pages and other non-HTML forms of documentation, of which we distribute several.

Show 24 quoted lines

> For example, https://git-scm.com/ currently shows:
> 
> > Latest source Release
> > 2.39.1
> > Release Notes (2022-12-13)
> 
> 
> Which links to:
> 
> > Git v2.39.1 Release Notes
> > =========================
> >
> >
> > This release merges the security fix that appears in v2.30.7; see
> >
> > the release notes for that version for details.
> 
> -- https://raw.github.com/git/git/master/Documentation/RelNotes/2.39.1.txt
> 
> Navigating to the release notes for v2.30.7 is not convenient. Some
> users will simply modify the URL, which will do the trick. Others may
> find their way to
> https://github.com/git/git/tree/master/Documentation/RelNotes & search
> for "2.39.1", which also works, but isn't particularly friendly.

This is tricky because we'd want to link to them on git-scm.com, since we don't distribute solely on GitHub, and I don't know if those are available there.

If you asked (or submitted a pull request) at https://github.com/git/git-scm.com to make sure they're distributed as part of the site, then perhaps Junio would be willing to insert a link or two when we have another security release.

-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA