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

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

Weijie Yuan <wy@wyuan.org> writes:

>> +2. **Solution (The Approach)**:
>> +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.

I do not think "Command the codebase to change" is a good phrasing.
It would have been better to highlight the distinction between the
design of the solution (approach) and the implementation.  Perhaps

    2. Design (The Approach)

    3. Implementation (The Changes)
    [[imperative-mood]]
       Describe how the change is implemented.  Write this in the
       imperative mood. ...

or something?

>> +#### Formatting and Style Guidelines
>
> Perhaps using "====" here would be in harmony with the existing content.

Indeed.

>> +* **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?

Perhaps just to stick to "around 70".

I do not think the defaults in various editors matter.

The "wrap around 70 columns" rule exists so that in a text based
email exchange, where you lose two columns to leading "> " when
quoted, and an additional column with each subsequent reply, the
lines will still fit on standard 80-column terminals.

Thanks.