Markdown release notes

From: Michael Rienstra <mrienstra@gmail.com>
Date: Feb 9, 2023, 22:15 UTC
Message-ID: <CABBAUF+acoMScQfHFQGooPx9eng2FBeb-Z2619DsnCt5QmhQPQ@mail.gmail.com>

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.

For example, https://git-scm.com/ currently shows:

> Latest source Release
> 2.39.1
> Release Notes (2022-12-13)

Which links to:

Show 7 quoted lines

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

Markdown alternative POC for the v2.39.1 release notes: https://github.com/mrienstra/git/blob/markdown-release-notes-poc/Documentation/RelNotes/2.39.1.md

Now "the security fix that appears in v2.30.7" can be easily followed to: https://github.com/mrienstra/git/blob/markdown-release-notes-poc/Documentation/RelNotes/2.30.7.md

Along the same lines, CVE IDs could be linked out in Markdown release notes, I did that in a few cases as part of this POC. For example, in the v2.30.7 release notes (last link above) there is now a link to: https://nvd.nist.gov/vuln/detail/CVE-2022-41903

(nvd.nist.gov seemed to be preferred over cve.org, based on a search of http://public-inbox.org/git)

I used regex search & replace to add these links, sundry details are in commit messages here: https://github.com/git/git/compare/master...mrienstra:git:markdown-release-notes-poc

This seems like a simple change with no obvious side effects. I suppose the Markdown files could be placed in a subfolder to prevent a jump from 464 files to 928 in one directory.

Thoughts?