SubmittingPatches: guidance for topic names and multi-series efforts
cover SubmittingPatches: guidance for topic names and multi-series efforts
A note to the maintainer, I suggest queueing this as:
* tb/submitting-patches
Extend the experimental protocol used by contributors to propose a topic branch name in addition to a description, and describe how to name multi-series efforts.
---
In [1], Junio suggested a few points to stress in our SubmittingPatches documentation, which are:
- Mentioning what topics not in 'master' your patches depend on.
- Suggesting one-line summaries for topics to be used as a topic branch name.
- Describing your topic in the context of a multi-series effort.
The first is already covered by 0a02ca2383 (SubmittingPatches:
simplify guidance for choosing a starting point, 2023-07-14), but the latter two are not.
The two patches part of this series address the latter two suggestions.
(As an aside, we should consider whether or not the experiment started in d255105c99 (SubmittingPatches: release-notes entry experiment, 2024-03-25) can yet be declared a success, and if so, graduate it.)
Thanks in advance for your review!
[1]: https://lore.kernel.org/git/[email protected]/
Taylor Blau (2):
SubmittingPatches: extend release-notes experiment to topic names
SubmittingPatches: guidance for multi-series efforts
Documentation/SubmittingPatches | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-)
base-commit: 45547b60aca32b45d2f1ef93462cf9df28637c13
Signature · 1 line
2.51.0.435.gf7a65e208c7
PATCH 1/2 SubmittingPatches: extend release-notes experiment to topic names
In d255105c99 (SubmittingPatches: release-notes entry experiment, 2024-03-25), we began an experiment to have contributors suggest a topic description to appear in our RelNotes and "What's cooking?" reports. Extend that experiment to also welcome suggested topic branch names in addition to descriptions.
--- Documentation/SubmittingPatches | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-)
Documentation/SubmittingPatches +13 -8
@@ -579,14 +579,19 @@ line via `git format-patch --notes`. [[the-topic-summary]] *This is EXPERIMENTAL*. -When sending a topic, you can propose 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 Documentation/RelNotes/* files for examples), and make -it the first paragraph of the cover letter. For a single-patch -series, use the space between the three-dash line and the diffstat, as -described earlier. +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 +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. [[attachment]] Do not attach the patch as a MIME attachment, compressed or not.
Signature · 1 line
2.51.0.435.gf7a65e208c7
PATCH 2/2 SubmittingPatches: guidance for multi-series efforts
In reply to Taylor BlauOccasionally there are efforts to contribute to the Git project that span more than one patch series in order to achieve a broader goal. By convention, the maintainer has typically suffixed the topic names with "-part-one", or "-part-1" and so on.
Document that convention and suggest some guidance on how to structure proposed topic names for multi-series efforts.
--- Documentation/SubmittingPatches | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/SubmittingPatches +8 -0
@@ -593,6 +593,14 @@ 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. +[[multi-series-efforts]] +If your patch series is part of a larger effort spanning multiple +patch series, briefly describe the broader goal, and state where the +current series fits into that goal. If you are suggesting a topic +name as in <<the-topic-summary, section above>>, consider +"XX/the-broader-goal-part-one", "XX/the-broader-goal-part-two", and so +on. + [[attachment]] Do not attach the patch as a MIME attachment, compressed or not. Do not let your e-mail client send quoted-printable. Do not let
Signature · 1 line
2.51.0.435.gf7a65e208c7
Quoted 3 lines · Taylor Blau
(As an aside, we should consider whether or not the experiment started in
d255105c99(SubmittingPatches: release-notes entry experiment, 2024-03-25) can yet be declared a success, and if so, graduate it.)
Thanks. I haven't seen this used very often, though. Perhaps it was a failed experiment that needs to be retracted?
Re: [PATCH 1/2] SubmittingPatches: extend release-notes experiment to topic names
In reply to Taylor BlauQuoted 5 lines · Taylor Blau
In
d255105c99(SubmittingPatches: release-notes entry experiment, 2024-03-25), we began an experiment to have contributors suggest a topic description to appear in our RelNotes and "What's cooking?" reports. Extend that experiment to also welcome suggested topic branch names in addition to descriptions.
This is a nice idea for keeping track of the upstream topic.
Quoted 17 lines
[snip]
Documentation/SubmittingPatches +0
-8@@ -579,14 +579,19 @@ line via `git format-patch --notes`. [[the-topic-summary]] *This is EXPERIMENTAL*. -When sending a topic, you can propose 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 Documentation/RelNotes/* files for examples), and make -it the first paragraph of the cover letter. For a single-patch -series, use the space between the three-dash line and the diffstat, as -described earlier.
Documentation/SubmittingPatches line via `git format-patch --notes`. · line 591
Quoted 10 lines
Documentation/SubmittingPatches +10
-0+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 +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
Is there a precedent for “primary” author? Why not just “author”?
This seems to be referring to the fact that patches might have co-authors (trailers) and similar, or that it could be sent from someone else but the author, but I don’t think this adjective makes it clear that the topic name should stick to the author (in the Git model’s sense) name only.
Quoted 8 lines
Documentation/SubmittingPatches +3
-1+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. [[attachment]] Do not attach the patch as a MIME attachment, compressed or not. --2.51.0.435.gf7a65e208c7
I like the format in the cover letter:
* tb/submitting-patches
Extend the experimental protocol used by contributors to propose a topic branch name in addition to a description, and describe how to name multi-series efforts.
---
Everything is nicely *delimited* so to speak.
But it was noted[1] that the-topic-summary doesn’t seem to have been used much. That’s not surprising given that the instruction makes the-topic-summary blend in with the rest of the cover letter and doesn’t signal that the author intends for the first paragraph to be used as such. This patch shares the same problem.
I think it would be nice to distinguish these things with some initial paragraph text. In the case of the-topic-summary:
1. Start a paragraph with Topic summary:
2. Then continue the paragraph with an explanation that would fit well in our release notes (see many bulleted entries in the Documentation/RelNotes/* files for examples). Aim for 2-5 lines.
In the case of topic-name:
- Add a paragraph with Topic name: XX/your-topic-name where XX is the author's initials.
Then it might be possible to drop “at the start of” *if* the aim of that part is to be able to pick up the intended paragraphs reliably. (Maybe the intent is for the maintainer to be able to read the cover letter in a predictable order.)
Re: [PATCH 1/2] SubmittingPatches: extend release-notes experiment to topic names
Quoted 7 lines · Kristoffer Haugsbakk
I like the format in the cover letter:
* tb/submitting-patches
Extend the experimental protocol used by contributors to propose a topic branch name in addition to a description, and describe how to name multi-series efforts.
Hmph, but the paragraphs that eventually go into RelNotes are not commit log messages. "Extend the protocol A to achieve X" is what we would write in our proposed log messages, but after such a patch achieves X by extending the protocol A, we'd report it in our release notes by saying something ike "The protocol A was extended in such and such way to achieve X".
Quoted 5 lines
But it was noted[1] that the-topic-summary doesn’t seem to have been used much. That’s not surprising given that the instruction makes the-topic-summary blend in with the rest of the cover letter and doesn’t signal that the author intends for the first paragraph to be used as such. This patch shares the same problem.
Oh, that's a new theory. So you are saying that authors may have tried but I (and others) failed to notice? It cetainly is possible.
Re: [PATCH 1/2] SubmittingPatches: extend release-notes experiment to topic names
In reply to Kristoffer HaugsbakkQuoted 29 lines · Kristoffer Haugsbakk
Quoted 16 lines
Documentation/SubmittingPatches +0
-8@@ -579,14 +579,19 @@ line via `git format-patch --notes`. [[the-topic-summary]] *This is EXPERIMENTAL*. -When sending a topic, you can propose 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 Documentation/RelNotes/* files for examples), and make -it the first paragraph of the cover letter. For a single-patch -series, use the space between the three-dash line and the diffstat, as -described earlier.Documentation/SubmittingPatches line via `git format-patch --notes`. · line 591
Quoted 10 lines
Documentation/SubmittingPatches +10
-0+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 +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-delimitedIs there a precedent for “primary” author? Why not just “author”?
Quoted 5 lines
This seems to be referring to the fact that patches might have co-authors (trailers) and similar, or that it could be sent from someone else but the author, but I don’t think this adjective makes it clear that the topic name should stick to the author (in the Git model’s sense) name only.
I wrote it this way to account for individuals listed under the Co-authored-by trailer. I'm not entirely sure that I'm following the latter half of this sentence. Could you clarify what you mean?
Quoted 5 lines
But it was noted[1] that the-topic-summary doesn’t seem to have been used much. That’s not surprising given that the instruction makes the-topic-summary blend in with the rest of the cover letter and doesn’t signal that the author intends for the first paragraph to be used as such. This patch shares the same problem.
That's fair, though I admittedly dislike the idea of prescribing a format for the cover letter. It should be clear to those (such as the maintainer) who are reading the cover letter closely whether or not the first paragraph (or two) are meant to be used as the topic name/summary.
Perhaps I am in the minority in thinking that, though, in which case I am happy to continue to discuss/explore other options.
Thanks,
Taylor
Re: [PATCH 1/2] SubmittingPatches: extend release-notes experiment to topic names
In reply to Junio C HamanoQuoted 10 lines · Junio C Hamano
Quoted 7 lines · Kristoffer Haugsbakk
I like the format in the cover letter:
* tb/submitting-patches
Extend the experimental protocol used by contributors to propose a topic branch name in addition to a description, and describe how to name multi-series efforts.
Quoted 6 lines
Hmph, but the paragraphs that eventually go into RelNotes are not commit log messages. "Extend the protocol A to achieve X" is what we would write in our proposed log messages, but after such a patch achieves X by extending the protocol A, we'd report it in our release notes by saying something ike "The protocol A was extended in such and such way to achieve X".
Fair, though I think the existing documentation suffers from the same issue. It says both:
you can propose a one-paragraph summary that should appear in the "What's cooking" report
and:
Please write a 2-5 line paragraph that will fit well in our release notes.
I think that's a separate issue that we should clarify as a prerequisite to the two patches proposed here.
Quoted 8 lines
Quoted 5 lines
But it was noted[1] that the-topic-summary doesn’t seem to have been used much. That’s not surprising given that the instruction makes the-topic-summary blend in with the rest of the cover letter and doesn’t signal that the author intends for the first paragraph to be used as such. This patch shares the same problem.
Oh, that's a new theory. So you are saying that authors may have tried but I (and others) failed to notice? It cetainly is possible.
Certainly possible indeed, but I am not so sure this is happening. At least from the series that I have looked at since this experiment was introduced, I have seen vanishingly few examples of contributors following the process suggested here.
Perhaps I am missing them too, but my sense is that it's likelier that contributors just simply aren't doing this rather than doing it and both of us are not noticing it.
That may be an argument for dropping this section entirely and declaring the experiment as having failed?
Thanks,
Taylor
Re: [PATCH 1/2] SubmittingPatches: extend release-notes experiment to topic names
In reply to Taylor BlauQuoted 5 lines · Taylor Blau
[snip]
I wrote it this way to account for individuals listed under the Co-authored-by trailer. I'm not entirely sure that I'm following the latter half of this sentence. Could you clarify what you mean?
Sorry. I tried to say that: I don’t think “primary” makes it more clear that one should use the Git author compared to just “author”.
Quoted 11 lines
Quoted 5 lines
But it was noted[1] that the-topic-summary doesn’t seem to have been used much. That’s not surprising given that the instruction makes the-topic-summary blend in with the rest of the cover letter and doesn’t signal that the author intends for the first paragraph to be used as such. This patch shares the same problem.
That's fair, though I admittedly dislike the idea of prescribing a format for the cover letter. It should be clear to those (such as the maintainer) who are reading the cover letter closely whether or not the first paragraph (or two) are meant to be used as the topic name/summary.
I think saying that the cover letter should start with them is just as much of a prescription as saying that they should be marked with some paragraph-prefix (and be somewhere in the cover letter). Some people might prefer to start the letter with what they think are important call-out information and get to the topic summary later. For example.
Quoted 1 line
[snip]
Re: [PATCH 1/2] SubmittingPatches: extend release-notes experiment to topic names
In reply to Taylor BlauQuoted 7 lines · Taylor Blau
[snip]
Quoted 6 lines
Quoted 5 lines
But it was noted[1] that the-topic-summary doesn’t seem to have been used much. That’s not surprising given that the instruction makes the-topic-summary blend in with the rest of the cover letter and doesn’t signal that the author intends for the first paragraph to be used as such. This patch shares the same problem.
Quoted 8 lines
Quoted 2 lines
Oh, that's a new theory. So you are saying that authors may have tried but I (and others) failed to notice? It cetainly is possible.
Certainly possible indeed, but I am not so sure this is happening. At least from the series that I have looked at since this experiment was introduced, I have seen vanishingly few examples of contributors following the process suggested here.
I had a look and found one cover letter where I definitely tried to use the-topic-summary:
The documentation for git-bundle(1) now prominently covers --all, the option from git-rev-list(1) that can be used to package all refs. A "Discussion" section has also been added to address the naive backup strategy of copying a Git repository manually with cp(1) or some other non-Git tool.
---
The part above was for the-topic-summary.
https://lore.kernel.org/git/[email protected]/
The merge commit message and the release note entry:
Documentation for "git bundle" saw improvements to more prominently call out the use of '--all' when creating bundles.
Contrasted with no judgement.
Quoted 1 line
[snip]