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

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

[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.

Signed-off-by: Josh Triplett <josh@joshtriplett.org>
---
 Documentation/SubmittingPatches | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 26b1e31..c74e73c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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.
 
-- 
1.8.5.1

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

[Borislav Petkov]

On Sun, Dec 15, 2013 at 12:59:26PM -0800, Josh Triplett wrote:
> 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.
> 
> Signed-off-by: Josh Triplett <josh@joshtriplett.org>

Acked-by: Borislav Petkov <bp@suse.de>

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.

-- 
Regards/Gruss,
    Boris.

Sent from a fat crate under my desk. Formatting is fine.
--

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

[Josh Triplett]

On Sun, Dec 15, 2013 at 10:14:29PM +0100, Borislav Petkov wrote:
> On Sun, Dec 15, 2013 at 12:59:26PM -0800, Josh Triplett wrote:
> > 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.
> > 
> > Signed-off-by: Josh Triplett <josh@joshtriplett.org>
> 
> Acked-by: Borislav Petkov <bp@suse.de>
> 
> 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.

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