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
