Contributing
Code Style
Use clear naming for variables, objects, etc. rather than mathematical short hand (e.g. measurement_matrix rather than H)
Use standard Python errors and warnings
At least one release cycle with deprecated warnings before removing/changing interface (excluding alpha/beta releases)
No strict typing, exploit duck typing
Each object has one role, modular sub-components
Embrace abstract base classes
Allowing inhomogeneity at the lower levels of the inheritance hierarchy
New components should subclass from base types for each (e.g. Updater) where possible
Use of Python abstract classes to have familiar behaviour to existing Python objects
Avoid strict encapsulation (use of __methods) but use non-strict encapsulation where needed (_method).
All code should follow PEP 8. Flake8 can be used to check for issues. If necessary, in-line ignores can be added.
Documentation
In Stone Soup, NumPy Doc style documentation is used, with documentation generated with Sphinx. It must be provided for all public interfaces, and should also be provided for private interfaces.
Where applicable, documentation should include reference to the paper and mathematical description. For new functionality provide Sphinx-Gallery example which demonstrate use case.
To build the documentation, use the following:
sphinx-build -W docs/source docs/build
You should find index.html file present in the docs/build/ directory.
The pages built by Sphinx-Gallery will be cached to speed up building process, but can be cleared to ensure that all examples build, using the following command:
git clean -xf docs/source/auto_*
Tests
PyTest is used for testing in Stone Soup. As much effort should be put into developing tests as the code. Tests should be provide to test functionality and also ensuring exceptions are raised or managed appropriately. Tests can be run (including Flake8) with the following:
pytest --flake8 stonesoup
Code coverage should also be checked, aiming for 100% coverage (noting coverage alone is not a measure of test quality), using Coverage.py. This can be run with the following (along with Flake8):
pytest --cov=stonesoup --cov-report=html --flake8 stonesoup
This will produce a report in htmlcov directory.
License
Any contributions submitted are to be under the MIT or similar non-copyleft license. MIT License will be assumed to be unless otherwise stated on the pull request.
External Dependencies
Use standard library and existing well maintained external libraries where possible. New external libraries should be licensed permissive (e.g MIT) or weak copyleft (e.g. LGPL)
Pull Requests
Submissions should be done via Pull Requests on the Stone Soup GitHub repo. Currently we are using GitHub Flow as our approach to development. Once a pull request has been opened, CircleCI will run tests and build documentation, and Codecov will check code coverage. The results of these status checks will be available on the PR, and any failures should be addressed.