From e30eeef29c68370daf4ba9380511e75f223faede Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Thu, 16 Sep 2021 10:56:18 +0200 Subject: STYLE: Recommend using direct and imperative wording In the same way as it is recommended for Git development in the `imperative-mood` section of their `Documentation/SubmittingPatches.txt` guidelines, we should recommend using the imperative mood or at least direct style in commit message subjects. While at it, let's recommand a direct and 'get to the point' style in the whole message. --- STYLE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/STYLE.md b/STYLE.md index e663c397a..6a3a52bbf 100644 --- a/STYLE.md +++ b/STYLE.md @@ -466,6 +466,24 @@ you're implementing a new feature "X" for subsystem "Y", your commit message would be "Y: Implement new feature X". This makes it easier to quickly sift through relevant commits by simply inspecting this prefix. +### Use more direct and imperative wording + +Prefer less verbose and more direct wording to unambiguously describe +the same ideas. + +In the commit subjects, preferring the imperative mood can help with +generally summarizing the patch and understanding its intent. + +The same goes for summarizing data in the form of bullet points or a +formatted table in the commit message body, instead of in relatively +verbose prose. Get to the point. + +For example about using the imperative mood, use +`Y: Implement new feature X` instead of +`Y: [This patch] implements new feature X` or +`Y: [I] implemented new feature X`, as if +you are giving orders to the codebase to change its behavior. + ### Keep the commit subject short As commit subjects are displayed in various command line tools by default, it is -- cgit v1.2.3