diff --git a/.cirrus.yml b/.cirrus.yml index 3f9e45b5ea..0a7c972821 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -18,6 +18,16 @@ container: env: + # Skip specific tasks by name. Set to a non-empty string to skip. + SKIP_LINT_TASK: "" + SKIP_TEST_MINIMAL_TASK: "" + SKIP_TEST_FULL_TASK: "" + SKIP_GALLERY_TASK: "" + SKIP_DOCTEST_TASK: "" + SKIP_LINKCHECK_TASK: "" + # Skip task groups by type. Set to a non-empty string to skip. + SKIP_ALL_TEST_TASKS: "" + SKIP_ALL_DOC_TASKS: "" # Maximum cache period (in weeks) before forcing a new cache upload. CACHE_PERIOD: "2" # Increment the build number to force new cartopy cache upload. @@ -50,7 +60,7 @@ linux_task_template: &LINUX_TASK_TEMPLATE fingerprint_script: - wget --quiet https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh - echo "${CIRRUS_OS} $(sha256sum miniconda.sh)" - - echo "$(date +%Y).$(($(date +%U) / ${CACHE_PERIOD})):${CONDA_CACHE_BUILD}" + - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${CONDA_CACHE_BUILD}" populate_script: - bash miniconda.sh -b -p ${HOME}/miniconda - conda config --set always_yes yes --set changeps1 no @@ -62,12 +72,12 @@ linux_task_template: &LINUX_TASK_TEMPLATE folder: ${HOME}/.local/share/cartopy fingerprint_script: - echo "${CIRRUS_OS}" - - echo "$(date +%Y).$(($(date +%U) / ${CACHE_PERIOD})):${CARTOPY_CACHE_BUILD}" + - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${CARTOPY_CACHE_BUILD}" nox_cache: folder: ${CIRRUS_WORKING_DIR}/.nox fingerprint_script: - echo "${CIRRUS_TASK_NAME}" - - echo "$(date +%Y).$(($(date +%U) / ${CACHE_PERIOD})):${NOX_CACHE_BUILD}" + - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${NOX_CACHE_BUILD}" - sha256sum ${CIRRUS_WORKING_DIR}/requirements/ci/py$(echo ${PY_VER} | tr -d ".").yml @@ -82,6 +92,7 @@ compute_credits_template: &CREDITS_TEMPLATE # Linting # lint_task: + only_if: $SKIP_LINT_TASK == "" << : *CREDITS_TEMPLATE auto_cancellation: true name: "${CIRRUS_OS}: flake8 and black" @@ -89,7 +100,7 @@ lint_task: folder: ~/.cache/pip fingerprint_script: - echo "${CIRRUS_TASK_NAME}" - - echo "$(date +%Y).$(($(date +%U) / ${CACHE_PERIOD})):${PIP_CACHE_BUILD} ${PIP_CACHE_PACKAGES}" + - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${PIP_CACHE_BUILD} ${PIP_CACHE_PACKAGES}" lint_script: - pip list - python -m pip install --retries 3 --upgrade ${PIP_CACHE_PACKAGES} @@ -101,7 +112,8 @@ lint_task: # # Testing Minimal (Linux) # -linux_minimal_task: +test_minimal_task: + only_if: $SKIP_TEST_MINIMAL_TASK == "" && $SKIP_ALL_TEST_TASKS == "" << : *CREDITS_TEMPLATE matrix: env: @@ -125,7 +137,8 @@ linux_minimal_task: # # Testing Full (Linux) # -linux_task: +test_full_task: + only_if: $SKIP_TEST_FULL_TASK == "" && $SKIP_ALL_TEST_TASKS == "" << : *CREDITS_TEMPLATE matrix: env: @@ -159,6 +172,7 @@ linux_task: # Testing Documentation Gallery (Linux) # gallery_task: + only_if: $SKIP_GALLERY_TASK == "" && $SKIP_ALL_DOC_TASKS == "" << : *CREDITS_TEMPLATE matrix: env: @@ -188,6 +202,7 @@ gallery_task: # Testing Documentation (Linux) # doctest_task: + only_if: $SKIP_DOCTEST_TASK == "" && $SKIP_ALL_DOC_TASKS == "" << : *CREDITS_TEMPLATE matrix: env: @@ -222,7 +237,8 @@ doctest_task: # # Testing Documentation Link Check (Linux) # -link_task: +linkcheck_task: + only_if: $SKIP_LINKCHECK_TASK == "" && $SKIP_ALL_DOC_TASKS == "" << : *CREDITS_TEMPLATE matrix: env: diff --git a/docs/src/common_links.inc b/docs/src/common_links.inc index 23a933367e..d9df15be8b 100644 --- a/docs/src/common_links.inc +++ b/docs/src/common_links.inc @@ -3,6 +3,7 @@ .. _black: https://black.readthedocs.io/en/stable/ .. _.cirrus.yml: https://github.com/SciTools/iris/blob/master/.cirrus.yml +.. _flake8: https://flake8.pycqa.org/en/stable/ .. _.flake8.yml: https://github.com/SciTools/iris/blob/master/.flake8 .. _cirrus-ci: https://cirrus-ci.com/github/SciTools/iris .. _conda: https://docs.conda.io/en/latest/ diff --git a/docs/src/developers_guide/contributing_ci_tests.rst b/docs/src/developers_guide/contributing_ci_tests.rst index a6bdac4ae0..8594612fe1 100644 --- a/docs/src/developers_guide/contributing_ci_tests.rst +++ b/docs/src/developers_guide/contributing_ci_tests.rst @@ -5,9 +5,9 @@ Continuous Integration (CI) Testing =================================== -The `Iris`_ GitHub repository is configured to run checks on the code -automatically when a pull request is created, updated or merged against -Iris **master**. The checks performed are: +The `Iris`_ GitHub repository is configured to run checks against all its +branches automatically whenever a pull request is created, updated or merged. +The checks performed are: * :ref:`testing_cla` * :ref:`testing_cirrus` @@ -18,9 +18,9 @@ Iris **master**. The checks performed are: SciTools CLA Checker ******************** -A bot that checks the user who created the pull request has signed the -**Contributor's License Agreement (CLA)**. For more information on this this -please see https://scitools.org.uk/organisation.html#governance +A bot which checks that the GitHub author of the pull request has signed the +**SciTools Contributor's License Agreement (CLA)**. For more information on +this please see https://scitools.org.uk/organisation.html#governance. .. _testing_cirrus: @@ -28,19 +28,55 @@ please see https://scitools.org.uk/organisation.html#governance Cirrus-CI ********* -The unit and integration tests in Iris are an essential mechanism to ensure +Iris unit and integration tests are an essential mechanism to ensure that the Iris code base is working as expected. :ref:`developer_running_tests` -may be run manually but to ensure the checks are performed a -continuous integration testing tool named `cirrus-ci`_ is used. +may be performed manually by a developer locally. However Iris is configured to +use the `cirrus-ci`_ service for automated Continuous Integration (CI) testing. -A `cirrus-ci`_ configuration file named `.cirrus.yml`_ -is in the Iris repository which tells Cirrus-CI what commands to run. The -commands include retrieving the Iris code base and associated test files using -conda and then running the tests. `cirrus-ci`_ allows for a matrix of tests to -be performed to ensure that all expected variations test successfully. +The `cirrus-ci`_ configuration file `.cirrus.yml`_ in the root of the Iris repository +defines the tasks to be performed by `cirrus-ci`_. For further details +refer to the `Cirrus-CI Documentation`_. The tasks performed during CI include: + +* linting the code base and ensuring it adheres to the `black`_ format +* running the system, integration and unit tests for Iris +* ensuring the documentation gallery builds successfully +* performing all doc-tests within the code base +* checking all URL references within the code base and documentation are valid + +The above `cirrus-ci`_ tasks are run automatically against all `Iris`_ branches +on GitHub whenever a pull request is submitted, updated or merged. See the +`Cirrus-CI Dashboard`_ for details of recent past and active Iris jobs. + +.. _skipping Cirrus-CI tasks: + +Skipping Cirrus-CI Tasks +------------------------ + +As a developer you may wish to not run all the CI tasks when you are actively +developing e.g., you are writing documentation and there is no need for linting, +or long running compute intensive testing tasks to be executed. + +As a convenience, it is possible to easily skip one or more tasks by setting +the appropriate environment variable within the `.cirrus.yml`_ file to a +**non-empty** string: + +* ``SKIP_LINT_TASK`` to skip `flake8`_ linting and `black`_ formatting +* ``SKIP_TEST_MINIMAL_TASK`` to skip restricted unit and integration testing +* ``SKIP_TEST_FULL_TASK`` to skip full unit and integration testing +* ``SKIP_GALLERY_TASK`` to skip building the documentation gallery +* ``SKIP_DOCTEST_TASK`` to skip running the documentation doc-tests +* ``SKIP_LINKCHECK_TASK`` to skip checking for broken documentation URL references +* ``SKIP_ALL_TEST_TASKS`` which is equivalent to setting ``SKIP_TEST_MINIMAL_TASK`` and ``SKIP_TEST_FULL_TASK`` +* ``SKIP_ALL_DOC_TASKS`` which is equivalent to setting ``SKIP_GALLERY_TASK``, ``SKIP_DOCTEST_TASK``, and ``SKIP_LINKCHECK_TASK`` + +e.g., to skip the linting task, the following are all equivalent:: + + SKIP_LINT_TASK: "1" + SKIP_LINT_TASK: "true" + SKIP_LINT_TASK: "false" + SKIP_LINT_TASK: "skip" + SKIP_LINT_TASK: "unicorn" -The `cirrus-ci`_ tests are run automatically against the `Iris`_ master -repository when a pull request is submitted, updated or merged. GitHub Checklist **************** @@ -50,6 +86,10 @@ passing: .. image:: ci_checks.png -If any CI checks fail, then the pull request is unlikely to be merged to the +If any CI tasks fail, then the pull request is unlikely to be merged to the Iris target branch by a core developer. + +.. _Cirrus-CI Dashboard: https://cirrus-ci.com/github/SciTools/iris +.. _Cirrus-CI Documentation: https://cirrus-ci.org/guide/writing-tasks/ + diff --git a/docs/src/developers_guide/contributing_code_formatting.rst b/docs/src/developers_guide/contributing_code_formatting.rst index 6bf8dca717..1a3573d135 100644 --- a/docs/src/developers_guide/contributing_code_formatting.rst +++ b/docs/src/developers_guide/contributing_code_formatting.rst @@ -58,6 +58,4 @@ will look similar to:: their officially documentation for more information. -.. _black: https://black.readthedocs.io/en/stable/ -.. _flake8: https://flake8.pycqa.org/en/stable/ .. _pre-commit: https://pre-commit.com/ diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 59e75942b0..4abf1e1192 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -124,6 +124,10 @@ This document explains the changes made to Iris for this release #. `@akuhnregnier`_ replaced `deprecated numpy 1.20 aliases for builtin types`_. (:pull:`3997`) +#. `@bjlittle`_ added conditional task execution to `.cirrus.yml`_ to allow + developers to easily disable `cirrus-ci`_ tasks. See + :ref:`skipping Cirrus-CI tasks`. (:pull:`4019`) + .. comment Whatsnew author names (@github name) in alphabetical order. Note that,