cicd.rst

Continuous Integration
======================

The Continuous Integration is based on Jenkins.
A push to git repository will trigger a build for the package on Jenkins platform.
Then an email with a build log and unit test coverage report will be delivered to
the relavant developer.


``build status`` explained
--------------------------

The ``build status`` is in the subject of the notification email from ``csst_das@nao.cas.cn``
Here are the explanations of them.

Successful
   Congratulations! Your code passes all tests.
Fixed
   Although last build fails, this build is successful.
Failure
   Current build fails in at least one test.
Still Failing
   Current build fails in at least one test. And last build fails.


``build log`` explained
-----------------------

The build log includes several sections on

1. a check on versions of requirements
   The status will be non-zero if any of your requirements is behind other developers.
2. a check on installation of requirements
   The status will be non-zero if ``pip install -r requirements.txt`` exit with non-zero status.
3. a check on installation of package
   The status will be non-zero if the following code are unsuccessfully executed

   .. code-block:: bash

      rm -rf dist                                           # remove dist directory if exists
      python setup.py build_ext --inplace                   # build extension
      python setup.py sdist                                 # build source code
      pip install dist/*.tar.gz --force-reinstall --no-deps # install package without dependencies

4. a check on import of interfaces (top_level_interface)
   The status will be non-zero if the following code are unsuccessfully executed

   .. code-block:: python

      from <your_package>.top_level_interface import *

5. unit tests and coverage
   The status will be non-zero if the following code are unsuccessfully executed

   .. code-block:: bash

      coverage run -m pytest --import-mode=importlib

6. Numpydoc validation of interfaces

   .. code-block:: bash

      python -m numpydoc --validate {YOUR_PACKAGE}.top_level_interface.{YOUR_FUNCTION/CLASS}


An example of test summary is at the end of build log (the attached ``build.zip``).
If all checks/tests/validations passed, you will see a section as below.

.. code-block::

    ===================== TEST SUMMARY =====================
    Test passed!
    Check requirements: 0
    Install requirements: 0
    Install package: 0
    Importability status: 0
    Unit test status: 0
    Numpydoc status: 0


Unit test coverage report
-------------------------

The ``build log`` also contains a section of unit test coverage report.
An example is below.

.. code-block::

       Name                                Stmts   Miss  Cover
    -------------------------------------------------------
    csst_proto/__init__.py                  3      0   100%
    csst_proto/demo.py                      8      3    62%
    csst_proto/flip_image.py               13      0   100%
    csst_proto/top_level_interface.py       3      0   100%
    tests/test_demos.py                     5      0   100%
    tests/test_flip_image.py                8      0   100%
    -------------------------------------------------------
    TOTAL                                  40      3    92%

This means the overall unit test coverage is 92%.
You can also find a detailed coverage report in ``html`` format in the attached ``htmlcov.zip``.


Caveats
-------
The Numpy style docstring check is only for the packages listed below. 

- csst_proto
- csst_cicd
- csst_ms_mbi_instrument
- csst_ms_mbi_distortion
- csst_ms_mbi_position
- csst_ms_mbi_flux
- csst_ms_mbi_photometry

We welcome other packages participate in.