Thread (18 messages) 18 messages, 5 authors, 22h ago
HOTtoday

[PATCH 6/6] SubmittingPatches: clarify the writing style of whats-cooking

From: Junio C Hamano <hidden>
Date: 2026-07-11 19:27:01
Subsystem: documentation, the rest · Maintainers: Jonathan Corbet, Linus Torvalds

Unlike commit log messages, that use present tense to make
observations of the current code, and imperative mood to describe
what changes the commit makes, entries in the whats-cooking report
are written mostly in past or present perfect tense to report what
has been done.

Spell it out for contributors.

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/SubmittingPatches | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 0a80358703..8917cc3805 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -714,17 +714,26 @@ line via `git format-patch --notes`.
 
 When sending a topic, you can optionally propose a topic name and/or a
 one-paragraph summary that should appear in the "What's cooking"
-report when it is picked up to explain the topic.  If you choose to do
-so, please write a 2-5 line paragraph that will fit well in our
-release notes (see many bulleted entries in the
+report when it is picked up to explain the topic.
+
+If you choose to do so, please write a 2-5 line paragraph that will
+fit well in our release notes (see many bulleted entries in the
 Documentation/RelNotes/* files for examples), and make it the first
 (or second, if including a suggested topic name) paragraph of the
-cover letter.  If suggesting a topic name, use the format
-"XX/your-topic-name", where "XX" is a stand-in for the primary
-author's initials, and "your-topic-name" is a brief, dash-delimited
-description of what your topic does.  For a single-patch series, use
-the space between the three-dash line and the diffstat, as described
-earlier.
+cover letter.
+
+If suggesting a topic name, use the format "XX/your-topic-name", where
+"XX" is a stand-in for the primary author's initials, and
+"your-topic-name" is a brief, dash-delimited description of what your
+topic does.  For a single-patch series, use the space between the
+three-dash line and the diffstat, as described earlier.
+
+TIP: When proposing a topic summary in your cover letter, write it in
+the reporting style (passive voice, past or present perfect tense
+describing the change as completed, e.g., "The XYZ subsystem has
+been updated to...") rather than the imperative mood, like you do
+in the proposed commit log messages.  This matches the format
+used in the "What's cooking" report and release notes.
 
 [[multi-series-efforts]]
 If your patch series is part of a larger effort spanning multiple
-- 
2.55.0-391-gdf86bf5712
Keyboard shortcuts
hback out one level
jnext message in thread
kprevious message in thread
ldrill in
Escclose help / fold thread tree
?toggle this help