Skip to contentSkip to conversation

SubmittingPatches: Add style recommendation to use imperative descriptions

PATCH Superseded Josh Triplett 2 participants 3 messages Dec 15, 2013 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/3 SubmittingPatches: Add style recommendation to use imperative descriptions

Most commit messages use this style, and the recommendation frequently comes up in discussions (especially in response to patches that don't use it), but that recommendation doesn't actually appear anywhere in Documentation. Add this style guideline to SubmittingPatches, using the description from git's SubmittingPatches.

---
 Documentation/SubmittingPatches | 5 +++++
 1 file changed, 5 insertions(+)
Documentation/SubmittingPatches +5 -0
index 26b1e31..c74e73c 100644
@@ -106,6 +106,11 @@ I.e., the patch (series) and its description should be self-contained.
 This benefits both the patch merger(s) and reviewers.  Some reviewers
 probably didn't even receive earlier versions of the patch.
 
+Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
+instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
+to do frotz", as if you are giving orders to the codebase to change
+its behaviour.
+
 If the patch fixes a logged bug entry, refer to that bug entry by
 number and URL.
 
Signature · 1 line
1.8.5.1
Acked-by on v1 1/3
#1 lore raw
Quoted 7 lines · Josh Triplett

Most commit messages use this style, and the recommendation frequently comes up in discussions (especially in response to patches that don't use it), but that recommendation doesn't actually appear anywhere in Documentation. Add this style guideline to SubmittingPatches, using the description from git's SubmittingPatches.

We should probably also document the wished-for structure of a commit message:

The current situation is A. The shortcoming is B. Change/fix it by doing C.

This helps very much in explaining to the unenlightened onlooker what a patch is trying to fix without having to ask the author a bunch of questions first.

Signature · 5 lines
Regards/Gruss,
    Boris.

Sent from a fat crate under my desk. Formatting is fine.
--
#2 lore raw
Quoted 14 lines · Borislav Petkov
Quoted 7 lines · Josh Triplett

Most commit messages use this style, and the recommendation frequently comes up in discussions (especially in response to patches that don't use it), but that recommendation doesn't actually appear anywhere in Documentation. Add this style guideline to SubmittingPatches, using the description from git's SubmittingPatches.

We should probably also document the wished-for structure of a commit message:

Quoted 6 lines

The current situation is A. The shortcoming is B. Change/fix it by doing C.

This helps very much in explaining to the unenlightened onlooker what a patch is trying to fix without having to ask the author a bunch of questions first.

git's SubmittingPatches has some bits that could help there. I wouldn't recommend writing the structure quite so rigidly (A and B aren't always needed, depending on the nature of the problem and the fix), but some guidance would help.

- Josh Triplett