Skip to content

Commit 8043dd7

Browse files
committed
SubmittingPatches: clarify the writing style of whats-cooking
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 <gitster@pobox.com>
1 parent 33d136c commit 8043dd7

1 file changed

Lines changed: 18 additions & 9 deletions

File tree

Documentation/SubmittingPatches

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -723,17 +723,26 @@ line via `git format-patch --notes`.
723723

724724
When sending a topic, you can optionally propose a topic name and/or a
725725
one-paragraph summary that should appear in the "What's cooking"
726-
report when it is picked up to explain the topic. If you choose to do
727-
so, please write a 2-5 line paragraph that will fit well in our
728-
release notes (see many bulleted entries in the
726+
report when it is picked up to explain the topic.
727+
728+
If you choose to do so, please write a 2-5 line paragraph that will
729+
fit well in our release notes (see many bulleted entries in the
729730
Documentation/RelNotes/* files for examples), and make it the first
730731
(or second, if including a suggested topic name) paragraph of the
731-
cover letter. If suggesting a topic name, use the format
732-
"XX/your-topic-name", where "XX" is a stand-in for the primary
733-
author's initials, and "your-topic-name" is a brief, dash-delimited
734-
description of what your topic does. For a single-patch series, use
735-
the space between the three-dash line and the diffstat, as described
736-
earlier.
732+
cover letter.
733+
734+
If suggesting a topic name, use the format "XX/your-topic-name", where
735+
"XX" is a stand-in for the primary author's initials, and
736+
"your-topic-name" is a brief, dash-delimited description of what your
737+
topic does. For a single-patch series, use the space between the
738+
three-dash line and the diffstat, as described earlier.
739+
740+
TIP: When proposing a topic summary in your cover letter, write it in
741+
the reporting style (passive voice, past or present perfect tense
742+
describing the change as completed, e.g., "The XYZ subsystem has
743+
been updated to...") rather than the imperative mood, like you do
744+
in the proposed commit log messages. This matches the format
745+
used in the "What's cooking" report and release notes.
737746

738747
[[multi-series-efforts]]
739748
If your patch series is part of a larger effort spanning multiple

0 commit comments

Comments
 (0)