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

[Weijie Yuan <wy@wyuan.org>]

On Sat, Jul 11, 2026 at 12:26:45PM -0700, Junio C Hamano wrote:
> The current text on log message has lots of justification and
> rationale before telling contributors what exactly is expected of
> them.

Nit: s/message/messages/ ?

> Simplify the rationale section and jump straight to what to write
> and how.

> [...]

> +Reviewers will evaluate your commit message for clarity and structure.
> +A well-structured commit message typically follows a three-part flow:
> +**Observation**, **Solution**, and **Command**.
>  
> -. justifies the way the change solves the problem, i.e. why the
> -  result with the change is better.
> -
> -. alternate solutions considered but discarded, if any.
> +[[meaningful-message]]
> +==== Structure of a Commit Message
>  
> -. records the resolution of design or viability concerns raised by the
> -  community during the review, if any, ensuring the historical record
> -  explains why the chosen approach was accepted over alternatives.
> +0. **Title**:
> +   The first line of the commit log message is the title that lets
> +   readers of `git log --oneline` quickly understand what area the
> +   commit touches and what problem it addresses.
>  
> +1. **Observation (The Status Quo)**:
> +   Explain the problem you are trying to solve.  Describe what is
> +   wrong with the current code *without* your change.
> ++
>  [[present-tense]]
> -The problem statement that describes the status quo is written in the
> -present tense.  Write "The code does X when it is given input Y",
> -instead of "The code used to do Y when given input X".  You do not
> -have to say "Currently"---the status quo in the problem statement is
> -about the code _without_ your change, by project convention.
> -
> -[[imperative-mood]]
> -Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
> -instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
> -to do frotz", as if you are giving orders to the codebase to change
> -its behavior.  Try to make sure your explanation can be understood
> -without external resources. Instead of giving a URL to a mailing list
> -archive, summarize the relevant points of the discussion.
> +Write this problem statement in the **present tense** (e.g., "The
> +code does X when given input Y", not "The code used to do Y").  The
> +status quo in the problem statement is always about the code without
> +your change, by project convention.  Do not use words like
> +"Currently" to describe this state.
> +
> +2. **Solution (The Approach)**:
> +   Justify the way your change solves the problem.  Explain why the
> +   proposed approach is better and mention any alternate solutions
> +   considered and discarded.
> ++
> +If your change only addresses a subset of a larger problem (e.g.,
> +handles directories but not files because of characteristic Y),
> +explain this limitation.  This helps future developers understand the
> +boundaries of your work and whether it can be safely extended.
> ++
> +If the change resolves design or viability concerns raised by the
> +community during prior review rounds, ensure the message records the
> +resolution, explaining why the chosen approach was accepted over
> +alternatives.
> +
> +3. **Command (The Instruction)**:
> +   [[imperative-mood]]
> +   Command the codebase to change.  Write this in the **imperative
> +   mood** (e.g., "make xyzzy do frotz" instead of "This patch makes
> +   xyzzy do..." or "I changed xyzzy..."), as if you are giving orders
> +   to the codebase to change its behavior.

Stopped and confused for a moment. I am not sure that "Command" belongs
alongside "Observation" and "Solution" as a third part of the message.
Sometimes the command still describes the solution. In other words,
Solution and Command seem not to be logically completely separable.

> +#### Formatting and Style Guidelines

Perhaps using "====" here would be in harmony with the existing content.

> +* **The Subject Line (First Line)**:
> +  * Keep it short (50 characters is the soft limit).
> +  * Skip the full stop at the end.
> +  * Prefix the subject with the modified area followed by a colon
> +    and a space (e.g., "area: subject").  The area is typically a
> +    filename or identifier (e.g., `doc:`, `transport:`, `t5601:`).
> +    Run `git log --no-merges` on target files to see conventions.
> +  * [[summary-section]]
> +    Do not capitalize the first word after the "area:" prefix unless
> +    there is a specific reason (e.g., `HEAD` is always in caps).
> +    E.g., use "doc: clarify...", not "doc: Clarify...".
> +
> +* **The Body**:
> +  * Explain the *why* rather than repeating the *what* of the diff.
> +  * Try to make the explanation self-contained.  Avoid relying on
> +    external URLs (like mailing list archives) as the sole
> +    explanation; summarize the relevant points of the discussion
> +    instead.
> +  * Wrap lines to 68-72 columns.

MyFirstContribution:
  This commit message is intentionally formatted to 72 columns per line

Should we update both?

btw I don't know which editors/projects have the default setting of 68.
Is it Emacs?

Thanks.