Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitaly.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Couder <chriscool@tuxfamily.org>2021-09-16 11:56:18 +0300
committerChristian Couder <chriscool@tuxfamily.org>2021-10-27 10:39:40 +0300
commite30eeef29c68370daf4ba9380511e75f223faede (patch)
tree24f44d9570b8f5c82e8b1db24e4812bd9967705f
parentba8bc12dd0ff83fc726c6c09ee0cb0ebc311a748 (diff)
STYLE: Recommend using direct and imperative wordingimperative-mood
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.
-rw-r--r--STYLE.md18
1 files changed, 18 insertions, 0 deletions
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