From 81f831ffb72a718d06852067b4c9769fb941cabb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Kowalczyk?= <mkow@invisiblethingslab.com>
Date: Sun, 10 Mar 2024 15:35:52 +0100
Subject: [PATCH 1/3] [Docs] Add more details to commit message styleguide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Signed-off-by: Michał Kowalczyk <mkow@invisiblethingslab.com>
---
CONTRIBUTING.rst | 6 ++++--
Documentation/devel/coding-style.rst | 32 ++++++++++++++++++++++++++++
2 files changed, 36 insertions(+), 2 deletions(-)
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 37232e0b15..d2b9175b8c 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
+ <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.
diff --git a/Documentation/devel/coding-style.rst b/Documentation/devel/coding-style.rst
index 0471bd1c94..3a9872222a 100644
--- a/Documentation/devel/coding-style.rst
+++ b/Documentation/devel/coding-style.rst
@@ -36,6 +36,38 @@ 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,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.
+
+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
-
From 5c773c9d11ab217b941fe6cf9512e750c1f19580 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Kowalczyk?= <mkow@invisiblethingslab.com>
Date: Mon, 11 Mar 2024 14:48:36 +0100
Subject: [PATCH 2/3] fixup! [Docs] Add more details to commit message
styleguide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Signed-off-by: Michał Kowalczyk <mkow@invisiblethingslab.com>
---
Documentation/devel/coding-style.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/devel/coding-style.rst b/Documentation/devel/coding-style.rst
index 3a9872222a..aac2c65f93 100644
--- a/Documentation/devel/coding-style.rst
+++ b/Documentation/devel/coding-style.rst
@@ -43,8 +43,8 @@ Commit message formatting
TL;DR: we follow https://commit.style/.
Additionally, commit message one-liner should include which component was
-changed (PAL-{Linux,SGX} / LibOS / Docs / CI) in the format
-"[component] change description". The one-liner should be
+changed (``PAL-{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
From 11a3972d24edcb91ba5fd3eba1cc2cfcf9415700 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Kowalczyk?= <mkow@invisiblethingslab.com>
Date: Wed, 20 Mar 2024 02:05:21 +0100
Subject: [PATCH 3/3] fixup! [Docs] Add more details to commit message
styleguide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Signed-off-by: Michał Kowalczyk <mkow@invisiblethingslab.com>
---
CONTRIBUTING.rst | 2 +-
Documentation/devel/coding-style.rst | 7 ++++---
2 files changed, 5 insertions(+), 4 deletions(-)
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index d2b9175b8c..cd1c3d9390 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -144,7 +144,7 @@ Reviewing Guidelines
the same time).
#. Meaningful commit messages (it's much easier to get them right if commits are
really atomic). Commit messages should follow `commit message style guidelines
- <coding-style.html#commit-message-formatting>`__.
+ <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.
diff --git a/Documentation/devel/coding-style.rst b/Documentation/devel/coding-style.rst
index aac2c65f93..0c07dea9f6 100644
--- a/Documentation/devel/coding-style.rst
+++ b/Documentation/devel/coding-style.rst
@@ -43,8 +43,8 @@ Commit message formatting
TL;DR: we follow https://commit.style/.
Additionally, commit message one-liner should include which component was
-changed (``PAL-{Linux,SGX}`` / ``LibOS`` / ``Docs`` / ``CI``) in the format
-"[component] Change description". The one-liner should be
+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
@@ -52,7 +52,8 @@ 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.
+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