From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Tue, 14 Jul 2026 22:46:05 GMT
Subject: Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message
Message-ID: <CALnO6CD8HFWaeN-4Gccopy0nw601cMyak_LSXfTsAa8xwOjKpQ@mail.gmail.com>
In-Reply-To: <alTy306FaTAe2E8w@wyuan.org>

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. 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 :)


> 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]

?

-- 
D. Ben Knoble