Contributions to ProbNum are very welcome. Before getting started make sure to read the following guidelines.
All contributions to ProbNum should be made via pull requests (PR) to the master branch on GitHub. Some suggestions for a good PR are:
- implements or fixes one functionality;
- includes tests and appropriate documentation; and
- makes minimal changes to the interface and core codebase.
Begin by forking the repository on GitHub and cloning your fork to a local machine. Next, create a new branch in your forked repository describing the feature you would like to implement. You can now get started writing code in your new branch. Make sure to keep the following best practices regarding code quality in mind.
Code quality is an essential component in a collaborative open-source project.
- Make sure to observe good coding practice.
- Keep dependencies to a minimum.
- All code should be covered by tests within the unittest framework.
- Documentation of code is essential. ProbNum uses the NumPy docstring format.
- Code should be formatted with *Black* and follow the internal style guide. For more thorough Python code style guides we refer to PEP 8 and to the *Black* code style.
For all of the above the existing ProbNum code is a good initial reference point.
Probnum uses tox in its continuous integration (CI)
pipeline to run tests and to build documentation. Under the hood, tox builds virtual environments following the
./tox.ini in order to run tests across multiple python versions, while making sure that all the
necessary dependencies are installed. Using tox unifies the local development process with CI, such that local test
results should match the outcomes of Travis’s builds more closely. This ensures that your pull request can be merged
seamlessly into ProbNum’s codebase.
Install tox from the Python Package Index (PyPI) via
pip install -U tox
Once tox and the required external tools below are installed, you can run tests and build the documentation locally by simply calling
Note, to reduce runtime tox caches and reuses the virtual environment it creates the first time you run the command. If
you are frequently switching between branches or adjusting the build configuration make sure to force recreation of the
virtual environment via
tox -r, if you experience unexpected tox failures.
Word of caution:
tox runs all environments as specified in
tox.ini, thus potentially running tests across many different
Python versions. To run the full test suite make sure that you have all specified Python versions installed.
Alternatively, you can run a single specific environment through
tox -e <env>, e.g.
tox -e py36 to run tests with
Python 3.6 or
tox -e docs to just build the documentation.
We use unittest for testing and aim to cover as much code with tests as possible. Make sure to always add tests for newly implemented code. To run the test suite on your machine you have multiple options:
Full test suite with tox: Run the full suite across different Python versions with
Single environment with tox: Run tests for a single Python environment, e.g. for Python 3.6
tox -e py36
pytest: Run tests directly in your local environment by calling
Code coverage of the tests is reported via codecov.
You can build the documentation locally via
tox -e docs
This creates a static web page under
./docs/_build/html/ which you can view in your browser by opening
Alternatively, if you want to build the docs in your current environment you can manually execute
cd docs make clean make html
ProbNum uses Travis CI for continuous integration.
For every pull request and every commit Travis builds the project and runs the test suite (through
tox), to make sure
that no breaking changes are introduced by mistake. Travis also automatically triggers a
build of ProbNum’s documentation. Changes to Travis can be made through the
.travis.yml file, as well as through
tox.ini since Travis relies on
tox for both testing and building the documentation. ProbNum also uses
GitHub Actions to verify that all pushes and pull requests are compliant with the
*Black* code style.