contributing: refine commit message rules

There were a few hiccups recently. Make sure that there are no
ambiguities.

Signed-off-by: Robin Jarry <robin@jarry.cc>
Acked-by: Tim Culverhouse <tim@timculverhouse.com>

1 files changed, 24 insertions, 6 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 167cb667..a291ee3d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,8 +13,8 @@ the project:
     $ make
 
 Patch the code. Write some tests. Ensure that your code is properly formatted
-with gofumpt. Ensure that everything builds and works as expected. Ensure that
-you did not break anything.
+with `gofumpt`. Ensure that everything builds and works as expected. Ensure
+that you did not break anything.
 
 - If applicable, update unit tests.
 - If adding a new feature, please consider adding new tests.
@@ -32,14 +32,24 @@ Once you are happy with your work, you can create a commit (or several
 commits). Follow these general rules:
 
 - Limit the first line (title) of the commit message to 60 characters.
-- Use a short prefix for the commit title for readability with `git log --oneline`.
+- Use a short prefix for the commit title for readability with `git log
+  --oneline`. Do not use the `fix:` nor `feature:` prefixes. See recent commits
+  for inspiration.
+- Only use lower case letters for the commit title except when quoting symbols
+  or known acronyms.
 - Use the body of the commit message to actually explain what your patch does
-  and why it is useful.
+  and why it is useful. Even if your patch is a one line fix, the description
+  is not limited in length and may span over multiple paragraphs. Use proper
+  English syntax, grammar and punctuation.
 - Address only one issue/topic per commit.
+- 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 you are fixing a ticket, use appropriate
   [commit trailers](https://man.sr.ht/git.sr.ht/#referencing-tickets-in-git-commit-messages).
 - If you are fixing a regression introduced by another commit, add a `Fixes:`
   trailer with the commit id and its title.
+- When in doubt, follow the format and layout of the recent existing commits.
 
 There is a great reference for commit messages in the
 [Linux kernel documentation](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes).
@@ -76,8 +86,7 @@ Acked-by or Reviewed-by trailer. If you only tested that a patch works as
 expected but did not conduct a proper code review, you can indicate it with
 a Tested-by trailer.
 
-You can follow the review process via email and on the
-[web ui](https://lists.sr.ht/~rjarry/aerc-devel/patches).
+You can follow the review process via email and on the [web ui][web-ui].
 
 Wait for feedback. Address comments and amend changes to your original commit.
 Then you should send a v2 (and maybe a v3, v4, etc.):
@@ -90,12 +99,21 @@ with something, feel free to discuss it.
 Once your patch has been reviewed and approved (and if the maintainer is OK
 with it), it will be applied and pushed.
 
+IMPORTANT: Do NOT use `--in-reply-to` when sending followup versions of a patch
+set. It causes multiple versions of the same patch to be merged under v1 in the
+[web ui][web-ui]
+
+[web-ui]: https://lists.sr.ht/~rjarry/aerc-devel/patches
+
 ## Code Style
 
 Please refer only to the quoted sections when guidelines are sourced from
 outside documents as some rules of the source material may conflict with other
 rules set out in this document.
 
+When updating an existing file, respect the existing coding style unless there
+is a good reason not to do so.
+
 ### Indentation
 
 Indentation rules follow the Linux kernel coding style: