On Sun, Jun 17, 2018 at 1:32 PM Kaartic Sivaraam <kaartic.sivar...@gmail.com> wrote: > On Friday 15 June 2018 01:13 PM, Eric Sunshine wrote: > > On Fri, Jun 15, 2018 at 2:58 AM Simon Ruderich <si...@ruderich.org> wrote: > >> Should we put the part about MacOS's make into the commit > >> message? Seems like relevant information for future readers. > > > > No. The bit of commentary mentioning MacOS's very old 'make' was just > > talking about a possible alternate way of implementing the change. > > That alternative was not chosen, so talking about old 'make' in the > > commit message would be confusing for readers. > > Interesting. Documentation/SubmittinPatches reads: > > The body should provide a meaningful commit message, which: > <snip> > . alternate solutions considered but discarded, if any. > > The consensus has changed, maybe? In which case, should we remove that > statement from there?
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. 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?).
