mirror of
https://gitlab.kitware.com/cmake/cmake.git
synced 2026-09-25 04:09:36 +03:00
Taylor Braun-Jones
d326c8afd5
Provide a `.devcontainer` definition, following the Dev Container Specification, to give contributors a ready-made Linux environment with the tools needed to build CMake, run its test suite, build its documentation, and satisfy its style rules. Base the container on Ubuntu, which offers the broadest ecosystem of packages and tooling for development, including a recent `cmake` and the `clang-format` version our style rules require, exactly. Mirror the package lists of the Debian image our CI infrastructure uses, section by section, so that the dependencies available closely match the ones against which merge requests are tested. Build the image the way the images under `.gitlab/ci/docker/` are built: bind mount the package lists and the installation script rather than copying them in, and cache the package lists and downloaded archives so that a rebuild fetches only what has changed. Run optional `.devcontainer/hooks/root.sh` and `.devcontainer/hooks/user.sh` scripts, both ignored by Git, so that developers may customize the container without modifying tracked files. Document usage in a new `Help/dev/devcontainer.rst`. Fixes: #28043
87 lines
3.5 KiB
ReStructuredText
87 lines
3.5 KiB
ReStructuredText
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
|
|
=========
|
|
|
|
CMake is maintained and supported by `Kitware`_ and developed in
|
|
collaboration with a productive community of contributors.
|
|
Please post to the ``Development`` category of the `CMake Forum`_ to raise
|
|
discussion of development topics.
|
|
|
|
.. _`Kitware`: https://www.kitware.com/cmake
|
|
.. _`CMake Forum`: https://discourse.cmake.org
|
|
|
|
Patches
|
|
=======
|
|
|
|
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 git configuration.
|
|
#. See `Building CMake`_ for building CMake locally.
|
|
Optionally, see the `CMake Dev Container Guide`_ for a ready-made
|
|
development environment.
|
|
#. See the `CMake Source Code Guide`_ for coding guidelines
|
|
and the `CMake Testing Guide`_ for testing instructions.
|
|
#. Create a topic branch named suitably for your work.
|
|
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.
|
|
If in doubt, prefer ``master``. Reviewers may simply ask for
|
|
a rebase if deemed appropriate in particular cases.
|
|
#. Create commits making incremental, distinct, logically complete changes
|
|
with appropriate `commit messages`_.
|
|
#. Push the 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).
|
|
Check the box labeled "Allow commits from members who can merge to the
|
|
target branch". This will allow maintainers to make minor edits on your
|
|
behalf.
|
|
|
|
The merge request will enter the `CMake Review Process`_ for consideration.
|
|
|
|
Please note `CMake's AI policy`_ if using AI tools or services as part of
|
|
preparing or submitting a change.
|
|
|
|
.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
|
|
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
|
|
.. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh
|
|
.. _`Building CMake`: README.rst#building-cmake
|
|
.. _`CMake Dev Container Guide`: Help/dev/devcontainer.rst
|
|
.. _`CMake Source Code Guide`: Help/dev/source.rst
|
|
.. _`CMake Testing Guide`: Help/dev/testing.rst
|
|
.. _`commit messages`: Help/dev/review.rst#commit-messages
|
|
.. _`CMake Review Process`: Help/dev/review.rst
|
|
.. _`CMake's AI policy`: Help/dev/ai-policy.rst
|
|
|
|
CMake Dashboard Client
|
|
======================
|
|
|
|
The *integration testing* step of the `CMake Review Process`_ uses a set of
|
|
testing machines that follow an integration branch on their own schedule to
|
|
drive testing and submit results to the `CMake CDash Page`_. Anyone is
|
|
welcome to provide testing machines in order to help keep support for their
|
|
platforms working.
|
|
|
|
See documentation on `CMake Integration Testing`_ for more information.
|
|
|
|
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
|
|
.. _`CMake Integration Testing`: Help/dev/integration-testing.rst
|
|
|
|
License
|
|
=======
|
|
|
|
We do not require any formal copyright assignment or contributor license
|
|
agreement. Any contributions intentionally sent upstream are presumed
|
|
to be offered under terms of the OSI-approved BSD 3-clause License.
|
|
See `LICENSE.rst`_ for details.
|
|
|
|
.. _`LICENSE.rst`: LICENSE.rst
|