Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message

From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Jul 14, 2026, 22:46 UTC
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]

Show 8 quoted lines

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

Show 11 quoted lines

> 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