diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 37232e0b15..cd1c3d9390 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -72,6 +72,8 @@ In general, a |nbsp| PR should: #. Address a single problem. #. Clearly explain the problem and solution in the PR and commit messages, using grammatically correct American English. +#. Usually it should contain only a single commit. Multiple commits are allowed + only if they are tightly coupled and should be reviewed and merged together. #. Include unit tests for the new behavior or bugfix, except in special circumstances, namely: when designing a unit test is difficult (e.g., the code is deep enough in Gramine that it would require extra hooks for @@ -141,8 +143,8 @@ Reviewing Guidelines formatting fixes mixed with features, no moving files and changing them at the same time). #. Meaningful commit messages (it's much easier to get them right if commits are - really atomic). Should include which component was changed (PAL-{Linux,SGX} - / LibOS / Docs / CI) in the format "[component] change description". + really atomic). Commit messages should follow `commit message style guidelines + `__. #. Every PR description should include: what's the purpose of the changes, what is changed (and how, in case of redesigning a component), and how to test the changes. diff --git a/Documentation/devel/coding-style.rst b/Documentation/devel/coding-style.rst index 0471bd1c94..0c07dea9f6 100644 --- a/Documentation/devel/coding-style.rst +++ b/Documentation/devel/coding-style.rst @@ -36,6 +36,39 @@ add`). helper tool. Adding it to git pre-commit hooks is definitely a |~| bad idea, at least currently. + +Commit message formatting +------------------------- + +TL;DR: we follow https://commit.style/. + +Additionally, commit message one-liner should include which component was +changed (``PAL/{Linux,Linux-SGX}`` / ``LibOS`` / ``Docs`` / ``CI``) in the +format "[component] Change description". The one-liner should be +written in imperative mood and say what this particular commit changes. + +We aim for our repository and commit history to be self-contained and still +usable even without GitHub (e.g. in case we migrate to a different provider). +Thus, please restrain from descriptions like "Fixes #1234" and instead describe +the fix in the commit message. If you really need to reference something on our +GitHub, then use the full URL instead of #1234, so that it won't break if we +move to a different repository. If you want to reference a specific commit, +please quote its one-liner message and optionally its hash. + +Please never write descriptions like "file.c doesn't flush buffers on exit" - +it's not clear whether it's what the commit does, or whether it's the problem it +fixes. Instead it should look like: + +.. code-block:: text + + [LibOS] Flush buffers on exit in file.c + + Previously, there was a bug in file.c which left some buffers without + flushing on exit, which caused problems with ASDF. + + Signed-off-by: Name Surname + + C -