Re: Doc/SubmittingPatches: re-phrashing a sentence about alternate solutions (was Re: [PATCH] Makefile: make NO_ICONV really mean "no iconv")

[Jeff King <peff@peff.net>]

On Sun, Jun 17, 2018 at 11:55:33PM +0530, Kaartic Sivaraam wrote:

> On Sun, 2018-06-17 at 14:00 -0400, Eric Sunshine wrote:
> > Whether or not to talk about alternate solutions in the commit message
> > is a judgment call. Same for deciding what belongs in the commit
> > message proper and what belongs in the "commentary" section of a
> > patch. A patch author should strive to convey the problem succinctly
> > in the commit message, to not overload the reader with unnecessary (or
> > confusing) information, while, at the same time, not be sparing with
> > information which is genuinely needed to understand the problem and
> > solution.
> > 
> > Often, this can be done without talking about alternatives; often even
> > without spelling out the solution in detail or at all since the
> > solution may be "obvious", given a well-written problem description.
> > Complex cases, or cases in which multiple solutions may be or seem
> > valid, on the other hand, might warrant talking about those alternate
> > solutions, so we probably don't want to drop that bullet point.
> 
> Well explained, thanks. (Thinking out loud, it might be even nice to
> including the above paragraphs into Documentation/SubmittingPatches as
> I find it to be more "humane" than the terse bullets. But I refrained
> from doing so as the document is already a bit too-long ;-)

Yes, the first paragraph especially. The _most_ important thing is
writing well with consideration for your readers. All the other rules
are really guidelines to help you remember how to do that. When in
doubt follow the guidelines, but it's OK to break them if it serves the
ultimate purpose.

All IMHO, of course. :)

-Peff