Re: [PATCH] Git release notes man page

From: Philip Oakley <philipoakley@iee.org>
Date: Feb 18, 2014, 22:46 UTC
Message-ID: <1EC26D492ABB45FF8C399F84B1E30817@PhilipOakley>
In-Reply-To: <xmqqha7wcbkz.fsf@gitster.dls.corp.google.com>

From: "Junio C Hamano" <gitster@pobox.com>

Show 25 quoted lines

> Philip Oakley <philipoakley@iee.org> writes:
>
>> A few days too late for the 1.9.0 release cycle :(
>>
>> This responds to Stefan Nwe's request for a 'git help' command that 
>> would
>> access the release notes. ($gmane/240595 17 Jan 2014).
>>
>> I've used the full name "release-notes" for the help guide rather 
>> than
>> Stefan's original 'git help relnotes'.
>>
>> The release-notes man page lists just the notes for the current 
>> release.
>> The combined notes for all releases is nearing 15k lines.
>
> RelNotes are incremental and only useful for those who know what the
> immediately previous release contained, but for most people who get
> their Git from distros, I have this impression that the versions of
> Git they get skip versions, and seeing the notable changes since the
> previous source release will not give them wrong information---they
> may have this warm fuzzy feeling that they know what is going on,
> but they are missing information on all the accumulated changes that
> were added in earlier versions their distro skipped---these changes
> are still in the version they are running.

That's a reasonable argument. I did look at trying to get the "stalenotes" to work as an alternative, that is extract the stalenotes section from the git.txt, and create a release notes man page from that. However there were two issues there that I couldn't solve (noted in the cover letter).

The first is that the man page generator does not expect more than 99 references so the link numbers repeat themselves. I'm sure that is fixable by someone who knows the insides of acsiidoc.

The other was that the links for the main version documentation appear to been to be made at kernel.org, so that links back there are created. Again I wasn't sure how that should be resolved.

>   I do not understand why
> it is even a good idea to show release notes from the command line
> "git" interface.

My looking at this came from Stefan's suggestion noted above $gmane/240595. So it had at least one follower ;-)

Philip