blacklight/aerc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

contributing: refine commit message rules

Browse source 
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>
This commit is contained in:
Robin Jarry 2022-08-22 14:36:36 +02:00
parent cd72812781
commit 3ba8a3b750
1 changed files with 24 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
CONTRIBUTING.md
View file

@ -13,8 +13,8 @@ the project:
$ make $ make
Patch the code. Write some tests. Ensure that your code is properly formatted 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 with `gofumpt`. Ensure that everything builds and works as expected. Ensure
you did not break anything. that you did not break anything.
- If applicable, update unit tests. - If applicable, update unit tests.
- If adding a new feature, please consider adding new 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: commits). Follow these general rules:
- Limit the first line (title) of the commit message to 60 characters. - 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 - 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. - 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 - If you are fixing a ticket, use appropriate
[commit trailers](https://man.sr.ht/git.sr.ht/#referencing-tickets-in-git-commit-messages). [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:` - If you are fixing a regression introduced by another commit, add a `Fixes:`
trailer with the commit id and its title. 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 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). [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 expected but did not conduct a proper code review, you can indicate it with
a Tested-by trailer. a Tested-by trailer.
You can follow the review process via email and on the You can follow the review process via email and on the [web ui][web-ui].
[web ui](https://lists.sr.ht/~rjarry/aerc-devel/patches).
Wait for feedback. Address comments and amend changes to your original commit. Wait for feedback. Address comments and amend changes to your original commit.
Then you should send a v2 (and maybe a v3, v4, etc.): 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 Once your patch has been reviewed and approved (and if the maintainer is OK
with it), it will be applied and pushed. 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 ## Code Style
Please refer only to the quoted sections when guidelines are sourced from 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 outside documents as some rules of the source material may conflict with other
rules set out in this document. 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
Indentation rules follow the Linux kernel coding style: Indentation rules follow the Linux kernel coding style: