From: Weijie Yuan <wy@wyuan.org>
Date: Fri, 17 Jul 2026 12:42:53 GMT
Subject: Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message
Message-ID: <alojTem4a5q1Xu4X@wyuan.org>
In-Reply-To: <CALnO6CD8HFWaeN-4Gccopy0nw601cMyak_LSXfTsAa8xwOjKpQ@mail.gmail.com>

On Tue, Jul 14, 2026 at 06:46:05PM -0400, D. Ben Knoble wrote:
> On Mon, Jul 13, 2026 at 10:42 AM Weijie Yuan <wy@wyuan.org> wrote:
> >
> [snip]
> > I think this might confuse readers. Now you place these points in
> > parallel:
> >
> >  1. Title
> >  2. Body
> >  3. Observation (The Status Quo)
> >  4. Solution Design (The Approach)
> >  5. Implementation (The Execution)
> 
> Without commenting on "confuse," I find this style of heading
> 
>     Thing (The Other Thing)
> 
> needlessly suggests an LLM's involvement with the text.

Aha, kind of. But I guess Junio didn't use LLM here ;-)

> That by itself is not grounds for my objection; instead, I'll note
> that often the parenthetical restates the original header in some way.
> That makes it redundant. (In some cases in the wild I have seen
> examples where the 2 were not synonymous, which _is_ confusing :)

True.

> > But acatually you mean:
> >
> > 1. Title
> > 2. Body
> >    The body typically follows three parts:
> >    a. Observation
> >    b. Solution Design
> >    c. Implementation
> >
> > But I haven't written much about adoc, so I don't know its syntax and
> > how to write it.
> 
> This is nice. If I had to suggest anything further, it would be "don't
> be afraid of long headings":
> 
> 1. Title: Summarize the change
> 2. Body: Describe [Justify?] the change
>     a. Observe the status quo
>     b. Explain your approach [solution/design/etc.]
>     c. Command the code to change [or: Describe the implementation/execution]
> 
> ?

I agree. More explanatory descriptions here are very likely to enable
contributors to express their ideas more clearly and understandably.