{"thread":{"id":"35878","subject":"[PATCH] [PATCH] Provide a release-notes man page / guide","startedAt":"2014-02-15T10:29:38Z","lastAt":"2014-02-19T18:22:09Z","messageCount":7,"participants":["Philip Oakley","Junio C Hamano","Stefan Näwe"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"234850","messageId":"1392460179-776-1-git-send-email-philipoakley@iee.org","threadId":"35878","inReplyTo":null,"subject":"[PATCH] Git release notes man page","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-02-15T10:29:38Z","receivedAt":"2014-02-15T10:29:38Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"A few days too late for the 1.9.0 release cycle :(\n\nThis responds to Stefan N�we's request for a 'git help' command that would\naccess the release notes. ($gmane/240595 17 Jan 2014).\n\nI've used the full name \"release-notes\" for the help guide rather than\nStefan's original 'git help relnotes'.\n\nThe release-notes man page lists just the notes for the current release.\nThe combined notes for all releases is nearing 15k lines.\n\nThe one formatting niggle is that the included text is column shifted\nsuch that the the raw text now starts at col 12 for the man page and\nreaches past col 80. Is there an attribute setting to not indent the\nincluded block text within a man page? It looks fine in --web format.\n\nI used the code.google link, rather than kernel.org, for the previous\nrelease notes to match the link currently used in git(1).\n\nPhilip Oakley (1):\n Provide a release-notes man page / guide\n\n Documentation/Makefile | 1 +\n Documentation/gitrelease-notes.txt | 37 +++++++++++++++++++++++++++++++++++++\n 2 files changed, 38 insertions(+)\n create mode 100644 Documentation/gitrelease-notes.txt\n\n-- \n1.8.3.msysgit.0\n"},{"id":"234849","messageId":"1392460179-776-2-git-send-email-philipoakley@iee.org","threadId":"35878","inReplyTo":"1392460179-776-1-git-send-email-philipoakley@iee.org","subject":"[PATCH] [PATCH] Provide a release-notes man page / guide","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-02-15T10:29:39Z","receivedAt":"2014-02-15T10:29:39Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Use the symlinked RelNote file as a list-block to\nact as the core of the release-notes man page.\n\nThe mantainers work load should not be affected.\n\nSigned-off-by: Philip Oakley \n---\n\nThe included lines are inset 11 spaces by the man page\nasciidoc formatting so some are more than 80 characters long.\nNo negative indent mechanism for the list block was found -\nsuggestions welcomed.\n\nThe use of the stalenotes section from git(1) was rejected.\n\nThe stalenotes, with over two hundred links, has greater than\n2 digits allowed in the trailing link list on the man page,\nso would miss the hundreds digit.\n\nAlso the html links for the \"documentation for release x.y.z\"\n(at kerenel.org) are to html files that are not actually made\nby the makefile.\n---\n Documentation/Makefile | 1 +\n Documentation/gitrelease-notes.txt | 37 +++++++++++++++++++++++++++++++++++++\n 2 files changed, 38 insertions(+)\n create mode 100644 Documentation/gitrelease-notes.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex fc6b2cf..b599b1f 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -29,6 +29,7 @@ MAN7_TXT += gitdiffcore.txt\n MAN7_TXT += gitglossary.txt\n MAN7_TXT += gitnamespaces.txt\n MAN7_TXT += gitrevisions.txt\n+MAN7_TXT += gitrelease-notes.txt\n MAN7_TXT += gittutorial-2.txt\n MAN7_TXT += gittutorial.txt\n MAN7_TXT += gitworkflows.txt\ndiff --git a/Documentation/gitrelease-notes.txt b/Documentation/gitrelease-notes.txt\nnew file mode 100644\nindex 0000000..29d9b1b\n--- /dev/null\n+++ b/Documentation/gitrelease-notes.txt\n@@ -0,0 +1,37 @@\n+gitrelease-notes(7)\n+===================\n+\n+NAME\n+----\n+gitrelease-notes - the onward progress of the stupid content tracker\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+'git help release-notes'\n+\n+DESCRIPTION\n+-----------\n+\n+Provide the release notes for the latest (possibly\n+unreleased) version of Git, that is available from 'master'\n+branch of the `git.git` repository.\n+\n+RELEASE NOTES\n+-------------\n+\n+----\n+include::../RelNotes[]\n+----\n+\n+OLDER RELEASE NOTES\n+-------------------\n+\n+Release notes for older versions are available in the Git source\n+Documentation/RelNotes/ folder. This is currently available at\n+https://code.google.com/p/git-core/source/browse/\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\n-- \n1.8.3.msysgit.0\n"},{"id":"235027","messageId":"xmqqha7wcbkz.fsf@gitster.dls.corp.google.com","threadId":"35878","inReplyTo":"1392460179-776-1-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] Git release notes man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-02-18T22:14:52Z","receivedAt":"2014-02-18T22:14:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> A few days too late for the 1.9.0 release cycle :(\n>\n> This responds to Stefan Nwe's request for a 'git help' command that would\n> access the release notes. ($gmane/240595 17 Jan 2014).\n>\n> I've used the full name \"release-notes\" for the help guide rather than\n> Stefan's original 'git help relnotes'.\n>\n> The release-notes man page lists just the notes for the current release.\n> The combined notes for all releases is nearing 15k lines.\n\nRelNotes are incremental and only useful for those who know what the\nimmediately previous release contained, but for most people who get\ntheir Git from distros, I have this impression that the versions of\nGit they get skip versions, and seeing the notable changes since the\nprevious source release will not give them wrong information---they\nmay have this warm fuzzy feeling that they know what is going on,\nbut they are missing information on all the accumulated changes that\nwere added in earlier versions their distro skipped---these changes\nare still in the version they are running. I do not understand why\nit is even a good idea to show release notes from the command line\n\"git\" interface.\n"},{"id":"235030","messageId":"1EC26D492ABB45FF8C399F84B1E30817@PhilipOakley","threadId":"35878","inReplyTo":"xmqqha7wcbkz.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Git release notes man page","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2014-02-18T22:46:10Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> A few days too late for the 1.9.0 release cycle :(\n>>\n>> This responds to Stefan Nwe's request for a 'git help' command that \n>> would\n>> access the release notes. ($gmane/240595 17 Jan 2014).\n>>\n>> I've used the full name \"release-notes\" for the help guide rather \n>> than\n>> Stefan's original 'git help relnotes'.\n>>\n>> The release-notes man page lists just the notes for the current \n>> release.\n>> The combined notes for all releases is nearing 15k lines.\n>\n> RelNotes are incremental and only useful for those who know what the\n> immediately previous release contained, but for most people who get\n> their Git from distros, I have this impression that the versions of\n> Git they get skip versions, and seeing the notable changes since the\n> previous source release will not give them wrong information---they\n> may have this warm fuzzy feeling that they know what is going on,\n> but they are missing information on all the accumulated changes that\n> were added in earlier versions their distro skipped---these changes\n> are still in the version they are running.\n\nThat's a reasonable argument. I did look at trying to get the \n\"stalenotes\" to work as an alternative, that is extract the stalenotes \nsection from the git.txt, and create a release notes man page from that. \nHowever there were two issues there that I couldn't solve (noted in the \ncover letter).\n\nThe first is that the man page generator does not expect more than 99 \nreferences so the link numbers repeat themselves. I'm sure that is \nfixable by someone who knows the insides of acsiidoc.\n\nThe other was that the links for the main version documentation appear \nto been to be made at kernel.org, so that links back there are created. \nAgain I wasn't sure how that should be resolved.\n\n> I do not understand why\n> it is even a good idea to show release notes from the command line\n> \"git\" interface.\n\nMy looking at this came from Stefan's suggestion noted above \n$gmane/240595. So it had at least one follower ;-)\n\nPhilip\n-- \n"},{"id":"235036","messageId":"xmqqtxbwaund.fsf@gitster.dls.corp.google.com","threadId":"35878","inReplyTo":"xmqqha7wcbkz.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] Git release notes man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-02-18T23:05:58Z","receivedAt":"2014-02-18T23:05:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Philip Oakley writes:\n>\n>> A few days too late for the 1.9.0 release cycle :(\n>>\n>> This responds to Stefan Nwe's request for a 'git help' command that would\n>> access the release notes. ($gmane/240595 17 Jan 2014).\n>>\n>> I've used the full name \"release-notes\" for the help guide rather than\n>> Stefan's original 'git help relnotes'.\n>>\n>> The release-notes man page lists just the notes for the current release.\n>> The combined notes for all releases is nearing 15k lines.\n>\n> RelNotes are incremental and only useful for those who know what the\n> immediately previous release contained, but for most people who get\n> their Git from distros, I have this impression that the versions of\n> Git they get skip versions, and seeing the notable changes since the\n> previous source release will not give them wrong information---they\n\nEhh,, s/will not give them/will give them/; obviously...\n\n> may have this warm fuzzy feeling that they know what is going on,\n> but they are missing information on all the accumulated changes that\n> were added in earlier versions their distro skipped---these changes\n> are still in the version they are running. I do not understand why\n> it is even a good idea to show release notes from the command line\n> \"git\" interface.\n"},{"id":"235049","messageId":"53047431.7070909@atlas-elektronik.com","threadId":"35878","inReplyTo":"1EC26D492ABB45FF8C399F84B1E30817@PhilipOakley","subject":"Re: [PATCH] Git release notes man page","fromName":"Stefan Näwe","fromEmail":"stefan.naewe@atlas-elektronik.com","sentAt":"2014-02-19T09:06:57Z","receivedAt":"2014-02-19T09:06:57Z","isPatch":true,"sender":{"key":"stefan.naewe@gmail.com","avatar":"https://avatars.githubusercontent.com/u/4468?v=4"},"body":"Am 18.02.2014 23:54, schrieb Philip Oakley:\n> From: \"Junio C Hamano\" \n>> I do not understand why\n>> it is even a good idea to show release notes from the command line\n>> \"git\" interface.\n> \n> My looking at this came from Stefan's suggestion noted above \n> $gmane/240595. So it had at least one follower ;-)\n\nYes, but I could definitely live without it.\nI compile git myself on most systems and that would just be a\nconvenient way to get an overview of the latest changes.\n\nRegards,\n Stefan\n-- \n----------------------------------------------------------------\n/dev/random says: It is bad luck to be superstitious.\npython -c \"print '73746566616e2e6e616577654061746c61732d656c656b74726f6e696b2e636f6d'.decode('hex')\"\n"},{"id":"235058","messageId":"xmqqha7v9d4e.fsf@gitster.dls.corp.google.com","threadId":"35878","inReplyTo":"1EC26D492ABB45FF8C399F84B1E30817@PhilipOakley","subject":"Re: [PATCH] Git release notes man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-02-19T18:22:09Z","receivedAt":"2014-02-19T18:22:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n>> RelNotes are incremental and only useful for those who know what the\n>> immediately previous release contained, but for most people who get\n>> their Git from distros, I have this impression that the versions of\n>> Git they get skip versions, and seeing the notable changes since the\n>> previous source release will not give them wrong information---they\n>> may have this warm fuzzy feeling that they know what is going on,\n>> but they are missing information on all the accumulated changes that\n>> were added in earlier versions their distro skipped---these changes\n>> are still in the version they are running.\n>\n> That's a reasonable argument.\n\nI am not making an \"argument\" in order to reject the notion of\nmaking release-notes available, though. I am only raising concerns,\npointing out why showing a single release notes as if that were the\nonly one that matter is misleading.\n\nI am not opposed to the idea of making release notes available to\nthose who do not install from the source, by the way. Being able to\ngrep the release notes through may help people who are writing\nscripts using Git to learn when a feature they want to use appeared\nto make sure that they do not depend on something their users may\nnot have yet. But for that kind of users, it would be more helpful\nto point them at the file location they can find the plain text\nversion of release notes, instead of giving them a bunch of web\nlinks they need to read through page by page.\n\n> I did look at trying to get the\n> \"stalenotes\" to work as an alternative, that is extract the stalenotes\n> section from the git.txt, and create a release notes man page from\n> that.\n\nI am not sure if stale-notes section meshes well with this; the\nprimary purpose of it was to point at the whole documentation set,\nnot just release-notes, for versions previously released, so those\nwho came to a website that hosts them can pick the version, possibly\na stale one, that they are using and read the manual pages for that\nversion, without seeing newer features that are not available to\nthem. I do not think it is very useful in the context of your \"You\nreceived this single version of software, and you can access its\ndocumentation off-line\" feature---you cannot reasonably expect that\nsuch a software release to contain all the past documentation sets,\nbut even if you could do so, that is not how normal people use the\ninstalled documentation, i.e. to learn about older releases that\nthey no longer have.\n"}]}