patch, 6 partsUpdate Contributor Guides

21 messages between Jul 11, 2026 and Jul 17, 2026, from Junio C Hamano, Weijie Yuan, Matt Hunter, Michael Montalbo, D. Ben Knoble, Patrick Steinhardt.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Junio C HamanoJul 11, 2026, 19:26 UTC on lore

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

Junio C HamanoJul 11, 2026, 19:26 UTC in reply to Junio C Hamano on lore

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

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

Show changes to Documentation/SubmittingPatches +65 −75

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

Junio C HamanoJul 11, 2026, 19:26 UTC in reply to Junio C Hamano on lore

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

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(+)

Show changes to Documentation/MyFirstContribution.adoc +13 −0

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

Junio C HamanoJul 11, 2026, 19:26 UTC in reply to Junio C Hamano on lore

[PATCH 3/6] MyFirstContribution: carrying over trailers

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(+)

Show changes to Documentation/MyFirstContribution.adoc +22 −0

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

Junio C HamanoJul 11, 2026, 19:26 UTC in reply to Junio C Hamano on lore

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

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

Show changes to Documentation/MyFirstContribution.adoc +14 −4

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

Junio C HamanoJul 11, 2026, 19:26 UTC in reply to Junio C Hamano on lore

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

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

Show changes to Documentation/SubmittingPatches +3 −1

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

Junio C HamanoJul 11, 2026, 19:26 UTC in reply to Junio C Hamano on lore

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

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

Show changes to Documentation/SubmittingPatches +18 −9

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

Weijie YuanJul 12, 2026, 14:49 UTC in reply to Junio C Hamano on lore

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

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.

> [...]

Show 64 quoted lines

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

Show 19 quoted lines

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

Junio C HamanoJul 12, 2026, 16:07 UTC in reply to Weijie Yuan on lore

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

Weijie Yuan <wy@wyuan.org> writes:

Show 12 quoted lines

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

Show 12 quoted lines

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

Matt HunterJul 12, 2026, 18:08 UTC in reply to Junio C Hamano on lore

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

On Sat Jul 11, 2026 at 3:26 PM EDT, Junio C Hamano wrote:

Show 5 quoted lines

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

Junio C HamanoJul 12, 2026, 19:04 UTC in reply to Matt Hunter on lore

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

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

Show 10 quoted lines

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

Michael MontalboJul 12, 2026, 20:26 UTC in reply to Junio C Hamano on lore

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

On Sat, Jul 11, 2026 at 12:27 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 5 quoted lines

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

Show 10 quoted lines

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

Show 22 quoted lines

> +   [[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!

Michael MontalboJul 12, 2026, 20:41 UTC in reply to Junio C Hamano on lore

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

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

Junio C HamanoJul 13, 2026, 00:07 UTC in reply to Michael Montalbo on lore

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

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.

Junio C HamanoJul 13, 2026, 04:20 UTC in reply to Michael Montalbo on lore

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

Michael Montalbo <mmontalbo@gmail.com> writes:

Show 5 quoted lines

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

Weijie YuanJul 13, 2026, 14:14 UTC in reply to Junio C Hamano on lore

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

On Sun, Jul 12, 2026 at 09:07:32AM -0700, Junio C Hamano wrote:

Show 27 quoted lines

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

Show 21 quoted lines

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

Weijie YuanJul 13, 2026, 14:14 UTC in reply to Junio C Hamano on lore

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

On Sun, Jul 12, 2026 at 05:07:04PM -0700, Junio C Hamano wrote:

Show 86 quoted lines

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

D. Ben KnobleJul 14, 2026, 22:46 UTC in reply to Weijie Yuan on lore

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

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

Patrick SteinhardtJul 17, 2026, 11:12 UTC in reply to Junio C Hamano on lore

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

On Sat, Jul 11, 2026 at 12:26:46PM -0700, Junio C Hamano wrote:

Show 22 quoted lines

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

Should we also add the third reason: reviewers are simply not interested in the patch? It's a bit brutal, but that's quite a common reason, too. In the best case we'd of course tell the submitter that we don't want the patch to not leave them hanging.

Show 5 quoted lines

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

And this paragraph here can remain as-is regardless of which of the three reasons applies.

Patrick

Weijie YuanJul 17, 2026, 12:42 UTC in reply to D. Ben Knoble on lore

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

On Tue, Jul 14, 2026 at 06:46:05PM -0400, D. Ben Knoble wrote:

Show 17 quoted lines

> On Mon, Jul 13, 2026 at 10:42 AM Weijie Yuan <wy@wyuan.org> wrote:
> >
> [snip]
> > 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.

Aha, kind of. But I guess Junio didn't use LLM here ;-)

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

True.

Show 22 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]
> 
> ?

I agree. More explanatory descriptions here are very likely to enable contributors to express their ideas more clearly and understandably.

Junio C HamanoJul 17, 2026, 14:59 UTC in reply to Patrick Steinhardt on lore

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

Patrick Steinhardt <ps@pks.im> writes:

Show 26 quoted lines

> On Sat, Jul 11, 2026 at 12:26:46PM -0700, Junio C Hamano wrote:
>> 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.
>
> Should we also add the third reason: reviewers are simply not interested
> in the patch? It's a bit brutal, but that's quite a common reason, too.

Yeah, I agree that it would make a good addition.