[PATCH 0/6] Update Contributor Guides

[PATCH 0/6] Update Contributor Guides

[Junio C Hamano]

I have been tracking the rules I follow while updating the "What's
cooking" draft, which guides my daily work, and noticed a few gaps
in our contributor documentation.

* We often tell contributors how commit log messages should look on
  the mailing list, but the language in `SubmittingPatches` is too
  wordy.  The first patch in this series shortens it to get to the
  point earlier.

* We recently updated `MyFirstContribution` to advise contributors
  to pace themselves when they find mistakes or receive feedback.
  However, we lack instructions for when a patch receives no
  reaction.  The second patch addresses this gap.

* There seems to be some confusion regarding when contributors should
  add `Reviewed-by:` and `Acked-by:` trailers.  The third patch
  clarifies this process.

* We want to ensure contributors don't walk away once their patch lands
  in `seen`, as that is merely the beginning of the story.  The fourth
  and fifth patches clarify this point.

* An experimental feature in `SubmittingPatches` invites contributors
  to draft the description for their topic in the "What's cooking"
  report.  However, instead of outlining the expected tone, we simply
  told them to emulate existing entries.  The final patch remedies this.

 1/6: SubmittingPatches: clarify expected structure of commit log message
 2/6: MyFirstContribution: what if I don't get a reply?
 3/6: MyFirstContribution: carrying over trailers
 4/6: MyFirstContribution: clarify that 'seen' does not mean acceptance
 5/6: SubmittingPatches: clarify the meaning of "Will queue"
 6/6: SubmittingPatches: clarify the writing style of whats-cooking

 Documentation/MyFirstContribution.adoc |  53 +++++++-
 Documentation/SubmittingPatches        | 171 +++++++++++++------------
 2 files changed, 135 insertions(+), 89 deletions(-)

-- 
2.55.0-391-gdf86bf5712

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

[Junio C Hamano]

The current text on log message has lots of justification and
rationale before telling contributors what exactly is expected of
them.

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

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 140 +++++++++++++++-----------------
 1 file changed, 65 insertions(+), 75 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d2d82eb543..12f9660cef 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -289,86 +289,76 @@ run `git diff --check` on your changes before you commit.
 
 The log message that explains your changes is just as important as the
 changes themselves.  Your code may be clearly written with in-code
-comment to sufficiently explain how it works with the surrounding
-code, but those who need to fix or enhance your code in the future
-will need to know _why_ your code does what it does, for a few
-reasons:
-
-. Your code may be doing something differently from what you wanted it
-  to do.  Writing down what you actually wanted to achieve will help
-  them fix your code and make it do what it should have been doing
-  (also, you often discover your own bugs yourself, while writing the
-  log message to summarize the thought behind it).
-
-. Your code may be doing things that were only necessary for your
-  immediate needs (e.g. "do X to directories" without implementing or
-  even designing what is to be done on files).  Writing down why you
-  excluded what the code does not do will help guide future developers.
-  Writing down "we do X to directories, because directories have
-  characteristic Y" would help them infer "oh, files also have the same
-  characteristic Y, so perhaps doing X to them would also make sense?".
-  Saying "we don't do the same X to files, because ..." will help them
-  decide if the reasoning is sound (in which case they do not waste
-  time extending your code to cover files), or reason differently (in
-  which case, they can explain why they extend your code to cover
-  files, too).
-
-The goal of your log message is to convey the _why_ behind your change
-to help future developers.  The reviewers will also make sure that
-your proposed log message will serve this purpose well.
-
-The first line of the commit message should be a short description (50
-characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),
-and should skip the full stop.  It is also conventional in most cases to
-prefix the first line with "area: " where the area is a filename or
-identifier for the general area of the code being modified, e.g.
-
-* doc: clarify distinction between sign-off and pgp-signing
-* githooks.txt: improve the intro section
-
-If in doubt which identifier to use, run `git log --no-merges` on the
-files you are modifying to see the current conventions.
-
-[[summary-section]]
-The title sentence after the "area:" prefix omits the full stop at the
-end, and its first word is not capitalized (the omission
-of capitalization applies only to the word after the "area:"
-prefix of the title) unless there is a reason to
-capitalize it other than because it is the first word in the sentence.
-E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt:
-improve...", not "githooks.txt: Improve...".  But "refs: HEAD is also
-treated as a ref" is correct, as we spell `HEAD` in all caps even when
-it appears in the middle of a sentence.
+comments, but future developers need to know *why* your code does what
+it does.  The goal of your log message is to convey the intent and
+rationales behind your changes.
 
-[[meaningful-message]]
-The body should provide a meaningful commit message, which:
-
-. explains the problem the change tries to solve, i.e. what is wrong
-  with the current code without the change.
+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.
+
+#### Formatting and Style Guidelines
+
+* **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.
 
 [[commit-reference]]
 
-- 
2.55.0-391-gdf86bf5712

[PATCH 2/6] MyFirstContribution: what if I don't get a reply?

[Junio C Hamano]

Tell readers that pinging is a perfectly sensible thing to do when
they do not see a response.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.adoc | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 4832e5bad5..fc2ce2e785 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1438,6 +1438,19 @@ substantial rework, and mention which parts of the current series will become
 obsolete so reviewers can avoid spending time on them until the updated series
 is ready.
 
+=== What if I don't get a reply?
+
+If you don't receive any review comments after a week or two, do not
+assume your patch has been accepted or merged.  In the Git project,
+silence does not equal approval.  It usually means reviewers are busy
+or haven't noticed your contribution.
+
+If your patch is overlooked, it is perfectly acceptable to send a
+polite ping to the thread.  You can do this by replying to your own
+cover letter (or patch) to ask if anyone has had a chance to look at
+it.  You can also CC additional people who might be interested; use
+the `git-contacts` script (mentioned earlier) to find relevant contributors.
+
 
 [[reviewing]]
 === Responding to Reviews
-- 
2.55.0-391-gdf86bf5712

[PATCH 3/6] MyFirstContribution: carrying over trailers

[Junio C Hamano]

The maintainer will usually collect and add Reviewed-by and Acked-by
trailers on the receiving end, but there are occasions when
contributors can carry them over from previous iterations to the new
iteration they are sending out.

Document how this procedure works and how it helps the maintainer.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.adoc | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index fc2ce2e785..988f0d4fba 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1509,6 +1509,28 @@ changing history, but since it's local history which you haven't shared with
 anyone, that is okay for now! (Later, it may not make sense to do this; take a
 look at the section below this one for some context.)
 
+=== Handling trailers in subsequent versions
+
+If a reviewer replies with an `Acked-by: Real Name <email>` trailer,
+carry it forward when preparing v2:
+
+- If your v2 changes are minor (e.g., fixing typos or making small
+  style tweaks) and do not affect the reviewed logic, add their
+  trailer to the commit message of the updated patch.  This lets the
+  maintainer know that the patch has received favorable review.
+
+- If your v2 contains significant logic changes or rewrites to address
+  feedback, do *not* carry over the trailer, as the reviewer has not
+  seen the new logic yet.  Mention in your cover letter that you made
+  changes that require re-review.
+
+The rule for the `Reviewed-by:` trailer is more strict: you generally
+should not carry it over to a new iteration unless you are resending
+the patch without any change.  For example, a new iteration of a patch
+series might update other patches while leaving the reviewed patch
+that received the `Reviewed-by:` trailer untouched.
+
+
 [[after-approval]]
 === After Review Approval
 
-- 
2.55.0-391-gdf86bf5712

[PATCH 4/6] MyFirstContribution: clarify that 'seen' does not mean acceptance

[Junio C Hamano]

Document that getting a patch picked up into 'seen' is not the end
of the story for contributors; it is merely the beginning.

This is also described in SubmittingPatches:[[patch-flow]] section,
but beneficial to make new contributors aware of it early.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.adoc | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 988f0d4fba..5acc265589 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1534,10 +1534,20 @@ that received the `Reviewed-by:` trailer untouched.
 [[after-approval]]
 === After Review Approval
 
-The Git project has four integration branches: `seen`, `next`, `master`, and
-`maint`. Your change will be placed into `seen` fairly early on by the maintainer
-while it is still in the review process; from there, when it is ready for wider
-testing, it will be merged into `next`. Plenty of early testers use `next` and
+The Git project maintains four integration branches: `seen`, `next`,
+`master`, and `maint`.  The maintainer will often place your change
+into `seen` fairly early in the review process; sometimes even before
+it receives its first comments.
+
+However, being queued in `seen` does not mean your patch has been
+accepted.  It is only there for integration testing, CI, and giving
+wider exposure and ready access to reviewers.  To advance from `seen`
+to `next`, your topic needs positive reviews and community consensus
+on the mailing list.  If reviews are favorable, the maintainer will
+mark the topic as "Will merge to `next`" in the "What's cooking"
+report before actually merging it.
+
+Plenty of early testers use `next` and
 may report issues. Eventually, changes in `next` will make it to `master`,
 which is typically considered stable. Finally, when a new release is cut,
 `maint` is used to base bugfixes onto. As mentioned at the beginning of this
-- 
2.55.0-391-gdf86bf5712

[PATCH 5/6] SubmittingPatches: clarify the meaning of "Will queue"

[Junio C Hamano]

Document that "Will queue" contributors get is merely a promise to
put the topic in 'seen' and has no other meaning.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 12f9660cef..0a80358703 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -104,7 +104,9 @@ of review.
   branch, in order to make it easier for people to play with it
   without having to pick up and apply the patches to their trees
   themselves.  Being in `seen` has no other meaning.  Specifically, it
-  does not mean the patch was "accepted" in any way.
+  does not mean the patch was "accepted" in any way.  The maintainer
+  may reply with "Will queue" when choosing to add the patches to
+  `seen`, but it does not mean the patch has been "accepted", either.
 
 . When the discussion reaches a consensus that the latest iteration of
   the patches are in good enough shape, the maintainer includes the
-- 
2.55.0-391-gdf86bf5712

[PATCH 6/6] SubmittingPatches: clarify the writing style of whats-cooking

[Junio C Hamano]

Unlike commit log messages, that use present tense to make
observations of the current code, and imperative mood to describe
what changes the commit makes, entries in the whats-cooking report
are written mostly in past or present perfect tense to report what
has been done.

Spell it out for contributors.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 0a80358703..8917cc3805 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -714,17 +714,26 @@ line via `git format-patch --notes`.
 
 When sending a topic, you can optionally propose a topic name and/or a
 one-paragraph summary that should appear in the "What's cooking"
-report when it is picked up to explain the topic.  If you choose to do
-so, please write a 2-5 line paragraph that will fit well in our
-release notes (see many bulleted entries in the
+report when it is picked up to explain the topic.
+
+If you choose to do so, please write a 2-5 line paragraph that will
+fit well in our release notes (see many bulleted entries in the
 Documentation/RelNotes/* files for examples), and make it the first
 (or second, if including a suggested topic name) paragraph of the
-cover letter.  If suggesting a topic name, use the format
-"XX/your-topic-name", where "XX" is a stand-in for the primary
-author's initials, and "your-topic-name" is a brief, dash-delimited
-description of what your topic does.  For a single-patch series, use
-the space between the three-dash line and the diffstat, as described
-earlier.
+cover letter.
+
+If suggesting a topic name, use the format "XX/your-topic-name", where
+"XX" is a stand-in for the primary author's initials, and
+"your-topic-name" is a brief, dash-delimited description of what your
+topic does.  For a single-patch series, use the space between the
+three-dash line and the diffstat, as described earlier.
+
+TIP: When proposing a topic summary in your cover letter, write it in
+the reporting style (passive voice, past or present perfect tense
+describing the change as completed, e.g., "The XYZ subsystem has
+been updated to...") rather than the imperative mood, like you do
+in the proposed commit log messages.  This matches the format
+used in the "What's cooking" report and release notes.
 
 [[multi-series-efforts]]
 If your patch series is part of a larger effort spanning multiple
-- 
2.55.0-391-gdf86bf5712

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

[Weijie Yuan]

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.

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

[Junio C Hamano]

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.

Re: [PATCH 4/6] MyFirstContribution: clarify that 'seen' does not mean acceptance

[Matt Hunter]

On Sat Jul 11, 2026 at 3:26 PM EDT, Junio C Hamano wrote:
> +
> +Plenty of early testers use `next` and
>  may report issues. Eventually, changes in `next` will make it to `master`,
>  which is typically considered stable. Finally, when a new release is cut,
>  `maint` is used to base bugfixes onto. As mentioned at the beginning of this

It feels odd not to reflow this paragraph, where the first line now just
stops halfway across the width of the paragraph.  Though, the diff-churn
may not be worth it in your eyes.

Re: [PATCH 4/6] MyFirstContribution: clarify that 'seen' does not mean acceptance

[Junio C Hamano]

"Matt Hunter" <m@lfurio.us> writes:

> On Sat Jul 11, 2026 at 3:26 PM EDT, Junio C Hamano wrote:
>> +
>> +Plenty of early testers use `next` and
>>  may report issues. Eventually, changes in `next` will make it to `master`,
>>  which is typically considered stable. Finally, when a new release is cut,
>>  `maint` is used to base bugfixes onto. As mentioned at the beginning of this
>
> It feels odd not to reflow this paragraph, where the first line now just
> stops halfway across the width of the paragraph.  Though, the diff-churn
> may not be worth it in your eyes.

Yes, I did not want to force patch readers to review three extra
lines just to spot a non-existent difference caused by an
unnecessary reflow.  Unlike SubmittingPatches, the target audience
for MyFirstContribution is less familiar with our source files than
experienced contributors are, so they will not be reading this in
its source form anyway.  Therefore, I thought leaving an unusually
short line there was a reasonable trade-off until the entire
paragraph needs to be rewritten.

However, when the next person who wants to modify this source file
reads it, it will indeed be distracting to them.  So, perhaps I
should reflow the remainder of the paragraph.

Thanks.

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

[Michael Montalbo]

On Sat, Jul 11, 2026 at 12:27 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> +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.

Slight reflow suggestion (answers the question "better than what?"
and is more concise):

"Explain why the proposed approach is better than any alternate
solutions that were 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.

In the spirit of paring down text, this last section seems to overlap with
the prior "alternative solutions considered" blurb above. Maybe they can
be combined?

> +
> +3. **Command (The Instruction)**:

"Command" reads a bit awkwardly to me. I think something about
"Implementation" or another phrase that distinguishes between
the mechanics of the change and the design of the change
might be more clear.

> +   [[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.
> +
> +#### Formatting and Style Guidelines
> +
> +* **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.

I think collapsing the "Formatting and Style Guidelines" section with
the above would be clearer than having a separate section. The
content prior to this section mixes "content" and "formatting"
guidelines so maybe those concepts could be explicitly delineated
and the advice in this section could be co-located with the commit
message component it is related to above. That might also help
eliminate some redundancy (i.e., another reference to "why vs.
what").

Some more general feedback: maybe examples of well vs. poorly
formed components would help distill the advice for a reader.

Overall, I think reducing the amount of text a contributor needs to
read in order to get up to speed is a very worthwhile endeavor, so
thank you!

Re: [PATCH 6/6] SubmittingPatches: clarify the writing style of whats-cooking

[Michael Montalbo]

On Sat, Jul 11, 2026 at 12:27 PM Junio C Hamano <gitster@pobox.com> wrote:
> +TIP: When proposing a topic summary in your cover letter, write it in...

super nit: It seems like the precedent in this file is to use "NOTE" instead
of "TIP".

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

[Junio C Hamano]

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.

Re: [PATCH 6/6] SubmittingPatches: clarify the writing style of whats-cooking

[Junio C Hamano]

Michael Montalbo <mmontalbo@gmail.com> writes:

> On Sat, Jul 11, 2026 at 12:27 PM Junio C Hamano <gitster@pobox.com> wrote:
>> +TIP: When proposing a topic summary in your cover letter, write it in...
>
> super nit: It seems like the precedent in this file is to use "NOTE" instead
> of "TIP".

Yeah, and not just locally in this file; "TIP:" is actually
not used anywhere in the Documentation/ directory, whereas
"NOTE:" is frequently used.  I will switch to "NOTE:" as
there is no point in having variety in something like this.

Thanks.

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

[Weijie Yuan]

On Sun, Jul 12, 2026 at 09:07:32AM -0700, Junio C Hamano wrote:
> 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?

Yeah, that is much clearer. I'm reading your draft in your reply to
Michael, seems good.

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

Yes, got it. I just want to say that I often see 72 columns, but I
haven't seen 68 very often. (maybe I'm too young ;-)

Thanks.

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

[Weijie Yuan]

On Sun, Jul 12, 2026 at 05:07:04PM -0700, Junio C Hamano wrote:
> 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.

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)

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.