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

[Junio C Hamano <gitster@pobox.com>]

Michael Montalbo <mmontalbo@gmail.com> writes:

> I think collapsing the "Formatting and Style Guidelines" section with
> the above would be clearer than having a separate section.

Thanks for pointing it out; I tend to agree.

Before rerolling the series in entirety, here is what I have in my
editor buffer right now, after attempting to move the formatting and
styles into the main description.

I haven't checked if the formatting works as AsciiDoc yet, though.

--- >8 ---
[[meaningful-message]]
==== Structure of a Commit Message

1. 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.

   - 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.
   - Do not capitalize the first word after the "area:" prefix
     unless there is a specific reason (e.g., `HEAD` is always in
     uppercase).  For example, use "doc: clarify...", not "doc:
     Clarify...".

2. Body:
   A well-structured commit message body typically follows a
   three-part flow: Observation, Solution Design, and
   Implementation.

   - Leave a blank line between the title and the body.
   - Wrap lines in the body of the commit log message to around 70
     columns.
   - The body of the log message must be self-contained.  Do not
     rely on external URLs (including mailing list archives) as the
     sole explanation.  Summarize the relevant points of external
     material so that readers can understand the change with the log
     message alone.

[[present-tense]]
3. Observation (The Status Quo):
   Explain the problem you are solving with your change by
   describing what is wrong with the current code *without* your
   change.

   - As this part is always about the current state by convention,
     words like "currently" are unnecessary.
   - Write this problem statement in the present tense (e.g., "The
     code does X when given input Y", not "The code did X").

4. Solution Design (The Approach):
   Explain the approach you took, justify how it solves the problem,
   and describe why you chose the particular design over other
   alternatives.

   - Focus on describing _why_, not _how_ (e.g., "The code does X
     when given input Y, but it should do Z _because_...").
   - If your change only addresses a subset of a larger problem
     (e.g., it handles directories but not files because ...),
     explain this limitation.  This helps future developers
     understand the boundaries of your work and whether it can be
     safely extended.
   - If your 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.

[[imperative-mood]]
5. Implementation (The Execution):
   Finally, describe how the changes are implemented.

   - Write this in the imperative mood (e.g., "Make xyzzy do frotz",
     not "This patch makes xyzzy do..." or "I changed xyzzy..."), as
     if you are instructing an agent to make changes to the
     codebase.
   - You do not have to repeat everything readers can discern from
     the patch text.  Highlight the key points in your
     implementation.