{"thread":{"id":"61202","subject":"[PATCH v2] SubmittingPatches: release-notes entry experiment","startedAt":"2024-03-25T22:21:47Z","lastAt":"2024-03-26T16:29:09Z","messageCount":7,"participants":["Junio C Hamano","Brian Lyles","Dragan Simic","Phillip Wood"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"491536","messageId":"xmqq8r26eyva.fsf@gitster.g","threadId":"61202","inReplyTo":null,"subject":"[PATCH v2] SubmittingPatches: release-notes entry experiment","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-25T22:21:45Z","receivedAt":"2024-03-25T22:21:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The \"What's cooking\" report lists the topics in flight, with a short\nparagraph descibing what they are about.\n\nOnce written, the description is automatically picked up from the\n\"What's cooking\" report and used in the commit log message of the\nmerge commit when the topic is merged into integration branches.\nThese commit log messges of the merge commits are then propagated to\nthe release notes.\n\nIt has been the maintainer's task to prepare these entries in the\n\"What's cooking\" report. Even though the original author of a topic\nmay be in the best position to write the initial description of a\ntopic, we so far lacked a formal channel for the author to suggest\nwhat description to use. The usual procedure has been for the\nauthor to see the topic described in \"What's cooking\" report, and\nthen either complain about inaccurate explanation and/or offer a\nrewrite.\n\nLet's try an experiment to optionally let the author propose the one\nparagraph description when the topic is submitted. Pick the cover\nletter as the logical place to do so, and describe an experimental\nworkflow in the SubmittingPatches document.\n\nSigned-off-by: Junio C Hamano \n---\n * An experimental procedure for a topic author to propose the topic\n description to be used in \"What's cooking\" report and in the\n release notes have been added to the SubmittingPatches document.\n\n The above is an example that follows this protocol for a\n single-patch series.\n\n >> Would it be beneficial to request some specific heading, phrase, or\n >> other structured text such that this summary is obvious, or even easily\n >> extracted with some sort of script? Or is that perhaps overkill for now?\n >\n > ... the rule might end up\n > to be as simple as \"When the first paragraph of the message looks\n > like an entry in the Release Notes, it is used as such\".\n\nRange-diff:\n1: 83f8b69ab9 ! 1: 86b861255b SubmittingPatches: release-notes entry experiment\n ## Documentation/SubmittingPatches ##\n @@ Documentation/SubmittingPatches: an explanation of changes between each iteration can be kept in\n @@ Documentation/SubmittingPatches: an explanation of changes between each iteratio\n +paragraph summary that appears in the \"What's cooking\" report when it\n +is picked up to explain the topic. If you choose to do so, please\n +write 2-5 lines of a paragraph that will fit well in our release notes\n -+(see Documentation/RelNotes/* directory for examples), and put it in\n -+the cover letter, clearly marked as such. For a single-patch series,\n ++(see Documentation/RelNotes/* directory for examples), and make it\n ++the first paragraph of the cover letter. For a single-patch series,\n +use the space between the three-dash line and the diffstat, as\n +described earlier.\n +\n\n Documentation/SubmittingPatches | 11 +++++++++++\n 1 file changed, 11 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex e734a3f0f1..e29a3d9a5b 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -459,6 +459,17 @@ an explanation of changes between each iteration can be kept in\n Git-notes and inserted automatically following the three-dash\n line via `git format-patch --notes`.\n \n+[[a-paragraph-summary]]\n+\n+*This is EXPERIMENTAL*. When sending a topic, you can propose one\n+paragraph summary that appears in the \"What's cooking\" report when it\n+is picked up to explain the topic. If you choose to do so, please\n+write 2-5 lines of a paragraph that will fit well in our release notes\n+(see Documentation/RelNotes/* directory for examples), and make it\n+the first paragraph of the cover letter. For a single-patch series,\n+use the space between the three-dash line and the diffstat, as\n+described earlier.\n+\n [[attachment]]\n Do not attach the patch as a MIME attachment, compressed or not.\n Do not let your e-mail client send quoted-printable. Do not let\n-- \n2.44.0-325-g11c821f2f2\n\n\n"},{"id":"491553","messageId":"17c0263586f87125.70b1dd9aae081c6e.203dcd72f6563036@zivdesk","threadId":"61202","inReplyTo":"xmqq8r26eyva.fsf@gitster.g","subject":"Re: [PATCH v2] SubmittingPatches: release-notes entry experiment","fromName":"Brian Lyles","fromEmail":"brianmlyles@gmail.com","sentAt":"2024-03-25T23:37:49Z","receivedAt":"2024-03-25T23:37:51Z","isPatch":true,"sender":{"key":"brianmlyles@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1123282?v=4"},"body":"Hi Junio\n\nOn Mon, Mar 25, 2024 at 5:21 PM Junio C Hamano wrote:\n\n> +[[a-paragraph-summary]]\n> +\n> +*This is EXPERIMENTAL*. When sending a topic, you can propose one\n> +paragraph summary that appears in the \"What's cooking\" report when it\n> +is picked up to explain the topic. If you choose to do so, please\n> +write 2-5 lines of a paragraph that will fit well in our release notes\n> +(see Documentation/RelNotes/* directory for examples), and make it\n> +the first paragraph of the cover letter. For a single-patch series,\n> +use the space between the three-dash line and the diffstat, as\n> +described earlier.\n> +\n\nOne very minor grammar note: \"you can propose *a* one paragraph\nsummary\".\n\nOtherwise, this patch looks good to me. Thanks for considering this.\n\n-- \nThank you,\nBrian Lyles\n"},{"id":"491559","messageId":"xmqqplvhe9cs.fsf@gitster.g","threadId":"61202","inReplyTo":"17c0263586f87125.70b1dd9aae081c6e.203dcd72f6563036@zivdesk","subject":"Re: [PATCH v2] SubmittingPatches: release-notes entry experiment","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-26T07:32:51Z","receivedAt":"2024-03-26T07:32:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Brian Lyles\" writes:\n\n>> +*This is EXPERIMENTAL*. When sending a topic, you can propose one\n>> +paragraph summary that appears in the \"What's cooking\" report when it\n>> +is picked up to explain the topic. If you choose to do so, please\n>> +write 2-5 lines of a paragraph that will fit well in our release notes\n>> +(see Documentation/RelNotes/* directory for examples), and make it\n>> +the first paragraph of the cover letter. For a single-patch series,\n>> +use the space between the three-dash line and the diffstat, as\n>> +described earlier.\n>> +\n>\n> One very minor grammar note: \"you can propose *a* one paragraph\n> summary\".\n\nOh, yeah, of course. Thanks for carefully reading.\n"},{"id":"491560","messageId":"506be88207b63ed25067c374d3da8c09@manjaro.org","threadId":"61202","inReplyTo":"xmqq8r26eyva.fsf@gitster.g","subject":"Re: [PATCH v2] SubmittingPatches: release-notes entry experiment","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-03-26T07:43:08Z","receivedAt":"2024-03-26T07:43:11Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-03-25 23:21, Junio C Hamano wrote:\n> The \"What's cooking\" report lists the topics in flight, with a short\n> paragraph descibing what they are about.\n> \n> Once written, the description is automatically picked up from the\n> \"What's cooking\" report and used in the commit log message of the\n> merge commit when the topic is merged into integration branches.\n> These commit log messges of the merge commits are then propagated to\n> the release notes.\n> \n> It has been the maintainer's task to prepare these entries in the\n> \"What's cooking\" report. Even though the original author of a topic\n> may be in the best position to write the initial description of a\n> topic, we so far lacked a formal channel for the author to suggest\n> what description to use. The usual procedure has been for the\n> author to see the topic described in \"What's cooking\" report, and\n> then either complain about inaccurate explanation and/or offer a\n> rewrite.\n> \n> Let's try an experiment to optionally let the author propose the one\n> paragraph description when the topic is submitted. Pick the cover\n> letter as the logical place to do so, and describe an experimental\n> workflow in the SubmittingPatches document.\n> \n> Signed-off-by: Junio C Hamano \n\nLooking good to me.\n\nReviewed-by: Dragan Simic \n\n> ---\n> * An experimental procedure for a topic author to propose the topic\n> description to be used in \"What's cooking\" report and in the\n> release notes have been added to the SubmittingPatches document.\n> \n> The above is an example that follows this protocol for a\n> single-patch series.\n> \n> >> Would it be beneficial to request some specific heading, phrase, \n> or\n> >> other structured text such that this summary is obvious, or even \n> easily\n> >> extracted with some sort of script? Or is that perhaps overkill \n> for now?\n> >\n> > ... the rule might end up\n> > to be as simple as \"When the first paragraph of the message looks\n> > like an entry in the Release Notes, it is used as such\".\n> \n> Range-diff:\n> 1: 83f8b69ab9 ! 1: 86b861255b SubmittingPatches: release-notes entry\n> experiment\n> ## Documentation/SubmittingPatches ##\n> @@ Documentation/SubmittingPatches: an explanation of changes\n> between each iteration can be kept in\n> @@ Documentation/SubmittingPatches: an explanation of changes\n> between each iteratio\n> +paragraph summary that appears in the \"What's cooking\" report \n> when it\n> +is picked up to explain the topic. If you choose to do so, \n> please\n> +write 2-5 lines of a paragraph that will fit well in our release \n> notes\n> -+(see Documentation/RelNotes/* directory for examples), and put it \n> in\n> -+the cover letter, clearly marked as such. For a single-patch \n> series,\n> ++(see Documentation/RelNotes/* directory for examples), and make \n> it\n> ++the first paragraph of the cover letter. For a single-patch \n> series,\n> +use the space between the three-dash line and the diffstat, as\n> +described earlier.\n> +\n> \n> Documentation/SubmittingPatches | 11 +++++++++++\n> 1 file changed, 11 insertions(+)\n> \n> diff --git a/Documentation/SubmittingPatches \n> b/Documentation/SubmittingPatches\n> index e734a3f0f1..e29a3d9a5b 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -459,6 +459,17 @@ an explanation of changes between each iteration\n> can be kept in\n> Git-notes and inserted automatically following the three-dash\n> line via `git format-patch --notes`.\n> \n> +[[a-paragraph-summary]]\n> +\n> +*This is EXPERIMENTAL*. When sending a topic, you can propose one\n> +paragraph summary that appears in the \"What's cooking\" report when it\n> +is picked up to explain the topic. If you choose to do so, please\n> +write 2-5 lines of a paragraph that will fit well in our release notes\n> +(see Documentation/RelNotes/* directory for examples), and make it\n> +the first paragraph of the cover letter. For a single-patch series,\n> +use the space between the three-dash line and the diffstat, as\n> +described earlier.\n> +\n> [[attachment]]\n> Do not attach the patch as a MIME attachment, compressed or not.\n> Do not let your e-mail client send quoted-printable. Do not let\n"},{"id":"491561","messageId":"da3a915b302c40dc8815d72d3e235a1f@manjaro.org","threadId":"61202","inReplyTo":"17c0263586f87125.70b1dd9aae081c6e.203dcd72f6563036@zivdesk","subject":"Re: [PATCH v2] SubmittingPatches: release-notes entry experiment","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-03-26T07:51:23Z","receivedAt":"2024-03-26T07:51:31Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-03-26 00:37, Brian Lyles wrote:\n\n> On Mon, Mar 25, 2024 at 5:21 PM Junio C Hamano \n> wrote:\n> \n>> +[[a-paragraph-summary]]\n>> +\n>> +*This is EXPERIMENTAL*. When sending a topic, you can propose one\n>> +paragraph summary that appears in the \"What's cooking\" report when it\n>> +is picked up to explain the topic. If you choose to do so, please\n>> +write 2-5 lines of a paragraph that will fit well in our release \n>> notes\n>> +(see Documentation/RelNotes/* directory for examples), and make it\n>> +the first paragraph of the cover letter. For a single-patch series,\n>> +use the space between the three-dash line and the diffstat, as\n>> +described earlier.\n>> +\n> \n> One very minor grammar note: \"you can propose *a* one paragraph\n> summary\".\n\nActually, it should read \"a one-paragraph summary\", to be precise. :)\n\n> Otherwise, this patch looks good to me. Thanks for considering this.\n"},{"id":"491578","messageId":"dda1ba52-7b43-4017-96e7-10080618d4e7@gmail.com","threadId":"61202","inReplyTo":"xmqq8r26eyva.fsf@gitster.g","subject":"Re: [PATCH v2] SubmittingPatches: release-notes entry experiment","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2024-03-26T14:18:10Z","receivedAt":"2024-03-26T14:18:13Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Junio\n\nOn 25/03/2024 22:21, Junio C Hamano wrote:\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index e734a3f0f1..e29a3d9a5b 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -459,6 +459,17 @@ an explanation of changes between each iteration can be kept in\n> Git-notes and inserted automatically following the three-dash\n> line via `git format-patch --notes`.\n> \n> +[[a-paragraph-summary]]\n> +\n> +*This is EXPERIMENTAL*. When sending a topic, you can propose one\n> +paragraph summary that appears in the \"What's cooking\" report when it\n> +is picked up to explain the topic. If you choose to do so, please\n> +write 2-5 lines of a paragraph that will fit well in our release notes\n\nMaybe \"please write a 2-5 line paragraph\"?\n\n> +(see Documentation/RelNotes/* directory for examples), and make it\n> +the first paragraph of the cover letter. For a single-patch series,\n> +use the space between the three-dash line and the diffstat, as\n> +described earlier.\n\nI think this is a good idea - one question though, how do you want patch \nauthors to indicate that the first paragraph should be used as the summary?\n\nBest Wishes\n\nPhillip\n"},{"id":"491584","messageId":"xmqq1q7xc5ys.fsf@gitster.g","threadId":"61202","inReplyTo":"dda1ba52-7b43-4017-96e7-10080618d4e7@gmail.com","subject":"Re: [PATCH v2] SubmittingPatches: release-notes entry experiment","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-03-26T16:28:59Z","receivedAt":"2024-03-26T16:29:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phillip Wood writes:\n\n>> +*This is EXPERIMENTAL*. When sending a topic, you can propose one\n>> +paragraph summary that appears in the \"What's cooking\" report when it\n>> +is picked up to explain the topic. If you choose to do so, please\n>> +write 2-5 lines of a paragraph that will fit well in our release notes\n>\n> Maybe \"please write a 2-5 line paragraph\"?\n\nVery true.\n\n>> +(see Documentation/RelNotes/* directory for examples), and make it\n>> +the first paragraph of the cover letter. For a single-patch series,\n>> +use the space between the three-dash line and the diffstat, as\n>> +described earlier.\n>\n> I think this is a good idea - one question though, how do you want\n> patch authors to indicate that the first paragraph should be used as\n> the summary?\n\nI want to start this as a light-weight process for contributors, and\nleave the automation for later, because we do not know how this will\nbe useful in practice. We may end up talking in inconsistent voices\nif the author-supplied summary is used verbatim, so automation has\nits limit---the result always need to be copy-edited.\n\nIn an case, taking an example from what eventually became 9187b276\n(Merge branch 'pw/diff-no-index-from-named-pipes', 2023-07-17),\nlet's illustrate how the current process works and the proposed new\nprocess would have worked.\n\nThe commit log message of the topic reads:\n\n Merge branch 'pw/diff-no-index-from-named-pipes'\n\n \"git diff --no-index\" learned to read from named pipes as if they\n were regular files, to allow \"git diff <(process) <(substitution)\"\n some shells support.\n\n * pw/diff-no-index-from-named-pipes:\n diff --no-index: support reading from named pipes\n t4054: test diff --no-index with stdin\n diff --no-index: die on error reading stdin\n diff --no-index: refuse to compare stdin to a directory\n\nThe three-line paragraph summary were written by me back then first\nin the draft of \"What's cooking\" being prepared when the topic was\nfirst merged to 'seen', and then the integration process [*1*]\ncopied the description to the merge commit message. Such a merge\ncommit with the summary are made every time the integration cycle\nruns, including the time the topic gets merged to 'next' and more\nimportantly to 'master', at which point, it also gets distributed\ninto sections of the draft version of RelNotes.\n\nThe topic is listed in the release notes for Git 2.42 as one of the\n\"UI, Workflows & Features\":\n\n * \"git diff --no-index\" learned to read from named pipes as if they\n were regular files, to allow \"git diff <(process) <(substitution)\"\n some shells support.\n\nIts cover letter \nstarted like so:\n\n In some shells, such as bash and zsh, it's possible to use a command\n substitution to provide the output of a command as a file argument to\n another process, like so:\n\n diff -u <(printf \"a\\nb\\n\") <(printf \"a\\nc\\n\")\n\n However, ...\n\nbut you could have started it like so:\n\n * \"git diff --no-index\" learned to read from named pipes as if they\n were regular files, to allow \"git diff <(process) <(substitution)\"\n some shells support.\n\n In some shells, such as bash and zsh, it's possible to use a command\n substitution to provide the output of a command as a file argument to\n another process, like so:\n ...\n\nand I suspect it would be sufficient to notice that the paragraph\nwants to be the topic description. We may even feed it to\nautomation if we decide to do so later [*2*]. Until then we\n\n - identify three-place indented first paragraph that is 2-5 lines\n long whose first line is indented with \" * \";\n\n - somehow use it when adding the topic to \"What's cooking\" draft;\n\nand then the integration process merges the topic to 'seen' and\nuses it in the merge commit log message. We *can* still copy-edit\nwhat I keep in the draft of \"What's cooking\" which I send to the\nlist about twice a week. When the topic eventually hits 'master',\nthe integration process would extract these merge log messages from\n\"git log --first-parent master\" output for the batch, and I rearrange\nthem into sections of RelNotes, while doing the final proofreading.\n\n\n[Footnotes]\n\n *1* The Reintegrate script and the other files from the 'todo'\n branch of my git repository are checked out in an untracked\n Meta subdirectory of my primary working area for Git\n development. It knows how to take topic descriptions from the\n draft of \"What's cooking\" (also checked out in Meta/) among\n other tricks.\n\n *2* Teaching \"am\" to do something useful with the cover letters is\n something I have been wanting to do for quite some time. Ideas\n other than the topic description we are disussing here include\n allowing the patch submitter to pick a branch name for the\n topic and creating an empty commit at the tip (not the bottom)\n of the topic branch that records the contents of the cover\n letter.\n"}]}