Skip to content

Commit

Permalink
Document CI
Browse files Browse the repository at this point in the history
  • Loading branch information
hcho3 committed Nov 22, 2024
1 parent 7540203 commit a8a8c6a
Show file tree
Hide file tree
Showing 8 changed files with 256 additions and 126 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/update_rapids.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ jobs:
if: github.ref == 'refs/heads/master'
with:
add-paths: |
tests/buildkite
ops/docker
branch: create-pull-request/update-rapids
base: master
title: "[CI] Update RAPIDS to latest stable"
Expand Down
2 changes: 1 addition & 1 deletion dev/release-artifacts.py
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ def make_python_sdist(
with DirectoryExcursion(ROOT):
with open("python-package/pyproject.toml", "r") as f:
orig_pyproj_lines = f.read()
with open("tests/buildkite/remove_nccl_dep.patch", "r") as f:
with open("ops/patch/remove_nccl_dep.patch", "r") as f:
patch_lines = f.read()
subprocess.run(
["patch", "-p0"], input=patch_lines, check=True, text=True, encoding="utf-8"
Expand Down
349 changes: 239 additions & 110 deletions doc/contrib/ci.rst

Large diffs are not rendered by default.

16 changes: 8 additions & 8 deletions doc/contrib/coding_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ C++ interface of the R package, please make corresponding changes in ``src/init.
Generating the Package and Running Tests
========================================

The source layout of XGBoost is a bit unusual to normal R packages as XGBoost is primarily written in C++ with multiple language bindings in mind. As a result, some special cares need to be taken to generate a standard R tarball. Most of the tests are being run on CI, and as a result, the best way to see how things work is by looking at the CI configuration files (GitHub action, at the time of writing). There are helper scripts in ``tests/ci_build`` and ``R-package/tests/helper_scripts`` for running various checks including linter and making the standard tarball.
The source layout of XGBoost is a bit unusual to normal R packages as XGBoost is primarily written in C++ with multiple language bindings in mind. As a result, some special cares need to be taken to generate a standard R tarball. Most of the tests are being run on CI, and as a result, the best way to see how things work is by looking at the CI configuration files (GitHub action, at the time of writing). There are helper scripts in ``ops/script`` and ``R-package/tests/helper_scripts`` for running various checks including linter and making the standard tarball.

*********************************
Running Formatting Checks Locally
Expand All @@ -127,29 +127,29 @@ To run checks for Python locally, install the checkers mentioned previously and
.. code-block:: bash
cd /path/to/xgboost/
python ./tests/ci_build/lint_python.py --fix
python ./ops/script/lint_python.py --fix
To run checks for R:

.. code-block:: bash
cd /path/to/xgboost/
R CMD INSTALL R-package/
Rscript tests/ci_build/lint_r.R $(pwd)
Rscript ops/script/lint_r.R $(pwd)
To run checks for cpplint locally:

.. code-block:: bash
cd /path/to/xgboost/
python ./tests/ci_build/lint_cpp.py
python ./ops/script/lint_cpp.py
See next section for clang-tidy. For CMake scripts:

.. code-block:: bash
bash ./tests/ci_build/lint_cmake.sh
bash ./ops/script/lint_cmake.sh
Lastly, the linter for jvm-packages is integrated into the maven build process.

Expand All @@ -163,21 +163,21 @@ To run this check locally, run the following command from the top level source t
.. code-block:: bash
cd /path/to/xgboost/
python3 tests/ci_build/tidy.py
python3 ops/script/run_clang_tidy.py
Also, the script accepts two optional integer arguments, namely ``--cpp`` and ``--cuda``. By default they are both set to 1, meaning that both C++ and CUDA code will be checked. If the CUDA toolkit is not installed on your machine, you'll encounter an error. To exclude CUDA source from linting, use:

.. code-block:: bash
cd /path/to/xgboost/
python3 tests/ci_build/tidy.py --cuda=0
python3 ops/script/run_clang_tidy.py --cuda=0
Similarly, if you want to exclude C++ source from linting:

.. code-block:: bash
cd /path/to/xgboost/
python3 tests/ci_build/tidy.py --cpp=0
python3 ops/script/run_clang_tidy.py --cpp=0
**********************************
Guide for handling user input data
Expand Down
8 changes: 4 additions & 4 deletions doc/contrib/donate.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ DMLC/XGBoost has grown from a research project incubated in academia to one of t

A robust and efficient **continuous integration (CI)** infrastructure is one of the most critical solutions to address the above challenge. A CI service will monitor an open-source repository and run a suite of integration tests for every incoming contribution. This way, the CI ensures that every proposed change in the codebase is compatible with existing functionalities. Furthermore, XGBoost can enable more thorough tests with a powerful CI infrastructure to cover cases which are closer to the production environment.

There are several CI services available free to open source projects, such as Travis CI and AppVeyor. The XGBoost project already utilizes GitHub Actions. However, the XGBoost project has needs that these free services do not adequately address. In particular, the limited usage quota of resources such as CPU and memory leaves XGBoost developers unable to bring "too-intensive" tests. In addition, they do not offer test machines with GPUs for testing XGBoost-GPU code base which has been attracting more and more interest across many organizations. Consequently, the XGBoost project uses a cloud-hosted test farm. We use `BuildKite <https://buildkite.com/xgboost>`_ to organize CI pipelines.
There are several CI services available free to open source projects, such as Travis CI and AppVeyor. The XGBoost project already utilizes GitHub Actions. However, the XGBoost project has needs that these free services do not adequately address. In particular, the limited usage quota of resources such as CPU and memory leaves XGBoost developers unable to bring "too-intensive" tests. In addition, they do not offer test machines with GPUs for testing XGBoost-GPU code base which has been attracting more and more interest across many organizations. Consequently, the XGBoost project uses a cloud-hosted test farm. We host `Amazon Web Services (AWS) <https://aws.amazon.com/>`_ to host the test machines, along with `GitHub Actions <https://github.com/features/actions>`_ and `RunsOn <https://runs-on.com/>`_ (SaaS app) to organize the CI pipelines.

The cloud-hosted test farm has recurring operating expenses. It utilizes a leading cloud provider (AWS) to accommodate variable workload. BuildKite launches worker machines on AWS on demand, to run the test suite on incoming contributions. To save cost, the worker machines are terminated when they are no longer needed.
The cloud-hosted test farm has recurring operating expenses. RunsOn launches worker machines on AWS on demand to run the test suite on incoming contributions. To save cost, the worker machines are terminated when they are no longer needed.

To help defray the hosting cost, the XGBoost project seeks donations from third parties.

Expand All @@ -29,9 +29,9 @@ The Project Management Committee (PMC) of the XGBoost project appointed `Open So

All expenses incurred for hosting CI will be submitted to the fiscal host with receipts. Only the expenses in the following categories will be approved for reimbursement:

* Cloud expenses for the cloud test farm (https://buildkite.com/xgboost)
* Cloud expenses for the cloud test farm
* Cost of domain https://xgboost-ci.net
* Monthly cost of using BuildKite
* Annual subscription for RunsOn
* Hosting cost of the User Forum (https://discuss.xgboost.ai)

Administration of cloud CI infrastructure
Expand Down
2 changes: 1 addition & 1 deletion doc/contrib/release.rst
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Making a Release
-----------------

1. Create an issue for the release, noting the estimated date and expected features or major fixes, pin that issue.
2. Create a release branch if this is a major release. Bump release version. There's a helper script ``tests/ci_build/change_version.py``.
2. Create a release branch if this is a major release. Bump release version. There's a helper script ``ops/script/change_version.py``.
3. Commit the change, create a PR on GitHub on release branch. Port the bumped version to default branch, optionally with the postfix ``SNAPSHOT``.
4. Create a tag on release branch, either on GitHub or locally.
5. Make a release on GitHub tag page, which might be done with previous step if the tag is created on GitHub.
Expand Down
2 changes: 1 addition & 1 deletion doc/contrib/unit_tests.rst
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Run

.. code-block:: bash
python ./tests/ci_build/test_r_package.py --task=check
python ./ops/script/test_r_package.py --task=check
at the root of the project directory. The command builds and checks the XGBoost
r-package. Alternatively, if you want to just run the tests, you can use the following
Expand Down
1 change: 1 addition & 0 deletions ops/pipeline/test-python-wheel.sh
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ else
gpu_option=""
fi

set -x
python3 ops/docker_run.py --container-id "${container_id}" ${gpu_option} \
--run-args='--shm-size=4g' \
-- bash ops/pipeline/test-python-wheel-impl.sh "${suite}"

0 comments on commit a8a8c6a

Please sign in to comment.