Re: Markdown release notes

From: Michael Rienstra <mrienstra@gmail.com>
Date: Feb 10, 2023, 00:09 UTC
Message-ID: <CABBAUFKv64xhJtwRk9kMWBov=nV_QzvR-jJqhJxKQyej3pcYCQ@mail.gmail.com>
In-Reply-To: <Y+V0Mu/v/FO5318/@tapette.crustytoothpaste.net>

> 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@crustytoothpaste.net> wrote:

Show 47 quoted lines

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