From a15f2c04268f9caeb0abf90adc1676cc414b1345 Mon Sep 17 00:00:00 2001 From: Bence Ferdinandy Date: Mon, 30 Jan 2023 22:55:12 +0100 Subject: [PATCH] contrib: make commit formatting rules clearer --- CONTRIBUTING.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73ee023..e3808ab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,24 +28,26 @@ PR without a merge commit. This means that Please follow these general rules (adopted somewhat from the aerc contribution guidelines): -- 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`. Do not use the `fix:` nor `feature:` prefixes. See recent commits - for inspiration. +- Limit the first line (title) of the commit message to 60 characters. Leave an +- empty space between the title and the body of the commit. 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. 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"* + English syntax, grammar and punctuation. Make sure the body of the commit is + hard wrapped at 72 characters. +- 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 an issue, add a `Fixes: #xxx` trailer with the issue id. - 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 (well, at least the later ones :)). +- When in doubt, follow the format and layout of the recent existing commits +- (well, at least the later ones :)). 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) and on [tpope's blog](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).