{"thread":{"id":"65977","subject":"[PATCH 0/6] Update Contributor Guides","startedAt":"2026-07-11T19:26:52Z","lastAt":"2026-07-17T14:59:34Z","messageCount":21,"participants":["Junio C Hamano","Weijie Yuan","Matt Hunter","Michael Montalbo","D. Ben Knoble","Patrick Steinhardt"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"547850","messageId":"20260711192650.2417665-1-gitster@pobox.com","threadId":"65977","inReplyTo":null,"subject":"[PATCH 0/6] Update Contributor Guides","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-11T19:26:44Z","receivedAt":"2026-07-11T19:26:52Z","isPatch":true,"body":"I have been tracking the rules I follow while updating the \"What's\ncooking\" draft, which guides my daily work, and noticed a few gaps\nin our contributor documentation.\n\n* We often tell contributors how commit log messages should look on\n the mailing list, but the language in `SubmittingPatches` is too\n wordy. The first patch in this series shortens it to get to the\n point earlier.\n\n* We recently updated `MyFirstContribution` to advise contributors\n to pace themselves when they find mistakes or receive feedback.\n However, we lack instructions for when a patch receives no\n reaction. The second patch addresses this gap.\n\n* There seems to be some confusion regarding when contributors should\n add `Reviewed-by:` and `Acked-by:` trailers. The third patch\n clarifies this process.\n\n* We want to ensure contributors don't walk away once their patch lands\n in `seen`, as that is merely the beginning of the story. The fourth\n and fifth patches clarify this point.\n\n* An experimental feature in `SubmittingPatches` invites contributors\n to draft the description for their topic in the \"What's cooking\"\n report. However, instead of outlining the expected tone, we simply\n told them to emulate existing entries. The final patch remedies this.\n\n 1/6: SubmittingPatches: clarify expected structure of commit log message\n 2/6: MyFirstContribution: what if I don't get a reply?\n 3/6: MyFirstContribution: carrying over trailers\n 4/6: MyFirstContribution: clarify that 'seen' does not mean acceptance\n 5/6: SubmittingPatches: clarify the meaning of \"Will queue\"\n 6/6: SubmittingPatches: clarify the writing style of whats-cooking\n\n Documentation/MyFirstContribution.adoc | 53 +++++++-\n Documentation/SubmittingPatches | 171 +++++++++++++------------\n 2 files changed, 135 insertions(+), 89 deletions(-)\n\n-- \n2.55.0-391-gdf86bf5712\n"},{"id":"547851","messageId":"20260711192650.2417665-2-gitster@pobox.com","threadId":"65977","inReplyTo":"20260711192650.2417665-1-gitster@pobox.com","subject":"[PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-11T19:26:45Z","receivedAt":"2026-07-11T19:26:54Z","isPatch":true,"body":"The current text on log message has lots of justification and\nrationale before telling contributors what exactly is expected of\nthem.\n\nSimplify the rationale section and jump straight to what to write\nand how.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/SubmittingPatches | 140 +++++++++++++++-----------------\n 1 file changed, 65 insertions(+), 75 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d2d82eb543..12f9660cef 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -289,86 +289,76 @@ run `git diff --check` on your changes before you commit.\n \n The log message that explains your changes is just as important as the\n changes themselves. Your code may be clearly written with in-code\n-comment to sufficiently explain how it works with the surrounding\n-code, but those who need to fix or enhance your code in the future\n-will need to know _why_ your code does what it does, for a few\n-reasons:\n-\n-. Your code may be doing something differently from what you wanted it\n- to do. Writing down what you actually wanted to achieve will help\n- them fix your code and make it do what it should have been doing\n- (also, you often discover your own bugs yourself, while writing the\n- log message to summarize the thought behind it).\n-\n-. Your code may be doing things that were only necessary for your\n- immediate needs (e.g. \"do X to directories\" without implementing or\n- even designing what is to be done on files). Writing down why you\n- excluded what the code does not do will help guide future developers.\n- Writing down \"we do X to directories, because directories have\n- characteristic Y\" would help them infer \"oh, files also have the same\n- characteristic Y, so perhaps doing X to them would also make sense?\".\n- Saying \"we don't do the same X to files, because ...\" will help them\n- decide if the reasoning is sound (in which case they do not waste\n- time extending your code to cover files), or reason differently (in\n- which case, they can explain why they extend your code to cover\n- files, too).\n-\n-The goal of your log message is to convey the _why_ behind your change\n-to help future developers. The reviewers will also make sure that\n-your proposed log message will serve this purpose well.\n-\n-The first line of the commit message should be a short description (50\n-characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),\n-and should skip the full stop. It is also conventional in most cases to\n-prefix the first line with \"area: \" where the area is a filename or\n-identifier for the general area of the code being modified, e.g.\n-\n-* doc: clarify distinction between sign-off and pgp-signing\n-* githooks.txt: improve the intro section\n-\n-If in doubt which identifier to use, run `git log --no-merges` on the\n-files you are modifying to see the current conventions.\n-\n-[[summary-section]]\n-The title sentence after the \"area:\" prefix omits the full stop at the\n-end, and its first word is not capitalized (the omission\n-of capitalization applies only to the word after the \"area:\"\n-prefix of the title) unless there is a reason to\n-capitalize it other than because it is the first word in the sentence.\n-E.g. \"doc: clarify...\", not \"doc: Clarify...\", or \"githooks.txt:\n-improve...\", not \"githooks.txt: Improve...\". But \"refs: HEAD is also\n-treated as a ref\" is correct, as we spell `HEAD` in all caps even when\n-it appears in the middle of a sentence.\n+comments, but future developers need to know *why* your code does what\n+it does. The goal of your log message is to convey the intent and\n+rationales behind your changes.\n \n-[[meaningful-message]]\n-The body should provide a meaningful commit message, which:\n-\n-. explains the problem the change tries to solve, i.e. what is wrong\n- with the current code without the change.\n+Reviewers will evaluate your commit message for clarity and structure.\n+A well-structured commit message typically follows a three-part flow:\n+**Observation**, **Solution**, and **Command**.\n \n-. justifies the way the change solves the problem, i.e. why the\n- result with the change is better.\n-\n-. alternate solutions considered but discarded, if any.\n+[[meaningful-message]]\n+==== Structure of a Commit Message\n \n-. records the resolution of design or viability concerns raised by the\n- community during the review, if any, ensuring the historical record\n- explains why the chosen approach was accepted over alternatives.\n+0. **Title**:\n+ The first line of the commit log message is the title that lets\n+ readers of `git log --oneline` quickly understand what area the\n+ commit touches and what problem it addresses.\n \n+1. **Observation (The Status Quo)**:\n+ Explain the problem you are trying to solve. Describe what is\n+ wrong with the current code *without* your change.\n++\n [[present-tense]]\n-The problem statement that describes the status quo is written in the\n-present tense. Write \"The code does X when it is given input Y\",\n-instead of \"The code used to do Y when given input X\". You do not\n-have to say \"Currently\"---the status quo in the problem statement is\n-about the code _without_ your change, by project convention.\n-\n-[[imperative-mood]]\n-Describe your changes in imperative mood, e.g. \"make xyzzy do frotz\"\n-instead of \"[This patch] makes xyzzy do frotz\" or \"[I] changed xyzzy\n-to do frotz\", as if you are giving orders to the codebase to change\n-its behavior. Try to make sure your explanation can be understood\n-without external resources. Instead of giving a URL to a mailing list\n-archive, summarize the relevant points of the discussion.\n+Write this problem statement in the **present tense** (e.g., \"The\n+code does X when given input Y\", not \"The code used to do Y\"). The\n+status quo in the problem statement is always about the code without\n+your change, by project convention. Do not use words like\n+\"Currently\" to describe this state.\n+\n+2. **Solution (The Approach)**:\n+ Justify the way your change solves the problem. Explain why the\n+ proposed approach is better and mention any alternate solutions\n+ considered and discarded.\n++\n+If your change only addresses a subset of a larger problem (e.g.,\n+handles directories but not files because of characteristic Y),\n+explain this limitation. This helps future developers understand the\n+boundaries of your work and whether it can be safely extended.\n++\n+If the change resolves design or viability concerns raised by the\n+community during prior review rounds, ensure the message records the\n+resolution, explaining why the chosen approach was accepted over\n+alternatives.\n+\n+3. **Command (The Instruction)**:\n+ [[imperative-mood]]\n+ Command the codebase to change. Write this in the **imperative\n+ mood** (e.g., \"make xyzzy do frotz\" instead of \"This patch makes\n+ xyzzy do...\" or \"I changed xyzzy...\"), as if you are giving orders\n+ to the codebase to change its behavior.\n+\n+#### Formatting and Style Guidelines\n+\n+* **The Subject Line (First Line)**:\n+ * Keep it short (50 characters is the soft limit).\n+ * Skip the full stop at the end.\n+ * Prefix the subject with the modified area followed by a colon\n+ and a space (e.g., \"area: subject\"). The area is typically a\n+ filename or identifier (e.g., `doc:`, `transport:`, `t5601:`).\n+ Run `git log --no-merges` on target files to see conventions.\n+ * [[summary-section]]\n+ Do not capitalize the first word after the \"area:\" prefix unless\n+ there is a specific reason (e.g., `HEAD` is always in caps).\n+ E.g., use \"doc: clarify...\", not \"doc: Clarify...\".\n+\n+* **The Body**:\n+ * Explain the *why* rather than repeating the *what* of the diff.\n+ * Try to make the explanation self-contained. Avoid relying on\n+ external URLs (like mailing list archives) as the sole\n+ explanation; summarize the relevant points of the discussion\n+ instead.\n+ * Wrap lines to 68-72 columns.\n \n [[commit-reference]]\n \n-- \n2.55.0-391-gdf86bf5712\n\n"},{"id":"547852","messageId":"20260711192650.2417665-3-gitster@pobox.com","threadId":"65977","inReplyTo":"20260711192650.2417665-1-gitster@pobox.com","subject":"[PATCH 2/6] MyFirstContribution: what if I don't get a reply?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-11T19:26:46Z","receivedAt":"2026-07-11T19:26:55Z","isPatch":true,"body":"Tell readers that pinging is a perfectly sensible thing to do when\nthey do not see a response.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/MyFirstContribution.adoc | 13 +++++++++++++\n 1 file changed, 13 insertions(+)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 4832e5bad5..fc2ce2e785 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1438,6 +1438,19 @@ substantial rework, and mention which parts of the current series will become\n obsolete so reviewers can avoid spending time on them until the updated series\n is ready.\n \n+=== What if I don't get a reply?\n+\n+If you don't receive any review comments after a week or two, do not\n+assume your patch has been accepted or merged. In the Git project,\n+silence does not equal approval. It usually means reviewers are busy\n+or haven't noticed your contribution.\n+\n+If your patch is overlooked, it is perfectly acceptable to send a\n+polite ping to the thread. You can do this by replying to your own\n+cover letter (or patch) to ask if anyone has had a chance to look at\n+it. You can also CC additional people who might be interested; use\n+the `git-contacts` script (mentioned earlier) to find relevant contributors.\n+\n \n [[reviewing]]\n === Responding to Reviews\n-- \n2.55.0-391-gdf86bf5712\n\n"},{"id":"547853","messageId":"20260711192650.2417665-4-gitster@pobox.com","threadId":"65977","inReplyTo":"20260711192650.2417665-1-gitster@pobox.com","subject":"[PATCH 3/6] MyFirstContribution: carrying over trailers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-11T19:26:47Z","receivedAt":"2026-07-11T19:26:57Z","isPatch":true,"body":"The maintainer will usually collect and add Reviewed-by and Acked-by\ntrailers on the receiving end, but there are occasions when\ncontributors can carry them over from previous iterations to the new\niteration they are sending out.\n\nDocument how this procedure works and how it helps the maintainer.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/MyFirstContribution.adoc | 22 ++++++++++++++++++++++\n 1 file changed, 22 insertions(+)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex fc2ce2e785..988f0d4fba 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1509,6 +1509,28 @@ changing history, but since it's local history which you haven't shared with\n anyone, that is okay for now! (Later, it may not make sense to do this; take a\n look at the section below this one for some context.)\n \n+=== Handling trailers in subsequent versions\n+\n+If a reviewer replies with an `Acked-by: Real Name ` trailer,\n+carry it forward when preparing v2:\n+\n+- If your v2 changes are minor (e.g., fixing typos or making small\n+ style tweaks) and do not affect the reviewed logic, add their\n+ trailer to the commit message of the updated patch. This lets the\n+ maintainer know that the patch has received favorable review.\n+\n+- If your v2 contains significant logic changes or rewrites to address\n+ feedback, do *not* carry over the trailer, as the reviewer has not\n+ seen the new logic yet. Mention in your cover letter that you made\n+ changes that require re-review.\n+\n+The rule for the `Reviewed-by:` trailer is more strict: you generally\n+should not carry it over to a new iteration unless you are resending\n+the patch without any change. For example, a new iteration of a patch\n+series might update other patches while leaving the reviewed patch\n+that received the `Reviewed-by:` trailer untouched.\n+\n+\n [[after-approval]]\n === After Review Approval\n \n-- \n2.55.0-391-gdf86bf5712\n\n"},{"id":"547854","messageId":"20260711192650.2417665-5-gitster@pobox.com","threadId":"65977","inReplyTo":"20260711192650.2417665-1-gitster@pobox.com","subject":"[PATCH 4/6] MyFirstContribution: clarify that 'seen' does not mean acceptance","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-11T19:26:48Z","receivedAt":"2026-07-11T19:26:58Z","isPatch":true,"body":"Document that getting a patch picked up into 'seen' is not the end\nof the story for contributors; it is merely the beginning.\n\nThis is also described in SubmittingPatches:[[patch-flow]] section,\nbut beneficial to make new contributors aware of it early.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/MyFirstContribution.adoc | 18 ++++++++++++++----\n 1 file changed, 14 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 988f0d4fba..5acc265589 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1534,10 +1534,20 @@ that received the `Reviewed-by:` trailer untouched.\n [[after-approval]]\n === After Review Approval\n \n-The Git project has four integration branches: `seen`, `next`, `master`, and\n-`maint`. Your change will be placed into `seen` fairly early on by the maintainer\n-while it is still in the review process; from there, when it is ready for wider\n-testing, it will be merged into `next`. Plenty of early testers use `next` and\n+The Git project maintains four integration branches: `seen`, `next`,\n+`master`, and `maint`. The maintainer will often place your change\n+into `seen` fairly early in the review process; sometimes even before\n+it receives its first comments.\n+\n+However, being queued in `seen` does not mean your patch has been\n+accepted. It is only there for integration testing, CI, and giving\n+wider exposure and ready access to reviewers. To advance from `seen`\n+to `next`, your topic needs positive reviews and community consensus\n+on the mailing list. If reviews are favorable, the maintainer will\n+mark the topic as \"Will merge to `next`\" in the \"What's cooking\"\n+report before actually merging it.\n+\n+Plenty of early testers use `next` and\n may report issues. Eventually, changes in `next` will make it to `master`,\n which is typically considered stable. Finally, when a new release is cut,\n `maint` is used to base bugfixes onto. As mentioned at the beginning of this\n-- \n2.55.0-391-gdf86bf5712\n\n"},{"id":"547855","messageId":"20260711192650.2417665-6-gitster@pobox.com","threadId":"65977","inReplyTo":"20260711192650.2417665-1-gitster@pobox.com","subject":"[PATCH 5/6] SubmittingPatches: clarify the meaning of \"Will queue\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-11T19:26:49Z","receivedAt":"2026-07-11T19:26:59Z","isPatch":true,"body":"Document that \"Will queue\" contributors get is merely a promise to\nput the topic in 'seen' and has no other meaning.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/SubmittingPatches | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 12f9660cef..0a80358703 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -104,7 +104,9 @@ of review.\n branch, in order to make it easier for people to play with it\n without having to pick up and apply the patches to their trees\n themselves. Being in `seen` has no other meaning. Specifically, it\n- does not mean the patch was \"accepted\" in any way.\n+ does not mean the patch was \"accepted\" in any way. The maintainer\n+ may reply with \"Will queue\" when choosing to add the patches to\n+ `seen`, but it does not mean the patch has been \"accepted\", either.\n \n . When the discussion reaches a consensus that the latest iteration of\n the patches are in good enough shape, the maintainer includes the\n-- \n2.55.0-391-gdf86bf5712\n\n"},{"id":"547856","messageId":"20260711192650.2417665-7-gitster@pobox.com","threadId":"65977","inReplyTo":"20260711192650.2417665-1-gitster@pobox.com","subject":"[PATCH 6/6] SubmittingPatches: clarify the writing style of whats-cooking","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-11T19:26:50Z","receivedAt":"2026-07-11T19:27:01Z","isPatch":true,"body":"Unlike commit log messages, that use present tense to make\nobservations of the current code, and imperative mood to describe\nwhat changes the commit makes, entries in the whats-cooking report\nare written mostly in past or present perfect tense to report what\nhas been done.\n\nSpell it out for contributors.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/SubmittingPatches | 27 ++++++++++++++++++---------\n 1 file changed, 18 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 0a80358703..8917cc3805 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -714,17 +714,26 @@ line via `git format-patch --notes`.\n \n When sending a topic, you can optionally propose a topic name and/or a\n one-paragraph summary that should appear in the \"What's cooking\"\n-report when it is picked up to explain the topic. If you choose to do\n-so, please write a 2-5 line paragraph that will fit well in our\n-release notes (see many bulleted entries in the\n+report when it is picked up to explain the topic.\n+\n+If you choose to do so, please write a 2-5 line paragraph that will\n+fit well in our release notes (see many bulleted entries in the\n Documentation/RelNotes/* files for examples), and make it the first\n (or second, if including a suggested topic name) paragraph of the\n-cover letter. If suggesting a topic name, use the format\n-\"XX/your-topic-name\", where \"XX\" is a stand-in for the primary\n-author's initials, and \"your-topic-name\" is a brief, dash-delimited\n-description of what your topic does. For a single-patch series, use\n-the space between the three-dash line and the diffstat, as described\n-earlier.\n+cover letter.\n+\n+If suggesting a topic name, use the format \"XX/your-topic-name\", where\n+\"XX\" is a stand-in for the primary author's initials, and\n+\"your-topic-name\" is a brief, dash-delimited description of what your\n+topic does. For a single-patch series, use the space between the\n+three-dash line and the diffstat, as described earlier.\n+\n+TIP: When proposing a topic summary in your cover letter, write it in\n+the reporting style (passive voice, past or present perfect tense\n+describing the change as completed, e.g., \"The XYZ subsystem has\n+been updated to...\") rather than the imperative mood, like you do\n+in the proposed commit log messages. This matches the format\n+used in the \"What's cooking\" report and release notes.\n \n [[multi-series-efforts]]\n If your patch series is part of a larger effort spanning multiple\n-- \n2.55.0-391-gdf86bf5712\n\n"},{"id":"547904","messageId":"alOplirhJxIkpDYh@wyuan.org","threadId":"65977","inReplyTo":"20260711192650.2417665-2-gitster@pobox.com","subject":"Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-07-12T14:49:58Z","receivedAt":"2026-07-12T14:50:20Z","isPatch":true,"body":"On Sat, Jul 11, 2026 at 12:26:45PM -0700, Junio C Hamano wrote:\n> The current text on log message has lots of justification and\n> rationale before telling contributors what exactly is expected of\n> them.\n\nNit: s/message/messages/ ?\n\n> Simplify the rationale section and jump straight to what to write\n> and how.\n\n> [...]\n\n> +Reviewers will evaluate your commit message for clarity and structure.\n> +A well-structured commit message typically follows a three-part flow:\n> +**Observation**, **Solution**, and **Command**.\n> \n> -. justifies the way the change solves the problem, i.e. why the\n> - result with the change is better.\n> -\n> -. alternate solutions considered but discarded, if any.\n> +[[meaningful-message]]\n> +==== Structure of a Commit Message\n> \n> -. records the resolution of design or viability concerns raised by the\n> - community during the review, if any, ensuring the historical record\n> - explains why the chosen approach was accepted over alternatives.\n> +0. **Title**:\n> + The first line of the commit log message is the title that lets\n> + readers of `git log --oneline` quickly understand what area the\n> + commit touches and what problem it addresses.\n> \n> +1. **Observation (The Status Quo)**:\n> + Explain the problem you are trying to solve. Describe what is\n> + wrong with the current code *without* your change.\n> ++\n> [[present-tense]]\n> -The problem statement that describes the status quo is written in the\n> -present tense. Write \"The code does X when it is given input Y\",\n> -instead of \"The code used to do Y when given input X\". You do not\n> -have to say \"Currently\"---the status quo in the problem statement is\n> -about the code _without_ your change, by project convention.\n> -\n> -[[imperative-mood]]\n> -Describe your changes in imperative mood, e.g. \"make xyzzy do frotz\"\n> -instead of \"[This patch] makes xyzzy do frotz\" or \"[I] changed xyzzy\n> -to do frotz\", as if you are giving orders to the codebase to change\n> -its behavior. Try to make sure your explanation can be understood\n> -without external resources. Instead of giving a URL to a mailing list\n> -archive, summarize the relevant points of the discussion.\n> +Write this problem statement in the **present tense** (e.g., \"The\n> +code does X when given input Y\", not \"The code used to do Y\"). The\n> +status quo in the problem statement is always about the code without\n> +your change, by project convention. Do not use words like\n> +\"Currently\" to describe this state.\n> +\n> +2. **Solution (The Approach)**:\n> + Justify the way your change solves the problem. Explain why the\n> + proposed approach is better and mention any alternate solutions\n> + considered and discarded.\n> ++\n> +If your change only addresses a subset of a larger problem (e.g.,\n> +handles directories but not files because of characteristic Y),\n> +explain this limitation. This helps future developers understand the\n> +boundaries of your work and whether it can be safely extended.\n> ++\n> +If the change resolves design or viability concerns raised by the\n> +community during prior review rounds, ensure the message records the\n> +resolution, explaining why the chosen approach was accepted over\n> +alternatives.\n> +\n> +3. **Command (The Instruction)**:\n> + [[imperative-mood]]\n> + Command the codebase to change. Write this in the **imperative\n> + mood** (e.g., \"make xyzzy do frotz\" instead of \"This patch makes\n> + xyzzy do...\" or \"I changed xyzzy...\"), as if you are giving orders\n> + to the codebase to change its behavior.\n\nStopped and confused for a moment. I am not sure that \"Command\" belongs\nalongside \"Observation\" and \"Solution\" as a third part of the message.\nSometimes the command still describes the solution. In other words,\nSolution and Command seem not to be logically completely separable.\n\n> +#### Formatting and Style Guidelines\n\nPerhaps using \"====\" here would be in harmony with the existing content.\n\n> +* **The Subject Line (First Line)**:\n> + * Keep it short (50 characters is the soft limit).\n> + * Skip the full stop at the end.\n> + * Prefix the subject with the modified area followed by a colon\n> + and a space (e.g., \"area: subject\"). The area is typically a\n> + filename or identifier (e.g., `doc:`, `transport:`, `t5601:`).\n> + Run `git log --no-merges` on target files to see conventions.\n> + * [[summary-section]]\n> + Do not capitalize the first word after the \"area:\" prefix unless\n> + there is a specific reason (e.g., `HEAD` is always in caps).\n> + E.g., use \"doc: clarify...\", not \"doc: Clarify...\".\n> +\n> +* **The Body**:\n> + * Explain the *why* rather than repeating the *what* of the diff.\n> + * Try to make the explanation self-contained. Avoid relying on\n> + external URLs (like mailing list archives) as the sole\n> + explanation; summarize the relevant points of the discussion\n> + instead.\n> + * Wrap lines to 68-72 columns.\n\nMyFirstContribution:\n This commit message is intentionally formatted to 72 columns per line\n\nShould we update both?\n\nbtw I don't know which editors/projects have the default setting of 68.\nIs it Emacs?\n\nThanks.\n"},{"id":"547909","messageId":"xmqq7bn042ez.fsf@gitster.g","threadId":"65977","inReplyTo":"alOplirhJxIkpDYh@wyuan.org","subject":"Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-12T16:07:32Z","receivedAt":"2026-07-12T16:07:34Z","isPatch":true,"body":"Weijie Yuan writes:\n\n>> +2. **Solution (The Approach)**:\n>> +3. **Command (The Instruction)**:\n>> + [[imperative-mood]]\n>> + Command the codebase to change. Write this in the **imperative\n>> + mood** (e.g., \"make xyzzy do frotz\" instead of \"This patch makes\n>> + xyzzy do...\" or \"I changed xyzzy...\"), as if you are giving orders\n>> + to the codebase to change its behavior.\n>\n> Stopped and confused for a moment. I am not sure that \"Command\" belongs\n> alongside \"Observation\" and \"Solution\" as a third part of the message.\n> Sometimes the command still describes the solution. In other words,\n> Solution and Command seem not to be logically completely separable.\n\nI do not think \"Command the codebase to change\" is a good phrasing.\nIt would have been better to highlight the distinction between the\ndesign of the solution (approach) and the implementation. Perhaps\n\n 2. Design (The Approach)\n\n 3. Implementation (The Changes)\n [[imperative-mood]]\n Describe how the change is implemented. Write this in the\n imperative mood. ...\n\nor something?\n\n>> +#### Formatting and Style Guidelines\n>\n> Perhaps using \"====\" here would be in harmony with the existing content.\n\nIndeed.\n\n>> +* **The Body**:\n>> + * Explain the *why* rather than repeating the *what* of the diff.\n>> + * Try to make the explanation self-contained. Avoid relying on\n>> + external URLs (like mailing list archives) as the sole\n>> + explanation; summarize the relevant points of the discussion\n>> + instead.\n>> + * Wrap lines to 68-72 columns.\n>\n> MyFirstContribution:\n> This commit message is intentionally formatted to 72 columns per line\n>\n> Should we update both?\n\nPerhaps just to stick to \"around 70\".\n\nI do not think the defaults in various editors matter.\n\nThe \"wrap around 70 columns\" rule exists so that in a text based\nemail exchange, where you lose two columns to leading \"> \" when\nquoted, and an additional column with each subsequent reply, the\nlines will still fit on standard 80-column terminals.\n\nThanks.\n"},{"id":"547913","messageId":"DJWSKKVJM03B.1DTV8F9FXG9IF@lfurio.us","threadId":"65977","inReplyTo":"20260711192650.2417665-5-gitster@pobox.com","subject":"Re: [PATCH 4/6] MyFirstContribution: clarify that 'seen' does not mean acceptance","fromName":"Matt Hunter","fromEmail":"m@lfurio.us","sentAt":"2026-07-12T18:08:02Z","receivedAt":"2026-07-12T18:08:09Z","isPatch":true,"body":"On Sat Jul 11, 2026 at 3:26 PM EDT, Junio C Hamano wrote:\n> +\n> +Plenty of early testers use `next` and\n> may report issues. Eventually, changes in `next` will make it to `master`,\n> which is typically considered stable. Finally, when a new release is cut,\n> `maint` is used to base bugfixes onto. As mentioned at the beginning of this\n\nIt feels odd not to reflow this paragraph, where the first line now just\nstops halfway across the width of the paragraph. Though, the diff-churn\nmay not be worth it in your eyes.\n"},{"id":"547916","messageId":"xmqqqzl82fn8.fsf@gitster.g","threadId":"65977","inReplyTo":"DJWSKKVJM03B.1DTV8F9FXG9IF@lfurio.us","subject":"Re: [PATCH 4/6] MyFirstContribution: clarify that 'seen' does not mean acceptance","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-12T19:04:43Z","receivedAt":"2026-07-12T19:04:46Z","isPatch":true,"body":"\"Matt Hunter\" writes:\n\n> On Sat Jul 11, 2026 at 3:26 PM EDT, Junio C Hamano wrote:\n>> +\n>> +Plenty of early testers use `next` and\n>> may report issues. Eventually, changes in `next` will make it to `master`,\n>> which is typically considered stable. Finally, when a new release is cut,\n>> `maint` is used to base bugfixes onto. As mentioned at the beginning of this\n>\n> It feels odd not to reflow this paragraph, where the first line now just\n> stops halfway across the width of the paragraph. Though, the diff-churn\n> may not be worth it in your eyes.\n\nYes, I did not want to force patch readers to review three extra\nlines just to spot a non-existent difference caused by an\nunnecessary reflow. Unlike SubmittingPatches, the target audience\nfor MyFirstContribution is less familiar with our source files than\nexperienced contributors are, so they will not be reading this in\nits source form anyway. Therefore, I thought leaving an unusually\nshort line there was a reasonable trade-off until the entire\nparagraph needs to be rewritten.\n\nHowever, when the next person who wants to modify this source file\nreads it, it will indeed be distracting to them. So, perhaps I\nshould reflow the remainder of the paragraph.\n\nThanks.\n"},{"id":"547920","messageId":"CAC2QwmL05MbVS=jtk7ARj6jJUT461Ws7BcYqUAUrywvDDXjJqg@mail.gmail.com","threadId":"65977","inReplyTo":"20260711192650.2417665-2-gitster@pobox.com","subject":"Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"Michael Montalbo","fromEmail":"mmontalbo@gmail.com","sentAt":"2026-07-12T20:26:43Z","receivedAt":"2026-07-12T20:26:55Z","isPatch":true,"body":"On Sat, Jul 11, 2026 at 12:27 PM Junio C Hamano wrote:\n>\n> +2. **Solution (The Approach)**:\n> + Justify the way your change solves the problem. Explain why the\n> + proposed approach is better and mention any alternate solutions\n> + considered and discarded.\n\nSlight reflow suggestion (answers the question \"better than what?\"\nand is more concise):\n\n\"Explain why the proposed approach is better than any alternate\nsolutions that were considered and discarded.\"\n\n> ++\n> +If your change only addresses a subset of a larger problem (e.g.,\n> +handles directories but not files because of characteristic Y),\n> +explain this limitation. This helps future developers understand the\n> +boundaries of your work and whether it can be safely extended.\n> ++\n> +If the change resolves design or viability concerns raised by the\n> +community during prior review rounds, ensure the message records the\n> +resolution, explaining why the chosen approach was accepted over\n> +alternatives.\n\nIn the spirit of paring down text, this last section seems to overlap with\nthe prior \"alternative solutions considered\" blurb above. Maybe they can\nbe combined?\n\n> +\n> +3. **Command (The Instruction)**:\n\n\"Command\" reads a bit awkwardly to me. I think something about\n\"Implementation\" or another phrase that distinguishes between\nthe mechanics of the change and the design of the change\nmight be more clear.\n\n> + [[imperative-mood]]\n> + Command the codebase to change. Write this in the **imperative\n> + mood** (e.g., \"make xyzzy do frotz\" instead of \"This patch makes\n> + xyzzy do...\" or \"I changed xyzzy...\"), as if you are giving orders\n> + to the codebase to change its behavior.\n> +\n> +#### Formatting and Style Guidelines\n> +\n> +* **The Subject Line (First Line)**:\n> + * Keep it short (50 characters is the soft limit).\n> + * Skip the full stop at the end.\n> + * Prefix the subject with the modified area followed by a colon\n> + and a space (e.g., \"area: subject\"). The area is typically a\n> + filename or identifier (e.g., `doc:`, `transport:`, `t5601:`).\n> + Run `git log --no-merges` on target files to see conventions.\n> + * [[summary-section]]\n> + Do not capitalize the first word after the \"area:\" prefix unless\n> + there is a specific reason (e.g., `HEAD` is always in caps).\n> + E.g., use \"doc: clarify...\", not \"doc: Clarify...\".\n> +\n> +* **The Body**:\n> + * Explain the *why* rather than repeating the *what* of the diff.\n\nI think collapsing the \"Formatting and Style Guidelines\" section with\nthe above would be clearer than having a separate section. The\ncontent prior to this section mixes \"content\" and \"formatting\"\nguidelines so maybe those concepts could be explicitly delineated\nand the advice in this section could be co-located with the commit\nmessage component it is related to above. That might also help\neliminate some redundancy (i.e., another reference to \"why vs.\nwhat\").\n\nSome more general feedback: maybe examples of well vs. poorly\nformed components would help distill the advice for a reader.\n\nOverall, I think reducing the amount of text a contributor needs to\nread in order to get up to speed is a very worthwhile endeavor, so\nthank you!\n"},{"id":"547921","messageId":"CAC2Qwm+30zeMQKHc3onqhXG90wgrdvba28TadF=N3-dD1Ah8zw@mail.gmail.com","threadId":"65977","inReplyTo":"20260711192650.2417665-7-gitster@pobox.com","subject":"Re: [PATCH 6/6] SubmittingPatches: clarify the writing style of whats-cooking","fromName":"Michael Montalbo","fromEmail":"mmontalbo@gmail.com","sentAt":"2026-07-12T20:41:22Z","receivedAt":"2026-07-12T20:41:34Z","isPatch":true,"body":"On Sat, Jul 11, 2026 at 12:27 PM Junio C Hamano wrote:\n> +TIP: When proposing a topic summary in your cover letter, write it in...\n\nsuper nit: It seems like the precedent in this file is to use \"NOTE\" instead\nof \"TIP\".\n"},{"id":"547923","messageId":"xmqqcxwr3g7r.fsf@gitster.g","threadId":"65977","inReplyTo":"CAC2QwmL05MbVS=jtk7ARj6jJUT461Ws7BcYqUAUrywvDDXjJqg@mail.gmail.com","subject":"Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-13T00:07:04Z","receivedAt":"2026-07-13T00:07:06Z","isPatch":true,"body":"Michael Montalbo writes:\n\n> I think collapsing the \"Formatting and Style Guidelines\" section with\n> the above would be clearer than having a separate section.\n\nThanks for pointing it out; I tend to agree.\n\nBefore rerolling the series in entirety, here is what I have in my\neditor buffer right now, after attempting to move the formatting and\nstyles into the main description.\n\nI haven't checked if the formatting works as AsciiDoc yet, though.\n\n--- >8 ---\n[[meaningful-message]]\n==== Structure of a Commit Message\n\n1. Title:\n The first line of the commit log message is the title that lets\n readers of `git log --oneline` quickly understand what area the\n commit touches and what problem it addresses.\n\n - Keep it short (50 characters is the soft limit).\n - Skip the full stop at the end.\n - Prefix the subject with the modified area followed by a colon\n and a space (e.g., \"area: subject\"). The area is typically a\n filename or identifier (e.g., `doc:`, `transport:`, `t5601:`).\n Run `git log --no-merges` on target files to see conventions.\n - Do not capitalize the first word after the \"area:\" prefix\n unless there is a specific reason (e.g., `HEAD` is always in\n uppercase). For example, use \"doc: clarify...\", not \"doc:\n Clarify...\".\n\n2. Body:\n A well-structured commit message body typically follows a\n three-part flow: Observation, Solution Design, and\n Implementation.\n\n - Leave a blank line between the title and the body.\n - Wrap lines in the body of the commit log message to around 70\n columns.\n - The body of the log message must be self-contained. Do not\n rely on external URLs (including mailing list archives) as the\n sole explanation. Summarize the relevant points of external\n material so that readers can understand the change with the log\n message alone.\n\n[[present-tense]]\n3. Observation (The Status Quo):\n Explain the problem you are solving with your change by\n describing what is wrong with the current code *without* your\n change.\n\n - As this part is always about the current state by convention,\n words like \"currently\" are unnecessary.\n - Write this problem statement in the present tense (e.g., \"The\n code does X when given input Y\", not \"The code did X\").\n\n4. Solution Design (The Approach):\n Explain the approach you took, justify how it solves the problem,\n and describe why you chose the particular design over other\n alternatives.\n\n - Focus on describing _why_, not _how_ (e.g., \"The code does X\n when given input Y, but it should do Z _because_...\").\n - If your change only addresses a subset of a larger problem\n (e.g., it handles directories but not files because ...),\n explain this limitation. This helps future developers\n understand the boundaries of your work and whether it can be\n safely extended.\n - If your change resolves design or viability concerns raised by\n the community during prior review rounds, ensure the message\n records the resolution, explaining why the chosen approach was\n accepted over alternatives.\n\n[[imperative-mood]]\n5. Implementation (The Execution):\n Finally, describe how the changes are implemented.\n\n - Write this in the imperative mood (e.g., \"Make xyzzy do frotz\",\n not \"This patch makes xyzzy do...\" or \"I changed xyzzy...\"), as\n if you are instructing an agent to make changes to the\n codebase.\n - You do not have to repeat everything readers can discern from\n the patch text. Highlight the key points in your\n implementation.\n"},{"id":"547937","messageId":"xmqqmrvv1px6.fsf@gitster.g","threadId":"65977","inReplyTo":"CAC2Qwm+30zeMQKHc3onqhXG90wgrdvba28TadF=N3-dD1Ah8zw@mail.gmail.com","subject":"Re: [PATCH 6/6] SubmittingPatches: clarify the writing style of whats-cooking","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-13T04:20:21Z","receivedAt":"2026-07-13T04:20:24Z","isPatch":true,"body":"Michael Montalbo writes:\n\n> On Sat, Jul 11, 2026 at 12:27 PM Junio C Hamano wrote:\n>> +TIP: When proposing a topic summary in your cover letter, write it in...\n>\n> super nit: It seems like the precedent in this file is to use \"NOTE\" instead\n> of \"TIP\".\n\nYeah, and not just locally in this file; \"TIP:\" is actually\nnot used anywhere in the Documentation/ directory, whereas\n\"NOTE:\" is frequently used. I will switch to \"NOTE:\" as\nthere is no point in having variety in something like this.\n\nThanks.\n"},{"id":"547998","messageId":"alTyt7hVW6gQOWQ4@wyuan.org","threadId":"65977","inReplyTo":"xmqq7bn042ez.fsf@gitster.g","subject":"Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-07-13T14:14:15Z","receivedAt":"2026-07-13T14:14:49Z","isPatch":true,"body":"On Sun, Jul 12, 2026 at 09:07:32AM -0700, Junio C Hamano wrote:\n> Weijie Yuan writes:\n> \n> >> +2. **Solution (The Approach)**:\n> >> +3. **Command (The Instruction)**:\n> >> + [[imperative-mood]]\n> >> + Command the codebase to change. Write this in the **imperative\n> >> + mood** (e.g., \"make xyzzy do frotz\" instead of \"This patch makes\n> >> + xyzzy do...\" or \"I changed xyzzy...\"), as if you are giving orders\n> >> + to the codebase to change its behavior.\n> >\n> > Stopped and confused for a moment. I am not sure that \"Command\" belongs\n> > alongside \"Observation\" and \"Solution\" as a third part of the message.\n> > Sometimes the command still describes the solution. In other words,\n> > Solution and Command seem not to be logically completely separable.\n> \n> I do not think \"Command the codebase to change\" is a good phrasing.\n> It would have been better to highlight the distinction between the\n> design of the solution (approach) and the implementation. Perhaps\n> \n> 2. Design (The Approach)\n> \n> 3. Implementation (The Changes)\n> [[imperative-mood]]\n> Describe how the change is implemented. Write this in the\n> imperative mood. ...\n> \n> or something?\n\nYeah, that is much clearer. I'm reading your draft in your reply to\nMichael, seems good.\n\n> >> +* **The Body**:\n> >> + * Explain the *why* rather than repeating the *what* of the diff.\n> >> + * Try to make the explanation self-contained. Avoid relying on\n> >> + external URLs (like mailing list archives) as the sole\n> >> + explanation; summarize the relevant points of the discussion\n> >> + instead.\n> >> + * Wrap lines to 68-72 columns.\n> >\n> > MyFirstContribution:\n> > This commit message is intentionally formatted to 72 columns per line\n> >\n> > Should we update both?\n> \n> Perhaps just to stick to \"around 70\".\n> \n> I do not think the defaults in various editors matter.\n> \n> The \"wrap around 70 columns\" rule exists so that in a text based\n> email exchange, where you lose two columns to leading \"> \" when\n> quoted, and an additional column with each subsequent reply, the\n> lines will still fit on standard 80-column terminals.\n\nYes, got it. I just want to say that I often see 72 columns, but I\nhaven't seen 68 very often. (maybe I'm too young ;-)\n\nThanks.\n"},{"id":"547999","messageId":"alTy306FaTAe2E8w@wyuan.org","threadId":"65977","inReplyTo":"xmqqcxwr3g7r.fsf@gitster.g","subject":"Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-07-13T14:14:55Z","receivedAt":"2026-07-13T14:15:15Z","isPatch":true,"body":"On Sun, Jul 12, 2026 at 05:07:04PM -0700, Junio C Hamano wrote:\n> Michael Montalbo writes:\n> \n> > I think collapsing the \"Formatting and Style Guidelines\" section with\n> > the above would be clearer than having a separate section.\n> \n> Thanks for pointing it out; I tend to agree.\n> \n> Before rerolling the series in entirety, here is what I have in my\n> editor buffer right now, after attempting to move the formatting and\n> styles into the main description.\n> \n> I haven't checked if the formatting works as AsciiDoc yet, though.\n> \n> --- >8 ---\n> [[meaningful-message]]\n> ==== Structure of a Commit Message\n> \n> 1. Title:\n> The first line of the commit log message is the title that lets\n> readers of `git log --oneline` quickly understand what area the\n> commit touches and what problem it addresses.\n> \n> - Keep it short (50 characters is the soft limit).\n> - Skip the full stop at the end.\n> - Prefix the subject with the modified area followed by a colon\n> and a space (e.g., \"area: subject\"). The area is typically a\n> filename or identifier (e.g., `doc:`, `transport:`, `t5601:`).\n> Run `git log --no-merges` on target files to see conventions.\n> - Do not capitalize the first word after the \"area:\" prefix\n> unless there is a specific reason (e.g., `HEAD` is always in\n> uppercase). For example, use \"doc: clarify...\", not \"doc:\n> Clarify...\".\n> \n> 2. Body:\n> A well-structured commit message body typically follows a\n> three-part flow: Observation, Solution Design, and\n> Implementation.\n> \n> - Leave a blank line between the title and the body.\n> - Wrap lines in the body of the commit log message to around 70\n> columns.\n> - The body of the log message must be self-contained. Do not\n> rely on external URLs (including mailing list archives) as the\n> sole explanation. Summarize the relevant points of external\n> material so that readers can understand the change with the log\n> message alone.\n> \n> [[present-tense]]\n> 3. Observation (The Status Quo):\n> Explain the problem you are solving with your change by\n> describing what is wrong with the current code *without* your\n> change.\n> \n> - As this part is always about the current state by convention,\n> words like \"currently\" are unnecessary.\n> - Write this problem statement in the present tense (e.g., \"The\n> code does X when given input Y\", not \"The code did X\").\n> \n> 4. Solution Design (The Approach):\n> Explain the approach you took, justify how it solves the problem,\n> and describe why you chose the particular design over other\n> alternatives.\n> \n> - Focus on describing _why_, not _how_ (e.g., \"The code does X\n> when given input Y, but it should do Z _because_...\").\n> - If your change only addresses a subset of a larger problem\n> (e.g., it handles directories but not files because ...),\n> explain this limitation. This helps future developers\n> understand the boundaries of your work and whether it can be\n> safely extended.\n> - If your change resolves design or viability concerns raised by\n> the community during prior review rounds, ensure the message\n> records the resolution, explaining why the chosen approach was\n> accepted over alternatives.\n> \n> [[imperative-mood]]\n> 5. Implementation (The Execution):\n> Finally, describe how the changes are implemented.\n> \n> - Write this in the imperative mood (e.g., \"Make xyzzy do frotz\",\n> not \"This patch makes xyzzy do...\" or \"I changed xyzzy...\"), as\n> if you are instructing an agent to make changes to the\n> codebase.\n> - You do not have to repeat everything readers can discern from\n> the patch text. Highlight the key points in your\n> implementation.\n\nI think this might confuse readers. Now you place these points in\nparallel:\n\n 1. Title\n 2. Body\n 3. Observation (The Status Quo)\n 4. Solution Design (The Approach)\n 5. Implementation (The Execution)\n\nBut acatually you mean:\n\n1. Title\n2. Body\n The body typically follows three parts:\n a. Observation\n b. Solution Design\n c. Implementation\n\nBut I haven't written much about adoc, so I don't know its syntax and\nhow to write it.\n"},{"id":"548172","messageId":"CALnO6CD8HFWaeN-4Gccopy0nw601cMyak_LSXfTsAa8xwOjKpQ@mail.gmail.com","threadId":"65977","inReplyTo":"alTy306FaTAe2E8w@wyuan.org","subject":"Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-07-14T22:46:05Z","receivedAt":"2026-07-14T22:46:17Z","isPatch":true,"body":"On Mon, Jul 13, 2026 at 10:42 AM Weijie Yuan wrote:\n>\n[snip]\n> I think this might confuse readers. Now you place these points in\n> parallel:\n>\n> 1. Title\n> 2. Body\n> 3. Observation (The Status Quo)\n> 4. Solution Design (The Approach)\n> 5. Implementation (The Execution)\n\nWithout commenting on \"confuse,\" I find this style of heading\n\n Thing (The Other Thing)\n\nneedlessly suggests an LLM's involvement with the text. That by itself\nis not grounds for my objection; instead, I'll note that often the\nparenthetical restates the original header in some way. That makes it\nredundant. (In some cases in the wild I have seen examples where the 2\nwere not synonymous, which _is_ confusing :)\n\n\n> But acatually you mean:\n>\n> 1. Title\n> 2. Body\n> The body typically follows three parts:\n> a. Observation\n> b. Solution Design\n> c. Implementation\n>\n> But I haven't written much about adoc, so I don't know its syntax and\n> how to write it.\n\nThis is nice. If I had to suggest anything further, it would be \"don't\nbe afraid of long headings\":\n\n1. Title: Summarize the change\n2. Body: Describe [Justify?] the change\n a. Observe the status quo\n b. Explain your approach [solution/design/etc.]\n c. Command the code to change [or: Describe the implementation/execution]\n\n?\n\n-- \nD. Ben Knoble\n"},{"id":"548497","messageId":"aloOAwOtutgPbJu2@pks.im","threadId":"65977","inReplyTo":"20260711192650.2417665-3-gitster@pobox.com","subject":"Re: [PATCH 2/6] MyFirstContribution: what if I don't get a reply?","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-07-17T11:12:03Z","receivedAt":"2026-07-17T11:12:11Z","isPatch":true,"body":"On Sat, Jul 11, 2026 at 12:26:46PM -0700, Junio C Hamano wrote:\n> Tell readers that pinging is a perfectly sensible thing to do when\n> they do not see a response.\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/MyFirstContribution.adoc | 13 +++++++++++++\n> 1 file changed, 13 insertions(+)\n> \n> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> index 4832e5bad5..fc2ce2e785 100644\n> --- a/Documentation/MyFirstContribution.adoc\n> +++ b/Documentation/MyFirstContribution.adoc\n> @@ -1438,6 +1438,19 @@ substantial rework, and mention which parts of the current series will become\n> obsolete so reviewers can avoid spending time on them until the updated series\n> is ready.\n> \n> +=== What if I don't get a reply?\n> +\n> +If you don't receive any review comments after a week or two, do not\n> +assume your patch has been accepted or merged. In the Git project,\n> +silence does not equal approval. It usually means reviewers are busy\n> +or haven't noticed your contribution.\n\nShould we also add the third reason: reviewers are simply not interested\nin the patch? It's a bit brutal, but that's quite a common reason, too.\nIn the best case we'd of course tell the submitter that we don't want\nthe patch to not leave them hanging.\n\n> +If your patch is overlooked, it is perfectly acceptable to send a\n> +polite ping to the thread. You can do this by replying to your own\n> +cover letter (or patch) to ask if anyone has had a chance to look at\n> +it. You can also CC additional people who might be interested; use\n> +the `git-contacts` script (mentioned earlier) to find relevant contributors.\n\nAnd this paragraph here can remain as-is regardless of which of the\nthree reasons applies.\n\nPatrick\n"},{"id":"548498","messageId":"alojTem4a5q1Xu4X@wyuan.org","threadId":"65977","inReplyTo":"CALnO6CD8HFWaeN-4Gccopy0nw601cMyak_LSXfTsAa8xwOjKpQ@mail.gmail.com","subject":"Re: [PATCH 1/6] SubmittingPatches: clarify expected structure of commit log message","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-07-17T12:42:53Z","receivedAt":"2026-07-17T12:43:02Z","isPatch":true,"body":"On Tue, Jul 14, 2026 at 06:46:05PM -0400, D. Ben Knoble wrote:\n> On Mon, Jul 13, 2026 at 10:42 AM Weijie Yuan wrote:\n> >\n> [snip]\n> > I think this might confuse readers. Now you place these points in\n> > parallel:\n> >\n> > 1. Title\n> > 2. Body\n> > 3. Observation (The Status Quo)\n> > 4. Solution Design (The Approach)\n> > 5. Implementation (The Execution)\n> \n> Without commenting on \"confuse,\" I find this style of heading\n> \n> Thing (The Other Thing)\n> \n> needlessly suggests an LLM's involvement with the text.\n\nAha, kind of. But I guess Junio didn't use LLM here ;-)\n\n> That by itself is not grounds for my objection; instead, I'll note\n> that often the parenthetical restates the original header in some way.\n> That makes it redundant. (In some cases in the wild I have seen\n> examples where the 2 were not synonymous, which _is_ confusing :)\n\nTrue.\n\n> > But acatually you mean:\n> >\n> > 1. Title\n> > 2. Body\n> > The body typically follows three parts:\n> > a. Observation\n> > b. Solution Design\n> > c. Implementation\n> >\n> > But I haven't written much about adoc, so I don't know its syntax and\n> > how to write it.\n> \n> This is nice. If I had to suggest anything further, it would be \"don't\n> be afraid of long headings\":\n> \n> 1. Title: Summarize the change\n> 2. Body: Describe [Justify?] the change\n> a. Observe the status quo\n> b. Explain your approach [solution/design/etc.]\n> c. Command the code to change [or: Describe the implementation/execution]\n> \n> ?\n\nI agree. More explanatory descriptions here are very likely to enable\ncontributors to express their ideas more clearly and understandably.\n"},{"id":"548517","messageId":"xmqqwlut64rx.fsf@gitster.g","threadId":"65977","inReplyTo":"aloOAwOtutgPbJu2@pks.im","subject":"Re: [PATCH 2/6] MyFirstContribution: what if I don't get a reply?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-17T14:59:30Z","receivedAt":"2026-07-17T14:59:34Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> On Sat, Jul 11, 2026 at 12:26:46PM -0700, Junio C Hamano wrote:\n>> Tell readers that pinging is a perfectly sensible thing to do when\n>> they do not see a response.\n>> \n>> Signed-off-by: Junio C Hamano \n>> ---\n>> Documentation/MyFirstContribution.adoc | 13 +++++++++++++\n>> 1 file changed, 13 insertions(+)\n>> \n>> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n>> index 4832e5bad5..fc2ce2e785 100644\n>> --- a/Documentation/MyFirstContribution.adoc\n>> +++ b/Documentation/MyFirstContribution.adoc\n>> @@ -1438,6 +1438,19 @@ substantial rework, and mention which parts of the current series will become\n>> obsolete so reviewers can avoid spending time on them until the updated series\n>> is ready.\n>> \n>> +=== What if I don't get a reply?\n>> +\n>> +If you don't receive any review comments after a week or two, do not\n>> +assume your patch has been accepted or merged. In the Git project,\n>> +silence does not equal approval. It usually means reviewers are busy\n>> +or haven't noticed your contribution.\n>\n> Should we also add the third reason: reviewers are simply not interested\n> in the patch? It's a bit brutal, but that's quite a common reason, too.\n\nYeah, I agree that it would make a good addition.\n\n"}]}