doc: contribute: improve "Commit Guidelines" section
The current content does have all the critical information, but you
have to read carefully to catch several important details. This makes
it less likely that people will be able to follow the rules, which
wastes maintainers' time in PRs from new contributors, since we have
to explain the details repeatedly.
Fix it by making the introduction shorter while still covering all the
bases, and adding details with more concrete examples in the following
subsections.
Keep some other text in the document up to date and fix some
cross-references as needed.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
diff --git a/doc/contribute/guidelines.rst b/doc/contribute/guidelines.rst
index 6d554c4..32f66bb 100644
--- a/doc/contribute/guidelines.rst
+++ b/doc/contribute/guidelines.rst
@@ -335,17 +335,23 @@
Tools and Git Setup
*******************
-Signed-off-by
-=============
+.. _git-name-and-email:
-The name in the commit message ``Signed-off-by:`` line and your email must
-match the change authorship information. Make sure your :file:`.gitconfig`
-is set up correctly:
+Name and email
+==============
+
+We need to know who you are, and how to contact you. To add this
+information to your Git installation, set the Git configuration
+variables ``user.name`` to your full name, and ``user.email`` to your
+email address.
+
+For example, if your name is ``Zephyr Developer`` and your email
+address is ``z.developer@example.com``:
.. code-block:: console
- git config --global user.name "David Developer"
- git config --global user.email "david.developer@company.com"
+ git config --global user.name "Zephyr Developer"
+ git config --global user.email "z.developer@example.com"
gitlint
=========
@@ -580,7 +586,7 @@
The ``-s`` option automatically adds your ``Signed-off-by:`` to your commit
message. Your commit will be rejected without this line that indicates your
- agreement with the `DCO`_. See the `Commit Guidelines`_ section for
+ agreement with the :ref:`DCO`. See the :ref:`commit-guidelines` section for
specific guidelines for writing your commit messages.
#. Push your topic branch with your changes to your fork in your personal
@@ -663,53 +669,146 @@
Additional information about the CI system can be found in
`Continuous Integration`_.
+.. _commit-guidelines:
-Commit Guidelines
-*****************
+Commit Message Guidelines
+*************************
-Changes are submitted as Git commits. Each commit message must contain:
+Changes are submitted as Git commits. Each commit has a *commit
+message* describing the change. Acceptable commit messages look like
+this:
-* A short and descriptive subject line that is less than 72 characters,
- followed by a blank line. The subject line must include a prefix that
- identifies the subsystem being changed, followed by a colon, and a short
- title, for example: ``doc: update wiki references to new site``.
- (If you're updating an existing file, you can use
- ``git log <filename>`` to see what developers used as the prefix for
- previous patches of this file.)
+.. code-block:: none
-* A change description with your logic or reasoning for the changes, followed
- by a blank line. (Every single line has to be less than 75 characters.)
+ [area]: [summary of change]
-* A Signed-off-by line, ``Signed-off-by: <name> <email>`` typically added
- automatically by using ``git commit -s``
+ [Commit message body (must be non-empty)]
-* If the change addresses an issue, include a line of the form::
+ Signed-off-by: [Your Full Name] <[your.email@address]>
- Fixes #<issue number>.
+You need to change text in square brackets (``[like this]``) above to
+fit your commit.
+Examples and more details follow.
-All changes and topics sent to GitHub must be well-formed, as described above.
+Example
+=======
+
+Here is an example of a good commit message.
+
+.. code-block:: none
+
+ drivers: sensor: abcd1234: fix bus I/O error handling
+
+ The abcd1234 sensor driver is failing to check the flags field in
+ the response packet from the device which signals that an error
+ occurred. This can lead to reading invalid data from the response
+ buffer. Fix it by checking the flag and adding an error path.
+
+ Signed-off-by: Zephyr Developer <z.developer@example.com>
+
+[area]: [summary of change]
+===========================
+
+This line is called the commit's *title*. Titles must be:
+
+* one line
+* less than 72 characters long
+* followed by a completely blank line
+
+[area]
+ The ``[area]`` prefix usually identifies the area of code
+ being changed. It can also identify the change's wider
+ context if multiple areas are affected.
+
+ Here are some examples:
+
+ * ``doc: ...`` for documentation changes
+ * ``drivers: foo:`` for ``foo`` driver changes
+ * ``Bluetooth: Shell:`` for changes to the Bluetooth shell
+ * ``net: ethernet:`` for Ethernet-related networking changes
+ * ``dts:`` for treewide devicetree changes
+ * ``style:`` for code style changes
+
+ If you're not sure what to use, try running ``git log FILE``, where
+ ``FILE`` is a file you are changing, and using previous commits that
+ changed the same file as inspiration.
+
+[summary of change]
+ The ``[summary of change]`` part should be a quick description of
+ what you've done. Here are some examples:
+
+ * ``doc: update wiki references to new site``
+ * ``drivers: sensor: sensor_shell: fix channel name collision``
Commit Message Body
===================
-When editing the commit message, please briefly explain what your change
-does and why it's needed. A change summary of ``"Fixes stuff"`` will be rejected.
-
.. warning::
- An empty change summary body is not permitted. Even for trivial changes, please
- include a summary body in the commit message.
-The description body of the commit message must include:
+ An empty commit message body is not permitted. Even for trivial
+ changes, please include a descriptive commit message body. Your
+ pull request will fail CI checks if you do not.
+
+This part of the commit should explain what your change does, and why
+it's needed. Be specific. A body that says ``"Fixes stuff"`` will be
+rejected. Be sure to include the following as relevant:
* **what** the change does,
* **why** you chose that approach,
* **what** assumptions were made, and
* **how** you know it works -- for example, which tests you ran.
+Each line in your commit message should usually be 75 characters or
+less. Use newlines to wrap longer lines. Exceptions include lines
+with long URLs, email addresses, etc.
+
For examples of accepted commit messages, you can refer to the Zephyr GitHub
`changelog <https://github.com/zephyrproject-rtos/zephyr/commits/main>`__.
+If the change addresses a GitHub issue, include a line of the form:
+
+.. code-block:: none
+
+ Fixes #[issue number]
+
+Where ``[issue number]`` is the relevant GitHub issue's number. For
+example:
+
+.. code-block:: none
+
+ Fixes: #1234
+
+Signed-off-by: ...
+==================
+
+.. tip::
+
+ You should have set your :ref:`git-name-and-email`
+ already. Create your commit with ``git commit -s`` to add the
+ Signed-off-by: line automatically using this information.
+
+For open source licensing reasons, your commit must include a
+Signed-off-by: line that looks like this:
+
+.. code-block:: none
+
+ Signed-off-by: [Your Full Name] <[your.email@address]>
+
+For example, if your full name is ``Zephyr Developer`` and your email
+address is ``z.developer@example.com``:
+
+.. code-block:: none
+
+ Signed-off-by: Zephyr Developer <z.developer@example.com>
+
+This means that you have personally made sure your change complies
+with the :ref:`DCO`. For this reason, you must use your legal name.
+Pseudonyms or "hacker aliases" are not permitted.
+
+Your name and the email address you use must match the name and email
+in the Git commit's ``Author:`` field.
+
Other Commit Expectations
=========================
