3 files changed, 205 insertions, 9 deletions
diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst
index 78c06df..bdfb3d0 100644
--- a/Help/dev/maint.rst
+++ b/Help/dev/maint.rst
@@ -8,6 +8,80 @@ See documentation on `CMake Development`_ for more information.
 
 .. contents:: Maintainer Processes:
 
+Review a Merge Request
+======================
+
+The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge``
+command to integrate a merge request.  Please check at least the following:
+
+* If the MR source branch is not named well for the change it makes
+  (e.g. it is just ``master`` or the patch changed during review),
+  add a ``Topic-rename: <topic>`` trailing line to the MR description
+  to provide a better topic name.
+
+* If the MR introduces a new feature or a user-facing behavior change,
+  such as a policy, ensure that a ``Help/release/dev/$topic.rst`` file
+  is added with a release note.
+
+* If a commit changes a specific area, such as a module, its commit
+  message should have an ``area:`` prefix on its first line.
+
+* If a commit fixes a tracked issue, its commit message should have
+  a trailing line such as ``Fixes: #00000``.
+
+* Ensure that the MR adds sufficient documentation and test cases.
+
+* Ensure that the MR has been tested sufficiently.  Typically it should
+  be staged for nightly testing with ``Do: stage``.  Then manually
+  review the `CMake CDash Page`_ to verify that no regressions were
+  introduced.  (Learn to tolerate spurious failures due to idiosyncrasies
+  of various nightly builders.)
+
+* Ensure that the MR targets the ``master`` branch.  A MR intended for
+  the ``release`` branch should be based on ``release`` but still merged
+  to ``master`` first (via ``Do: merge``).  A maintainer may then merge
+  the MR topic to ``release`` manually.
+
+Maintain Current Release
+========================
+
+The ``release`` branch is used to maintain the current release or release
+candidate.  The branch is published with no version number but maintained
+using a local branch named ``release-$ver``, where ``$ver`` is the version
+number of the current release in the form ``$major.$minor``.  It is always
+merged into ``master`` before publishing.
+
+To merge some ``$topic`` branch into ``release``, first create the local
+branch:
+
+.. code-block:: shell
+
+  git fetch origin
+  git checkout -b release-$ver origin/release
+
+Merge the ``$topic`` branch into the local ``release-$ver`` branch:
+
+.. code-block:: shell
+
+  git merge --no-ff $topic
+
+Merge the ``release-$ver`` branch to ``master``:
+
+.. code-block:: shell
+
+  git checkout master
+  git pull
+  git merge --no-ff release-$ver
+
+Publish both ``master`` and ``release`` simultaneously:
+
+.. code-block:: shell
+
+  git push --atomic origin master release-$ver:release
+
+.. _`CMake Review Process`: review.rst
+.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
+
 Branch a New Release
 ====================
 
diff --git a/Help/dev/review.rst b/Help/dev/review.rst
index 9450bf0..be02a1a 100644
--- a/Help/dev/review.rst
+++ b/Help/dev/review.rst
@@ -185,6 +185,83 @@ 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.
+
+Area Prefix on Commit Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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``
+
+Referencing Issues in Commit Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+Referencing Commits in Commit Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The preferred form for references to other commits is
+``commit <commit> (<subject>, <date>)``, where:
+
+* ``<commit>``:
+  If available, a tag-relative name of the commit produced by
+  ``git describe --contains <commit-ish>``.  Otherwise, the first
+  8-10 characters of the commit ``<hash>``.
+
+* ``<subject>``:
+  The first line of the commit message.
+
+* ``<date>``:
+  The author date of the commit, in its original time zone, formatted as
+  ``CCYY-MM-DD``.  ``git-log(1)`` shows the original time zone by default.
+
+Alternatively, the full commit ``<hash>`` may be used.
+
+Revising Commit Messages
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
 =============
 
diff --git a/Help/dev/source.rst b/Help/dev/source.rst
index 7e44995..b40a884 100644
--- a/Help/dev/source.rst
+++ b/Help/dev/source.rst
@@ -23,20 +23,18 @@ format only a subset of files, such as those that are locally modified.
 C++ Subset Permitted
 ====================
 
-CMake supports compiling as C++98 in addition to C++11 and C++14.
-In order to support building on older toolchains some constructs
-need to be handled with care:
+CMake requires compiling as C++11 or above.  However, in order to support
+building on older toolchains some constructs need to be handled with care:
 
-* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``.
+* Do not use ``CM_AUTO_PTR`` or ``std::auto_ptr``.
 
-  The ``std::auto_ptr`` template is deprecated in C++11.  We want to use it
-  so we can build on C++98 compilers but we do not want to turn off compiler
-  warnings about deprecated interfaces in general.  Use the ``CM_AUTO_PTR``
-  macro instead.
+  The ``std::auto_ptr`` template is deprecated in C++11.  The ``CM_AUTO_PTR``
+  macro remains leftover from C++98 support until its uses can be ported to
+  ``std::unique_ptr``.  Do not add new uses of the macro.
 
 * Use ``CM_EQ_DELETE;`` instead of ``= delete;``.
 
-  Defining functions as *deleted* is not supported in C++98.  Using
+  Older C++11 compilers do not support deleting functions.  Using
   ``CM_EQ_DELETE`` will delete the functions if the compiler supports it and
   give them no implementation otherwise.  Calling such a function will lead
   to compiler errors if the compiler supports *deleted* functions and linker
@@ -58,3 +56,50 @@ need to be handled with care:
   When assigning the result of ``.size()`` on a container for example,
   the result should be assigned to ``size_t`` not to ``std::size_t``,
   ``unsigned int`` or similar types.
+
+Source Tree Layout
+==================
+
+The CMake source tree is organized as follows.
+
+* ``Auxiliary/``:
+  Shell and editor integration files.
+
+* ``Help/``:
+  Documentation.
+
+  * ``Help/dev/``:
+    Developer documentation.
+
+  * ``Help/release/dev/``:
+    Release note snippets for development since last release.
+
+* ``Licenses/``:
+  License files for third-party libraries in binary distributions.
+
+* ``Modules/``:
+  CMake language modules installed with CMake.
+
+* ``Packaging/``:
+  Files used for packaging CMake itself for distribution.
+
+* ``Source/``:
+  Source code of CMake itself.
+
+* ``Templates/``:
+  Files distributed with CMake as implementation details for generators,
+  packagers, etc.
+
+* ``Tests/``:
+  The test suite.  See `Tests/README.rst`_.
+
+* ``Utilities/``:
+  Scripts, third-party source code.
+
+  * ``Utilities/Sphinx/``:
+    Sphinx configuration to build CMake user documentation.
+
+  * ``Utilities/Release/``:
+    Scripts used to package CMake itself for distribution on ``cmake.org``.
+
+.. _`Tests/README.rst`: ../../Tests/README.rst