* Markdown release notes @ 2023-02-09 22:15 Michael Rienstra 2023-02-09 22:31 ` brian m. carlson 0 siblings, 1 reply; 5+ messages in thread From: Michael Rienstra @ 2023-02-09 22:15 UTC (permalink / raw) To: git 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? ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Markdown release notes 2023-02-09 22:15 Markdown release notes Michael Rienstra @ 2023-02-09 22:31 ` brian m. carlson 2023-02-10 0:09 ` Michael Rienstra 0 siblings, 1 reply; 5+ messages in thread From: brian m. carlson @ 2023-02-09 22:31 UTC (permalink / raw) To: Michael Rienstra; +Cc: git [-- 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 --] ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Markdown release notes 2023-02-09 22:31 ` brian m. carlson @ 2023-02-10 0:09 ` Michael Rienstra 2023-02-10 0:12 ` Michael Rienstra 2023-02-10 13:20 ` Ævar Arnfjörð Bjarmason 0 siblings, 2 replies; 5+ messages in thread From: Michael Rienstra @ 2023-02-10 0:09 UTC (permalink / raw) To: brian m. carlson; +Cc: git > 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Markdown release notes 2023-02-10 0:09 ` Michael Rienstra @ 2023-02-10 0:12 ` Michael Rienstra 2023-02-10 13:20 ` Ævar Arnfjörð Bjarmason 1 sibling, 0 replies; 5+ messages in thread From: Michael Rienstra @ 2023-02-10 0:12 UTC (permalink / raw) To: brian m. carlson; +Cc: git Whoops, didn't mean to include a full quote at the bottom, sorry, my plain text email skills are a smidge rusty. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Markdown release notes 2023-02-10 0:09 ` Michael Rienstra 2023-02-10 0:12 ` Michael Rienstra @ 2023-02-10 13:20 ` Ævar Arnfjörð Bjarmason 1 sibling, 0 replies; 5+ messages in thread From: Ævar Arnfjörð Bjarmason @ 2023-02-10 13:20 UTC (permalink / raw) To: Michael Rienstra; +Cc: brian m. carlson, git 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. ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2023-02-10 13:22 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2023-02-09 22:15 Markdown release notes Michael Rienstra 2023-02-09 22:31 ` brian m. carlson 2023-02-10 0:09 ` Michael Rienstra 2023-02-10 0:12 ` Michael Rienstra 2023-02-10 13:20 ` Ævar Arnfjörð Bjarmason
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).