Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Add more details to commit message styleguide #1805

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
<https://gramine.readthedocs.io/en/latest/devel/coding-style.html#commit-message-formatting>`__.
#. 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.
Expand Down
33 changes: 33 additions & 0 deletions Documentation/devel/coding-style.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <email>


C
-

Expand Down