SubmittingPatches: Add style recommendation to use imperative descriptions
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
@@ -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
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.
Signed-off-by Josh Triplett <[email protected]>
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.
--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.
Signed-off-by Josh Triplett <[email protected]>Acked-by Borislav Petkov <[email protected]>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