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

[Jeff King]

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

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

[Kaartic Sivaraam]

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 ;-)

> Perhaps, instead, it can be re-worded a bit to make it sound something
> other than mandatory (but I can't think of a good way to phrase it;
> maybe you can?).

How about the following patch? (warning: patch only for discussion
purposes, might be white-space broken). It might be superfluous,
though.

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a1d0feca3..565bc4397 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -128,7 +128,7 @@ The body should provide a meaningful commit message, which:
 . justifies the way the change solves the problem, i.e. why the
   result with the change is better.
 
-. alternate solutions considered but discarded, if any.
+. alternate solutions considered but discarded, where necessary.
 
 [[imperative-mood]]
 Describe your changes in imperative mood, e.g. "make xyzzy do frotz"


Regards,
Sivaraam