From: Philip Oakley Date: Sun, 21 Oct 2012 21:33:54 GMT Subject: Re: [PATCH 6/6] format-patch --notes: show notes after three-dashes Message-ID: In-Reply-To: <7vlif3l9fw.fsf@alter.siamese.dyndns.org> From: "Junio C Hamano" > "Philip Oakley" writes: > >> From: "Junio C Hamano" >>> 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 >> >> 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. > 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