Re: [PATCH] Makefile: make NO_ICONV really mean "no iconv"

From: Eric Sunshine <sunshine@sunshineco.com>
To: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Cc: simon@ruderich.org, Git List <git@vger.kernel.org>,
	Mahmoud Al-Qudsi <mqudsi@neosmart.net>
Subject: Re: [PATCH] Makefile: make NO_ICONV really mean "no iconv"
Date: Sun, 17 Jun 2018 14:00:26 -0400	[thread overview]
Message-ID: <CAPig+cTMEfu=x2dhUww3x2uk9-ANAK6eepC3hOsx4FE+1jTgBA@mail.gmail.com> (raw)
In-Reply-To: <a079d636-e70d-f383-ae87-ab890a636441@gmail.com>

On Sun, Jun 17, 2018 at 1:32 PM Kaartic Sivaraam
<kaartic.sivaraam@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 <simon@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?).