Update Contributor Guides
cover Update Contributor Guides
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(-)
Signature · 1 line
2.55.0-391-gdf86bf5712
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.
--- Documentation/SubmittingPatches | 140 +++++++++++++++----------------- 1 file changed, 65 insertions(+), 75 deletions(-)
Documentation/SubmittingPatches +65 -75
@@ -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]]
Signature · 1 line
2.55.0-391-gdf86bf5712
Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message
Quoted 3 lines · Junio C Hamano
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/ ?
Quoted 59 lines
Simplify the rationale section and jump straight to what to write and how.
[...]
Documentation/SubmittingPatches +30
-20+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
Documentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 339
Quoted 10 lines
Documentation/SubmittingPatches +10
-0+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.
Quoted 1 line
+#### Formatting and Style Guidelines
Perhaps using "====" here would be in harmony with the existing content.
Quoted 9 lines
Documentation/SubmittingPatches +9
-0+* **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
Documentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 361
Quoted 10 lines
Documentation/SubmittingPatches +10
-0+ 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
Quoted 8 lines · Weijie Yuan
Documentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 339
Quoted 7 lines
+2. **Solution (The Approach)**:
+3. **Command (The Instruction)**:Documentation/SubmittingPatches +5
-0+ [[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.
Quoted 4 lines
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?
Quoted 3 lines
Quoted 1 line
+#### Formatting and Style Guidelines
Perhaps using "====" here would be in harmony with the existing content.
Indeed.
Quoted 8 lines
Documentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 361
Quoted 7 lines
Documentation/SubmittingPatches +7
-0+* **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.
Quoted 4 lines
MyFirstContribution:
This commit message is intentionally formatted to 72 columns per lineShould 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 1/6] SubmittingPatches: clarify expected structure of commit log message
Quoted 19 lines · Junio C Hamano
Quoted 8 lines · Weijie Yuan
Documentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 339
Quoted 7 lines
+2. **Solution (The Approach)**:
+3. **Command (The Instruction)**:Documentation/SubmittingPatches +5
-0+ [[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.Quoted 4 lines
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
Quoted 8 lines
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.
Quoted 13 lines
Quoted 8 lines
Documentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 361
Quoted 7 lines
Documentation/SubmittingPatches +7
-0+* **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.Quoted 4 lines
MyFirstContribution:
This commit message is intentionally formatted to 72 columns per lineShould we update both?
Quoted 8 lines
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
In reply to Junio C HamanoDocumentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 322
Quoted 5 lines · Junio C Hamano
+2. **Solution (The Approach)**:
Documentation/SubmittingPatches +3
-0+ 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."
Documentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 332
Quoted 10 lines
++
Documentation/SubmittingPatches +9
-0+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?
Quoted 2 lines
+
+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.
Quoted 12 lines
Documentation/SubmittingPatches +12
-0+ [[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
Documentation/SubmittingPatches run `git diff --check` on your changes before you commit. · line 356
Quoted 10 lines
Documentation/SubmittingPatches +10
-0+ 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 1/6] SubmittingPatches: clarify expected structure of commit log message
Quoted 2 lines · Michael Montalbo
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 1/6] SubmittingPatches: clarify expected structure of commit log message
Quoted 79 lines · Junio C Hamano
Quoted 2 lines · Michael Montalbo
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 Message1. Title:
The first line of the commit log message is the title that lets readers ofgit log --onelinequickly 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:). Rungit log --no-mergeson target files to see conventions.
- Do not capitalize the first word after the "area:" prefix unless there is a specific reason (e.g.,HEADis 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.
Quoted 7 lines
- 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.
Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message
Quoted 1 line · Weijie Yuan
[snip]
Quoted 8 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 :)
Quoted 11 lines
But acatually you mean:
1. Title
2. Body
The body typically follows three parts:
a. Observation
b. Solution Design
c. ImplementationBut 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]
?
Signature · 1 line
D. Ben Knoble
Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message
Quoted 12 lines · D. Ben Knoble
Quoted 1 line · Weijie Yuan
[snip]
Quoted 8 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)
Quoted 5 lines
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 ;-)
Quoted 4 lines
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.
Quoted 15 lines
Quoted 11 lines
But acatually you mean:
1. Title
2. Body
The body typically follows three parts:
a. Observation
b. Solution Design
c. ImplementationBut 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":
Quoted 7 lines
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.
PATCH 2/6 MyFirstContribution: what if I don't get a reply?
In reply to Junio C HamanoTell readers that pinging is a perfectly sensible thing to do when they do not see a response.
--- Documentation/MyFirstContribution.adoc | 13 +++++++++++++ 1 file changed, 13 insertions(+)
Documentation/MyFirstContribution.adoc +13 -0
@@ -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
Signature · 1 line
2.55.0-391-gdf86bf5712
Re: [PATCH 2/6] MyFirstContribution: what if I don't get a reply?
Quoted 13 lines · 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 <[email protected]>--- Documentation/MyFirstContribution.adoc | 13 +++++++++++++ 1 file changed, 13 insertions(+)Documentation/MyFirstContribution.adoc +0
-0
Documentation/MyFirstContribution.adoc substantial rework, and mention which parts of the current series will become · line 1446
Quoted 9 lines
Documentation/MyFirstContribution.adoc +6
-0@@ -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.
Documentation/MyFirstContribution.adoc substantial rework, and mention which parts of the current series will become · line 1452
Quoted 5 lines
Documentation/MyFirstContribution.adoc +5
-0+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
Re: [PATCH 2/6] MyFirstContribution: what if I don't get a reply?
Quoted 17 lines · Patrick Steinhardt
Quoted 16 lines · 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 <[email protected]>--- Documentation/MyFirstContribution.adoc | 13 +++++++++++++ 1 file changed, 13 insertions(+)Documentation/MyFirstContribution.adoc +0
-0@@ -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.
Quoted 9 lines
Documentation/MyFirstContribution.adoc substantial rework, and mention which parts of the current series will become · line 1446
Quoted 6 lines
Documentation/MyFirstContribution.adoc +6
-0+=== 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.
PATCH 3/6 MyFirstContribution: carrying over trailers
In reply to Junio C HamanoThe 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.
--- Documentation/MyFirstContribution.adoc | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+)
Documentation/MyFirstContribution.adoc +22 -0
@@ -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
Signature · 1 line
2.55.0-391-gdf86bf5712
PATCH 4/6 MyFirstContribution: clarify that 'seen' does not mean acceptance
In reply to Junio C HamanoDocument 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.
--- Documentation/MyFirstContribution.adoc | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-)
Documentation/MyFirstContribution.adoc +14 -4
@@ -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
Signature · 1 line
2.55.0-391-gdf86bf5712
Re: [PATCH 4/6] MyFirstContribution: clarify that 'seen' does not mean acceptance
Documentation/MyFirstContribution.adoc that received the `Reviewed-by:` trailer untouched. · line 1553
Quoted 5 lines · Junio C Hamano
Documentation/MyFirstContribution.adoc +2
-0+ +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
Quoted 10 lines · Matt Hunter
Documentation/MyFirstContribution.adoc that received the `Reviewed-by:` trailer untouched. · line 1553
Quoted 5 lines · Junio C Hamano
Documentation/MyFirstContribution.adoc +2
-0+ +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 thisIt 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.
PATCH 5/6 SubmittingPatches: clarify the meaning of "Will queue"
In reply to Junio C HamanoDocument that "Will queue" contributors get is merely a promise to put the topic in 'seen' and has no other meaning.
--- Documentation/SubmittingPatches | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/SubmittingPatches +3 -1
@@ -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
Signature · 1 line
2.55.0-391-gdf86bf5712
PATCH 6/6 SubmittingPatches: clarify the writing style of whats-cooking
In reply to Junio C HamanoUnlike 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.
--- Documentation/SubmittingPatches | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-)
Documentation/SubmittingPatches +18 -9
@@ -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
Signature · 1 line
2.55.0-391-gdf86bf5712
Re: [PATCH 6/6] SubmittingPatches: clarify the writing style of whats-cooking
Quoted 1 line · Junio C Hamano
+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 6/6] SubmittingPatches: clarify the writing style of whats-cooking
Quoted 5 lines · Michael Montalbo
Quoted 1 line · Junio C Hamano
+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.