Contributing¶
We very much welcome contributions. Before starting work on a big PR it is always good to check if there is interest and or how this would fit with existing development activities.
Installation¶
In order to contribute to mmu
you have to install the package from source.
The package can be installed for local development with:
git clone https://github.com/RUrlus/ModelMetricUncertainty.git
cd modelmetricuncertainty
pip install -e .
Note that the C++ extension is (re-)compiled during local installation.
If you don’t have a compiler installed and are not working on the extension the best solution is to download the wheels from PyPi.
Unzip the version for you system and Python version and copy it to mmu/lib/
.
Debug build¶
By default we create a CMake Release
build, if you need to create a
Debug
build use:
CMAKE_ARGS="CMAKE_BUILD_TYPE=Debug" pip install -e .
Manual compilation¶
If you only want to recompile the extension you can do so with:
cmake -S . -B mbuild \
-DCMAKE_BUILD_TYPE=Release \
-DMMU_DEV_MODE=ON \
-DMMU_ENABLE_INTERNAL_TESTS=ON \
-Dpybind11_DIR=$(python3 -c 'import pybind11; print(pybind11.get_cmake_dir())') \
-DPython3_EXECUTABLE=$(python3 -c 'import sys; print(sys.executable)')
cmake --build mbuild --target install --config Release -j 4
This requires that you have the following pip packages installed:
cmake
scikit-build
pybind11
numpy
Extension specific tests¶
The library contains unit tests for the internals of the C++ extension.
For example, unit tests of the functions in include/mmu/numpy.hpp
.
These are specific tests that have their own extension which can be build using:
CMAKE_ARGS="-DMMU_ENABLE_INTERNAL_TESTS=ON" pip install -e .
This will place _mmu_core_tests
extension in mmu/lib
.
You can run the tests with
pytest tests/internal
Testing¶
MMU’s test suite can than be run with:
cd tests
pytest
This will run both the API tests and the internal tests. In order to run the internal tests you need to have compiled the test extension. Please see Extension specific tests for details.
If you have not build the extension tests, you can test the API tests with:
cd tests
pytest api
CICD¶
There are a number of Github Actions that are triggered on pull requests:
Windows - Python 3.7 - 3.10
Linux - Python 3.7 - 3.10
MacOS - Python 3.7 - 3.10
Valgrind
Asan
A lighter Build & Test pipeline is run on each push, this should help you check compatibility across the platforms. Valgrind and Asan are only relevant if you have touched the C++ extension and can be largely ignored otherwise.
Conventions¶
We have a few conventions that we would like you to adhere to.
Pull requests¶
Please open pull-requests to the stable
branch.
We use a linear merge strategy.
Please make sure that your branch/fork contains the latest state of stable
, otherwise the merge cannot be completed.
Commits¶
Please prepend your commit messages with:
ENH:
the commit introduces new functionalityCHG:
the commit changes existing functionalityFIX:
the commit fixes incorrect behaviour of existing functionalitySTY:
the commit improves the readability of the code but not the functioning of the codeDOC:
the commit only relates to the documentationTST:
the commit only relates to the testsBLD:
changes related to setup files or build instructions (BLD: [CPP] ...
)CICD:
the commit only relates to the CI/CD templates
Additionally use [CPP]
after the prefix when your commit touches C++ code or build instructions.
For example, FIX: [CPP] Fix stride offset in foo
.
Clang format¶
If your contribution touches C++ code, please run clang-format.
The format is specified by the .clang-format
file at the root of the repo, it should be picked up automatically.
For example:
clang-format -i include/mmu/core/*.hpp
Building documentation¶
You can build documentation like this:
cd docs
pip install -r requirements.txt
sphinx-build source build
open build/index.html