> these files are actually in AsciiDoc Ah, thanks, they looked like some kind of structured text format. GitHub will format them if the extension is .adoc (supposedly .ad & .asciidoc work as well), here's a POC of that, with AsciiDoc links added, to allow easy navigation to v2.30.7 release notes & out to CVEs from there: https://github.com/mrienstra/git/blob/markdown-release-notes-poc/Documentation/RelNotes/2.39.1.adoc Docs for AsciiDoc link & URL macros: https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/ https://docs.asciidoctor.org/asciidoc/latest/macros/url-macro/ > 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. Perhaps there could be two identical files, the existing ones with .txt suffixes, and copies with .adoc suffixes -- the latter could be linked to from git-scm.com, to show formatted AsciiDoc, instead of raw AsciiDoc. Assuming adding relative link macros & URL macros won't break any other consumers of the release notes. > 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. Unless I'm mistaken: Right now, release notes are only in the `git/git` repo, which is what git-scm.com links to. They are not stored in the `git/git-scm` repo. Sounds like you're suggesting either (A) migrating them to the `git/git-scm` repo, (B) having them in both repos, or (C) displaying them on git-scm.com, but the underlying files would be retrieved from the `git/git` repo as part of the build pipeline for git-scm.com (so to speak). "C" sounds like the cleanest path forward, as it wouldn't involve any duplication or breakage. On Thu, Feb 9, 2023 at 2:31 PM brian m. carlson <sandals@xxxxxxxxxxxxxxxxxxxx> wrote: > > 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. > > > 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
