"Brian Lyles" <brianmlyles@xxxxxxxxx> writes: > Yes, I suspect you are right. I think the cover letter would be a good > start at the very least. Would you welcome a patch to > 'Documentation/SubmittingPatches' that adds a new expectation for this, > or do you think this would be best handled yourself? I am interested in > contributing but, as I'm sure you've noticed, I'm also quite new to the > project =) I'd prefer to start with a much less official "experimental" launch of such a new workflow, instead of adding an unproven idea as if it is a new hard requirement to the SubmittingPatches document. If it works well, we can write it down later. But even a soft launch needs some way to advertise it to the target audience, and the SubmittingPatches document is the only sensible place to do so. So, perhaps do something like this? I dunno. ------- >8 ------------- >8 ------------- >8 ------- Subject: SubmittingPatches: release-notes entry experiment It has been the maintainer's task to prepare the description of each topic listed in the "What's cooking" report. The description is automatically picked up from the "What's cooking" report and used in the commit log message of the merge commit when the topic is merged into integration branches. These commit log messges of the merge commits are then propagated to the release notes. The original author of a topic may be in the best position to write the initial description of a topic, but we so far lacked a formal channel for the author to tell what description to use. The usual procedure has been to see the topic described in "What's cooking" report, and then either complain about inaccurate explanation and/or offer a rewrite. Let's try an experiment to optionally let the author propose the one paragraph description when the topic is submitted. Pick the cover letter as the logical place to do so, and describe an experimental workflow in the SubmittingPatches document. Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> --- [for what's cooking] * An experimental procedure for a topic author to propose the topic description to be used in "What's cooking" report and in the release notes have been added to the SubmittingPatches document. Documentation/SubmittingPatches | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git i/Documentation/SubmittingPatches w/Documentation/SubmittingPatches index e734a3f0f1..05e15b9436 100644 --- i/Documentation/SubmittingPatches +++ w/Documentation/SubmittingPatches @@ -459,6 +459,17 @@ an explanation of changes between each iteration can be kept in Git-notes and inserted automatically following the three-dash line via `git format-patch --notes`. +[[a-paragraph-summary]] + +*This is EXPERIMENTAL*. When sending a topic, you can propose one +paragraph summary that appears in the "What's cooking" report when it +is picked up to explain the topic. If you choose to do so, please +write 2-5 lines of a paragraph that will fit well in our release notes +(see Documentation/RelNotes/* directory for examples), and put it in +the cover letter, clearly marked as such. 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. Do not let your e-mail client send quoted-printable. Do not let
