{"thread":{"id":"59220","subject":"Markdown release notes","startedAt":"2023-02-09T22:16:20Z","lastAt":"2023-02-10T13:22:18Z","messageCount":5,"participants":["Michael Rienstra","brian m. carlson","Ævar Arnfjörð Bjarmason"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"471883","messageId":"CABBAUF+acoMScQfHFQGooPx9eng2FBeb-Z2619DsnCt5QmhQPQ@mail.gmail.com","threadId":"59220","inReplyTo":null,"subject":"Markdown release notes","fromName":"Michael Rienstra","fromEmail":"mrienstra@gmail.com","sentAt":"2023-02-09T22:15:59Z","receivedAt":"2023-02-09T22:16:20Z","isPatch":false,"sender":{"key":"mrienstra@gmail.com","avatar":"https://gravatar.com/avatar/eea17b297e09ef17363c22289e22bbffad1852425e513a2fb9101e396e12b72f?d=mp&s=160"},"body":"Release notes are currently plain text files -- and that option should\nsurely remain for backwards compatibility -- but it would be nice to\nhave them in a format that facilitates cross-linking.\n\nFor example, https://git-scm.com/ currently shows:\n\n> Latest source Release\n> 2.39.1\n> Release Notes (2022-12-13)\n\n\nWhich links to:\n\n> Git v2.39.1 Release Notes\n> =========================\n>\n>\n> This release merges the security fix that appears in v2.30.7; see\n>\n> the release notes for that version for details.\n\n-- https://raw.github.com/git/git/master/Documentation/RelNotes/2.39.1.txt\n\nNavigating to the release notes for v2.30.7 is not convenient. Some\nusers will simply modify the URL, which will do the trick. Others may\nfind their way to\nhttps://github.com/git/git/tree/master/Documentation/RelNotes & search\nfor \"2.39.1\", which also works, but isn't particularly friendly.\n\nMarkdown alternative POC for the v2.39.1 release notes:\nhttps://github.com/mrienstra/git/blob/markdown-release-notes-poc/Documentation/RelNotes/2.39.1.md\n\nNow \"the security fix that appears in v2.30.7\" can be easily followed to:\nhttps://github.com/mrienstra/git/blob/markdown-release-notes-poc/Documentation/RelNotes/2.30.7.md\n\nAlong the same lines, CVE IDs could be linked out in Markdown release\nnotes, I did that in a few cases as part of this POC. For example, in\nthe v2.30.7 release notes (last link above) there is now a link to:\nhttps://nvd.nist.gov/vuln/detail/CVE-2022-41903\n\n(nvd.nist.gov seemed to be preferred over cve.org, based on a search\nof http://public-inbox.org/git)\n\nI used regex search & replace to add these links, sundry details are\nin commit messages here:\nhttps://github.com/git/git/compare/master...mrienstra:git:markdown-release-notes-poc\n\nThis seems like a simple change with no obvious side effects. I\nsuppose the Markdown files could be placed in a subfolder to prevent a\njump from 464 files to 928 in one directory.\n\nThoughts?\n"},{"id":"471885","messageId":"Y+V0Mu/v/FO5318/@tapette.crustytoothpaste.net","threadId":"59220","inReplyTo":"CABBAUF+acoMScQfHFQGooPx9eng2FBeb-Z2619DsnCt5QmhQPQ@mail.gmail.com","subject":"Re: Markdown release notes","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2023-02-09T22:31:14Z","receivedAt":"2023-02-09T22:31:21Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2023-02-09 at 22:15:59, Michael Rienstra wrote:\n> Release notes are currently plain text files -- and that option should\n> surely remain for backwards compatibility -- but it would be nice to\n> have them in a format that facilitates cross-linking.\n\nDespite the .txt extension, these files are actually in AsciiDoc, which\nis our preferred text format, just like the documentation.  AsciiDoc\ntends to work much better than Markdown for things like manual pages and\nother non-HTML forms of documentation, of which we distribute several.\n\n> For example, https://git-scm.com/ currently shows:\n> \n> > Latest source Release\n> > 2.39.1\n> > Release Notes (2022-12-13)\n> \n> \n> Which links to:\n> \n> > Git v2.39.1 Release Notes\n> > =========================\n> >\n> >\n> > This release merges the security fix that appears in v2.30.7; see\n> >\n> > the release notes for that version for details.\n> \n> -- https://raw.github.com/git/git/master/Documentation/RelNotes/2.39.1.txt\n> \n> Navigating to the release notes for v2.30.7 is not convenient. Some\n> users will simply modify the URL, which will do the trick. Others may\n> find their way to\n> https://github.com/git/git/tree/master/Documentation/RelNotes & search\n> for \"2.39.1\", which also works, but isn't particularly friendly.\n\nThis is tricky because we'd want to link to them on git-scm.com, since\nwe don't distribute solely on GitHub, and I don't know if those are\navailable there.\n\nIf you asked (or submitted a pull request) at\nhttps://github.com/git/git-scm.com to make sure they're distributed as\npart of the site, then perhaps Junio would be willing to insert a link\nor two when we have another security release.\n-- \nbrian m. carlson (he/him or they/them)\nToronto, Ontario, CA\n"},{"id":"471888","messageId":"CABBAUFKv64xhJtwRk9kMWBov=nV_QzvR-jJqhJxKQyej3pcYCQ@mail.gmail.com","threadId":"59220","inReplyTo":"Y+V0Mu/v/FO5318/@tapette.crustytoothpaste.net","subject":"Re: Markdown release notes","fromName":"Michael Rienstra","fromEmail":"mrienstra@gmail.com","sentAt":"2023-02-10T00:09:52Z","receivedAt":"2023-02-10T00:10:13Z","isPatch":false,"sender":{"key":"mrienstra@gmail.com","avatar":"https://gravatar.com/avatar/eea17b297e09ef17363c22289e22bbffad1852425e513a2fb9101e396e12b72f?d=mp&s=160"},"body":"> these files are actually in AsciiDoc\n\nAh, thanks, they looked like some kind of structured text format.\nGitHub will format them if the extension is .adoc (supposedly .ad &\n.asciidoc work as well), here's a POC of that, with AsciiDoc links\nadded, to allow easy navigation to v2.30.7 release notes & out to CVEs\nfrom there:\nhttps://github.com/mrienstra/git/blob/markdown-release-notes-poc/Documentation/RelNotes/2.39.1.adoc\n\nDocs for AsciiDoc link & URL macros:\nhttps://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/\nhttps://docs.asciidoctor.org/asciidoc/latest/macros/url-macro/\n\n> This is tricky because we'd want to link to them on git-scm.com, since\n> we don't distribute solely on GitHub, and I don't know if those are\n> available there.\n\nPerhaps there could be two identical files, the existing ones with\n.txt suffixes, and copies with .adoc suffixes -- the latter could be\nlinked to from git-scm.com, to show formatted AsciiDoc, instead of raw\nAsciiDoc. Assuming adding relative link macros & URL macros won't\nbreak any other consumers of the release notes.\n\n> If you asked (or submitted a pull request) at\n> https://github.com/git/git-scm.com to make sure they're distributed as\n> part of the site, then perhaps Junio would be willing to insert a link\n> or two when we have another security release.\n\nUnless I'm mistaken: Right now, release notes are only in the\n`git/git` repo, which is what git-scm.com links to. They are not\nstored in the `git/git-scm` repo.\n\nSounds like you're suggesting either (A) migrating them to the\n`git/git-scm` repo, (B) having them in both repos, or (C) displaying\nthem on git-scm.com, but the underlying files would be retrieved from\nthe `git/git` repo as part of the build pipeline for git-scm.com (so\nto speak). \"C\" sounds like the cleanest path forward, as it wouldn't\ninvolve any duplication or breakage.\n\n\nOn Thu, Feb 9, 2023 at 2:31 PM brian m. carlson\n<sandals@crustytoothpaste.net> wrote:\n>\n> On 2023-02-09 at 22:15:59, Michael Rienstra wrote:\n> > Release notes are currently plain text files -- and that option should\n> > surely remain for backwards compatibility -- but it would be nice to\n> > have them in a format that facilitates cross-linking.\n>\n> Despite the .txt extension, these files are actually in AsciiDoc, which\n> is our preferred text format, just like the documentation.  AsciiDoc\n> tends to work much better than Markdown for things like manual pages and\n> other non-HTML forms of documentation, of which we distribute several.\n>\n> > For example, https://git-scm.com/ currently shows:\n> >\n> > > Latest source Release\n> > > 2.39.1\n> > > Release Notes (2022-12-13)\n> >\n> >\n> > Which links to:\n> >\n> > > Git v2.39.1 Release Notes\n> > > =========================\n> > >\n> > >\n> > > This release merges the security fix that appears in v2.30.7; see\n> > >\n> > > the release notes for that version for details.\n> >\n> > -- https://raw.github.com/git/git/master/Documentation/RelNotes/2.39.1.txt\n> >\n> > Navigating to the release notes for v2.30.7 is not convenient. Some\n> > users will simply modify the URL, which will do the trick. Others may\n> > find their way to\n> > https://github.com/git/git/tree/master/Documentation/RelNotes & search\n> > for \"2.39.1\", which also works, but isn't particularly friendly.\n>\n> This is tricky because we'd want to link to them on git-scm.com, since\n> we don't distribute solely on GitHub, and I don't know if those are\n> available there.\n>\n> If you asked (or submitted a pull request) at\n> https://github.com/git/git-scm.com to make sure they're distributed as\n> part of the site, then perhaps Junio would be willing to insert a link\n> or two when we have another security release.\n> --\n> brian m. carlson (he/him or they/them)\n> Toronto, Ontario, CA\n"},{"id":"471889","messageId":"CABBAUFKAQNpNQ4mu2uDUuPod5WhQLx6pN5YyzX+TOGfFSOn1Ew@mail.gmail.com","threadId":"59220","inReplyTo":"CABBAUFKv64xhJtwRk9kMWBov=nV_QzvR-jJqhJxKQyej3pcYCQ@mail.gmail.com","subject":"Re: Markdown release notes","fromName":"Michael Rienstra","fromEmail":"mrienstra@gmail.com","sentAt":"2023-02-10T00:12:02Z","receivedAt":"2023-02-10T00:12:22Z","isPatch":false,"sender":{"key":"mrienstra@gmail.com","avatar":"https://gravatar.com/avatar/eea17b297e09ef17363c22289e22bbffad1852425e513a2fb9101e396e12b72f?d=mp&s=160"},"body":"Whoops, didn't mean to include a full quote at the bottom, sorry, my\nplain text email skills are a smidge rusty.\n"},{"id":"471918","messageId":"230210.86wn4pveny.gmgdl@evledraar.gmail.com","threadId":"59220","inReplyTo":"CABBAUFKv64xhJtwRk9kMWBov=nV_QzvR-jJqhJxKQyej3pcYCQ@mail.gmail.com","subject":"Re: Markdown release notes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2023-02-10T13:20:46Z","receivedAt":"2023-02-10T13:22:18Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Feb 09 2023, Michael Rienstra wrote:\n\n> Unless I'm mistaken: Right now, release notes are only in the\n> `git/git` repo, which is what git-scm.com links to. They are not\n> stored in the `git/git-scm` repo.\n\nYes, but when we deploy git-scm.com we pull in git.git.\n\n> Sounds like you're suggesting either (A) migrating them to the\n> `git/git-scm` repo, \n\nDefinitely not this.\n\n> (B) having them in both repos, or \n\nNot this\n\n> (C) displaying\n> them on git-scm.com, but the underlying files would be retrieved from\n> the `git/git` repo as part of the build pipeline for git-scm.com (so\n> to speak). \"C\" sounds like the cleanest path forward, as it wouldn't\n> involve any duplication or breakage.\n\nYeah, and most of that pipeline is set up already. I think it would be\nvaluable to render these release notes on that site. Thanks for working\non this.\n"}]}