From d33de80c8a9e3e5e56012cbfe640004f7cb1550f Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 23 Feb 2017 14:05:38 -0500 Subject: [PATCH 1/5] Help/dev: Exclude this directory from user-facing documentation Teach Sphinx and our own install rules to skip a `Help/dev` directory. This will give us a place to put developer-only documentation that should not be included in the user-facing documentation. Add a placeholder README. --- CMakeLists.txt | 1 + Help/dev/README.rst | 15 +++++++++++++++ Utilities/Sphinx/conf.py.in | 4 +++- 3 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 Help/dev/README.rst diff --git a/CMakeLists.txt b/CMakeLists.txt index 472c6ab7dd..ed5de10efd 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -806,6 +806,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE) PATTERN "*.sh*" PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE + REGEX "Help/dev($|/)" EXCLUDE ) # Install auxiliary files integrating with other tools. diff --git a/Help/dev/README.rst b/Help/dev/README.rst new file mode 100644 index 0000000000..a7cafccb3d --- /dev/null +++ b/Help/dev/README.rst @@ -0,0 +1,15 @@ +CMake Development +***************** + +This directory contains documentation about development of CMake itself. +It is not part of the user documentation distributed with CMake. + +Contributor Instructions +======================== + +See `CONTRIBUTING.rst`_ for instructions to contribute changes. + +The process for contributing changes is the same whether or not one +has been invited to participate directly in upstream development. + +.. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst diff --git a/Utilities/Sphinx/conf.py.in b/Utilities/Sphinx/conf.py.in index 9581458631..e3afc78ccd 100644 --- a/Utilities/Sphinx/conf.py.in +++ b/Utilities/Sphinx/conf.py.in @@ -18,7 +18,9 @@ release = '@conf_release@' # full version string primary_domain = 'cmake' -exclude_patterns = [] +exclude_patterns = [ + 'dev', # ignore developer-only documentation + ] extensions = ['cmake'] templates_path = ['@conf_path@/templates'] From 9360e6c6a0197e9ac05d085221eb7ec31be3c2eb Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 24 Feb 2017 16:16:19 -0500 Subject: [PATCH 2/5] Help/dev: Document the CMake Review Process --- Help/dev/README.rst | 12 ++ Help/dev/review.rst | 304 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 316 insertions(+) create mode 100644 Help/dev/review.rst diff --git a/Help/dev/README.rst b/Help/dev/README.rst index a7cafccb3d..6d3d46d8f1 100644 --- a/Help/dev/README.rst +++ b/Help/dev/README.rst @@ -13,3 +13,15 @@ The process for contributing changes is the same whether or not one has been invited to participate directly in upstream development. .. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst + +Upstream Development +==================== + +CMake uses `Kitware's GitLab Instance`_ to manage development, review, and +integration of changes. The `CMake Repository`_ holds the integration +branches and tags. Changes follow the `CMake Review Process`_ for +integration. + +.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com +.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake +.. _`CMake Review Process`: review.rst diff --git a/Help/dev/review.rst b/Help/dev/review.rst new file mode 100644 index 0000000000..ca64b95d5d --- /dev/null +++ b/Help/dev/review.rst @@ -0,0 +1,304 @@ +CMake Review Process +******************** + +The following documents the process for reviewing and integrating changes. +See `CONTRIBUTING.rst`_ for instructions to contribute changes. +See documentation on `CMake Development`_ for more information. + +.. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst +.. _`CMake Development`: README.rst + +.. contents:: The review process consists of the following steps: + +Merge Request +============= + +A user initiates the review process for a change by pushing a *topic +branch* to his or her own fork of the `CMake Repository`_ on GitLab and +creating a *merge request* ("MR"). The new MR will appear on the +`CMake Merge Requests Page`_. The rest of the review and integration +process is managed by the merge request page for the change. + +During the review process, the MR submitter should address review comments +or test failures by updating the MR with a (force-)push of the topic +branch. The update initiates a new round of review. + +We recommend that users enable the "Remove source branch when merge +request is accepted" option when creating the MR or by editing it. +This will cause the MR topic branch to be automatically removed from +the user's fork during the `Merge`_ step. + +.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/merge_requests +.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake + +Workflow Status +--------------- + +`CMake GitLab Project Developers`_ may set one of the following labels +in GitLab to track the state of a MR: + +* ``workflow:wip`` indicates that the MR needs additional updates from + the MR submitter before further review. Use this label after making + comments that require such updates. + +* ``workflow:in-review`` indicates that the MR awaits feedback from a + human reviewer or from `Topic Testing`_. Use this label after making + comments requesting such feedback. + +* ``workflow:nightly-testing`` indicates that the MR awaits results + of `Integration Testing`_. Use this label after making comments + requesting such staging. + +* ``workflow:expired`` indicates that the MR has been closed due + to a period of inactivity. See the `Expire`_ step. Use this label + after closing a MR for this reason. + +The workflow status labels are intended to be mutually exclusive, +so please remove any existing workflow label when adding one. + +.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/settings/members + +Robot Review +============ + +The "Kitware Robot" (``@kwrobot``) automatically performs basic checks on +the commits proposed in a MR. If all is well the robot silently reports +a successful "build" status to GitLab. Otherwise the robot posts a comment +with its diagnostics. **A topic may not be merged until the automatic +review succeeds.** The MR submitter is expected to address the robot's +comments by *rewriting* the commits named by the robot's diagnostics +(e.g. via ``git rebase -i``). + +The automatic check is repeated whenever the topic branch is updated. +One may explicitly request a re-check by adding a comment with the +following command among the `comment trailing lines`_:: + + Do: check + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also run its checks again. + +Human Review +============ + +Anyone is welcome to review merge requests and make comments! + +Reviewers may add comments providing feedback or to acknowledge their +approval. Lines of specific forms will be extracted during the `merge`_ +step and included as trailing lines of the generated merge commit message. +Each review comment consists of up to two parts which must be specified +in the following order: `comment body`_, then `comment trailing lines`_. +Each part is optional, but they must be specified in this order. + +Comment Body +------------ + +The body of a comment may be free-form `GitLab Flavored Markdown`_. +See GitLab documentation on `Special GitLab References`_ to add links to +things like issues, commits, or other merge requests (even across projects). + +Additionally, a line in the comment body may start with one of the +following votes: + +* ``-1`` or ``:-1:`` indicates "the change is not ready for integration". + +* ``+1`` or ``:+1:`` indicates "I like the change". + This adds an ``Acked-by:`` trailer to the `merge`_ commit message. + +* ``+2`` indicates "the change is ready for integration". + This adds a ``Reviewed-by:`` trailer to the `merge`_ commit message. + +* ``+3`` indicates "I have tested the change and verified it works". + This adds a ``Tested-by:`` trailer to the `merge`_ commit message. + +.. _`GitLab Flavored Markdown`: https://gitlab.kitware.com/help/user/markdown.md +.. _`Special GitLab References`: https://gitlab.kitware.com/help/user/markdown.md#special-gitlab-references + +Comment Trailing Lines +---------------------- + +Zero or more *trailing* lines in the last section of a comment may appear +with the form ``Key: Value``. The first such line should be separated +from a preceding `comment body`_ by a blank line. Any key-value pair(s) +may be specified for human reference. A few specific keys have meaning to +``@kwrobot`` as follows. + +Comment Trailer Votes +^^^^^^^^^^^^^^^^^^^^^ + +Among the `comment trailing lines`_ one may cast a vote using one of the +following pairs followed by nothing but whitespace before the end of the line: + +* ``Rejected-by: me`` indicates "the change is not ready for integration". +* ``Acked-by: me`` indicates "I like the change". + This adds an ``Acked-by:`` trailer to the `merge`_ commit message. +* ``Reviewed-by: me`` indicates "the change is ready for integration". + This adds a ``Reviewed-by:`` trailer to the `merge`_ commit message. +* ``Tested-by: me`` indicates "I have tested the change and verified it works". + This adds a ``Tested-by:`` trailer to the `merge`_ commit message. + +Each ``me`` reference may instead be an ``@username`` reference or a full +``Real Name `` reference to credit someone else for performing +the review. References to ``me`` and ``@username`` will automatically be +transformed into a real name and email address according to the user's +GitLab account profile. + +Comment Trailer Commands +^^^^^^^^^^^^^^^^^^^^^^^^ + +Among the `comment trailing lines`_ authorized users may issue special +commands to ``@kwrobot`` using the form ``Do: ...``: + +* ``Do: check`` explicitly re-runs `Robot Review`_ checks. +* ``Do: test`` submits the MR for `Topic Testing`_. +* ``Do: stage`` submits the MR for `Integration Testing`_. +* ``Do: merge`` submits the MR for `Merge`_. + +See the corresponding sections for details on permissions and options +for each command. + +Topic Testing +============= + +CMake has a `buildbot`_ instance watching for merge requests to test. +`CMake GitLab Project Developers`_ may activate buildbot on a MR by +adding a comment with a command among the `comment trailing lines`_:: + + Do: test + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also inform buildbot about the request. The buildbot +user (``@buildbot``) will schedule builds and respond with a comment +linking to the `CMake CDash Page`_ with a filter for results associated +with the topic test request. If the MR topic branch is updated by a +push a new ``Do: test`` command is needed to activate testing again. + +The ``Do: test`` command accepts the following arguments: + +* ``--stop``: clear the list of commands for the merge request +* ``--clear``: clear previous commands before adding this command +* ``--regex-include `` or ``-i ``: only build on builders + matching ```` (a Python regular expression) +* ``--regex-exclude `` or ``-e ``: exclude builds on builders + matching ```` (a Python regular expression) + +Builder names follow the pattern ``project-host-os-buildtype-generator``: + +* ``project``: always ``cmake`` for CMake builds +* ``host``: the buildbot host +* ``os``: one of ``windows``, ``osx``, or ``linux`` +* ``buildtype``: ``release`` or ``debug`` +* ``generator``: ``ninja``, ``makefiles``, or ``vs`` + +.. _`buildbot`: http://buildbot.net +.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake + +Integration Testing +=================== + +The above `topic testing`_ tests the MR topic independent of other +merge requests and on only a few key platforms and configurations. +CMake also has a large number of testing machines provided by Kitware +and generous volunteers that cover nearly all supported platforms, +generators, and configurations. In order to avoid overwhelming these +resources, they do not test every MR individually. Instead, these +machines follow an *integration branch*, run tests on a nightly basis +(or continuously during the day), and post to the `CMake CDash Page`_. +Some follow ``master``. Most follow a special integration branch, +the *topic stage*. + +The topic stage is a special branch maintained by the "Kitware Robot" +(``@kwrobot``). It consists of the head of the MR target integration +branch (e.g. ``master``) branch followed by a sequence of merges each +integrating changes from an open MR that has been staged for integration +testing. Each time the target integration branch is updated the stage +is rebuilt automatically by merging the staged MR topics again. + +`CMake GitLab Project Developers`_ may stage a MR for integration testing +by adding a comment with a command among the `comment trailing lines`_:: + + Do: stage + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also attempt to add the MR topic branch to the topic +stage. If the MR cannot be added (e.g. due to conflicts) the robot will +post a comment explaining what went wrong. + +Once a MR has been added to the topic stage it will remain on the stage +until one of the following occurs: + +* The MR topic branch is updated by a push. + +* The MR target integration branch (e.g. ``master``) branch is updated + and the MR cannot be merged into the topic stage again due to conflicts. + +* A developer or the submitter posts an explicit ``Do: unstage`` command. + +* The MR is closed. + +* The MR is merged. + +Once a MR has been removed from the topic stage a new ``Do: stage`` +command is needed to stage it again. + +Resolve +======= + +A MR may be resolved in one of the following ways. + +Merge +----- + +Once review has concluded that the MR topic is ready for integration, +`CMake GitLab Project Masters`_ may merge the topic by adding a comment +with a command among the `comment trailing lines`_:: + + Do: merge + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also attempt to merge the MR topic branch to the MR +target integration branch (e.g. ``master``). If the MR cannot be merged +(e.g. due to conflicts) the robot will post a comment explaining what +went wrong. If the MR is merged the robot will also remove the source +branch from the user's fork if the corresponding MR option was checked. + +The robot automatically constructs a merge commit message of the following +form:: + + Merge topic 'mr-topic-branch-name' + + 00000000 commit message subject line (one line per commit) + + Acked-by: Kitware Robot + Merge-request: !0000 + +Mention of the commit short sha1s and MR number helps GitLab link the +commits back to the merge request and indicates when they were merged. +The ``Acked-by:`` trailer shown indicates that `Robot Review`_ passed. +Additional ``Acked-by:``, ``Reviewed-by:``, and similar trailers may be +collected from `Human Review`_ comments that have been made since the +last time the MR topic branch was updated with a push. + +The ``Do: merge`` command accepts the following arguments: + +* ``-t ``: substitute ```` for the name of the MR topic + branch in the constructed merge commit message. + +.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members + +Close +----- + +If review has concluded that the MR should not be integrated then it +may be closed through GitLab. + +Expire +------ + +If progress on a MR has stalled for a while, it may be closed with a +``workflow:expired`` label and a comment indicating that the MR has +been closed due to inactivity. + +Contributors are welcome to re-open an expired MR when they are ready +to continue work. Please re-open *before* pushing an update to the +MR topic branch to ensure GitLab will still act on the association. From 205ac0f034b9fac9d220b2c24a17738708f3068b Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 23 Feb 2017 14:10:56 -0500 Subject: [PATCH 3/5] CONTRIBUTING: Add note about running developer setup script --- CONTRIBUTING.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 921ba7c9b5..61d2a6337b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -19,6 +19,7 @@ CMake uses `Kitware's GitLab Instance`_ to manage development and code review. To contribute patches: #. Fork the upstream `CMake Repository`_ into a personal account. +#. Run `Utilities/SetupForDevelopment.sh`_ for local configuration. #. Base all new work on the upstream ``master`` branch. #. Create commits making incremental, distinct, logically complete changes. #. Push a topic branch to a personal repository fork on GitLab. @@ -26,6 +27,7 @@ To contribute patches: .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake +.. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh Code Style ========== From 9a65b1272c94cfbaa929e674db55c67485a2cf2a Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 23 Feb 2017 15:56:50 -0500 Subject: [PATCH 4/5] CONTRIBUTING: Add link to development documentation README --- CONTRIBUTING.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 61d2a6337b..3eba1a51cf 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,6 +1,11 @@ Contributing to CMake ********************* +The following summarizes the process for contributing changes. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: Help/dev/README.rst + Community ========= From 1cc73e9a6c6dca38a163a8e61208b6ab74839441 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 23 Feb 2017 14:56:00 -0500 Subject: [PATCH 5/5] CONTRIBUTING: Add link to review process document --- CONTRIBUTING.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3eba1a51cf..434f0f448a 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -30,9 +30,12 @@ To contribute patches: #. Push a topic branch to a personal repository fork on GitLab. #. Create a GitLab Merge Request targeting the upstream ``master`` branch. +The merge request will enter the `CMake Review Process`_ for consideration. + .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake .. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh +.. _`CMake Review Process`: Help/dev/review.rst Code Style ==========