Re: [PATCH 6/6] format-patch --notes: show notes after three-dashes

From: Philip Oakley <philipoakley@iee.org>
Date: Oct 21, 2012, 21:33 UTC
Message-ID: <B15B2D6C9AAB43AF9D480D9DEB3D2F47@PhilipOakley>
In-Reply-To: <7vlif3l9fw.fsf@alter.siamese.dyndns.org>

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

Show 17 quoted lines

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Junio C Hamano" <gitster@pobox.com>
>>> When inserting the note after the commit log message to format-patch
>>> output, add three dashes before the note.  Record the fact that we
>>> did so in the rev_info and omit showing duplicated three dashes in
>>> the usual codepath that is used when notes are not being shown.
>>>
>>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>>
>> Should this also include a documentation update to make this
>> substantive benefit visible, whether that be in the format-patch man
>> pages, the SubmittingPatches guide, in the git-notes description of 
>> 'A
>> typical use...', or even in the user-manual?
>
> Eric Blake (http://mid.gmane.org/507EB310.8020904@redhat.com) was

Added to distribution.

Show 10 quoted lines

> already working on a documentation updates already, I thought.
>
> As long as what it does is explained in format-patch, that is fine.
>
> I do not think this deserves to be in the SubmittingPatches.  We do
> tell people to hide "here is the context of the change" additional
> explanation after three dashes, but how the submitters prepare that
> text is entirely up to them (and I personally do not think notes is
> not necessarily the right tool to do so).
>

I've prepared a short set of patches for the documenation I mentioned.

I, like Eric, feel some of the methods available are a bit of a Catch 22. We do need to at least hint about capabilities as a way of helping new users who aren't already experts (the inverse Kruger Dunning problem).

I have tried hard to make the patches concise so hopefully they will be acceptable.

Philip