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: > 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?
