summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorCraig Scott <craig.scott@crascit.com>2017-08-05 10:55:49 (GMT)
committerCraig Scott <craig.scott@crascit.com>2017-08-08 11:17:32 (GMT)
commit11d00a17aafb33385a57a11b53862ac2197f116f (patch)
treeae47b775193642aceffef4cb522d71b3e4b49134
parent7c7a57ce9e14bf2eff1eb1de06e17a8216af1e18 (diff)
downloadCMake-11d00a17aafb33385a57a11b53862ac2197f116f.zip
CMake-11d00a17aafb33385a57a11b53862ac2197f116f.tar.gz
CMake-11d00a17aafb33385a57a11b53862ac2197f116f.tar.bz2
Help/dev: Add commit message guidelines
-rw-r--r--CONTRIBUTING.rst4
-rw-r--r--Help/dev/review.rst48
2 files changed, 51 insertions, 1 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 3c84c2b..381769d 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -29,7 +29,8 @@ To contribute patches:
#. Base all new work on the upstream ``master`` branch.
Base work on the upstream ``release`` branch only if it fixes a
regression or bug in a feature new to that release.
-#. Create commits making incremental, distinct, logically complete changes.
+#. Create commits making incremental, distinct, logically complete changes
+ with appropriate `commit messages`_.
#. Push a topic branch to a personal repository fork on GitLab.
#. Create a GitLab Merge Request targeting the upstream ``master`` branch
(even if the change is intended for merge to the ``release`` branch).
@@ -40,6 +41,7 @@ The merge request will enter the `CMake Review Process`_ for consideration.
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
.. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh
.. _`CMake Source Code Guide`: Help/dev/source.rst
+.. _`commit messages`: Help/dev/review.rst#commit-messages
.. _`CMake Review Process`: Help/dev/review.rst
License
diff --git a/Help/dev/review.rst b/Help/dev/review.rst
index 9450bf0..985b1b7 100644
--- a/Help/dev/review.rst
+++ b/Help/dev/review.rst
@@ -185,6 +185,54 @@ commands to ``@kwrobot`` using the form ``Do: ...``:
See the corresponding sections for details on permissions and options
for each command.
+Commit Messages
+---------------
+
+Part of the human review is to check that each commit message is appropriate.
+The first line of the message should begin with one or two words indicating the
+area the commit applies to, followed by a colon and then a brief summary.
+Committers should aim to keep this first line short. Any subsequent lines
+should be separated from the first by a blank line and provide relevant, useful
+information.
+
+The appropriateness of the initial word describing the area the commit applies
+to is not something the automatic robot review can judge, so it is up to the
+human reviewer to confirm that the area is specified and that it is
+appropriate. Good area words include the module name the commit is primarily
+fixing, the main C++ source file being edited, ``Help`` for generic
+documentation changes or a feature or functionality theme the changes apply to
+(e.g. ``server`` or ``Autogen``). Examples of suitable first lines of a commit
+message include:
+
+* ``Help: Fix example in cmake-buildsystem(7) manual``
+* ``FindBoost: Add support for 1.64``
+* ``Autogen: Extended mocInclude tests``
+* ``cmLocalGenerator: Explain standard flag selection logic in comments``
+
+If the commit fixes a particular reported issue, this information should
+ideally also be part of the commit message. The recommended way to do this is
+to place a line at the end of the message in the form ``Fixes: #xxxxx`` where
+``xxxxx`` is the GitLab issue number and to separate it from the rest of the
+text by a blank line. For example::
+
+ Help: Fix FooBar example robustness issue
+
+ FooBar supports option X, but the example provided
+ would not work if Y was also specified.
+
+ Fixes: #12345
+
+GitLab will automatically create relevant links to the merge request and will
+close the issue when the commit is merged into master. GitLab understands a few
+other synonyms for ``Fixes`` and allows much more flexible forms than the
+above, but committers should aim for this format for consistency. Note that
+such details can alternatively be specified in the merge request description.
+
+Reviewers are encouraged to ask the committer to amend commit messages to
+follow these guidelines, but prefer to focus on the changes themselves as a
+first priority. Maintainers will also make a check of commit messages before
+merging.
+
Topic Testing
=============