Markdown release notes

Markdown release notes

[Michael Rienstra]

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?

Re: Markdown release notes

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1770 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]

Re: Markdown release notes

[Michael Rienstra]

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

Re: Markdown release notes

[Michael Rienstra]

Whoops, didn't mean to include a full quote at the bottom, sorry, my
plain text email skills are a smidge rusty.

Re: Markdown release notes

[Ævar Arnfjörð Bjarmason]

On Thu, Feb 09 2023, Michael Rienstra wrote:

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

Yes, but when we deploy git-scm.com we pull in git.git.

> Sounds like you're suggesting either (A) migrating them to the
> `git/git-scm` repo, 

Definitely not this.

> (B) having them in both repos, or 

Not this

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

Yeah, and most of that pipeline is set up already. I think it would be
valuable to render these release notes on that site. Thanks for working
on this.