Contributing

Thanks for helping us build Rubicon!

Cloning the Repository

Make a fork of the rubicon-ml repo and clone the fork:

git clone https://github.com/<your-github-username>/rubicon-ml
cd rubicon-ml

You may want to add https://github.com/capitalone/rubicon-ml/ as an upstream remote:

git remote add upstream https://github.com/capitalone/rubicon-ml

Creating a Development Environment

We have a conda environment YAML file with all the necessary dependencies at the root of the repository.

conda env create -f environment.yml

Building rubicon_ml

After you’ve cloned the repository, use pip to install rubicon_ml locally:

python -m pip install -e .[all]

Style

rubicon_ml uses black for formatting, flake8 for linting, and isort for standardizing imports. If you installed rubicon_ml using conda, these tools will already be in your environment.

black rubicon_ml tests
flake8 rubicon_ml tests
isort -rc rubicon_ml tests

Install and configure pre-commit to automatically run each of these tools before committing. Once installed, run pre-commit install to set up the git hooks.

Running Tests

rubicon_ml uses pytest for testing. Run the tests from the root rubicon_ml directory as follows:

python -m pytest

Documentation

We follow numpydoc formatting for our docstrings. This lets us use sphinx to automatically generate a library reference.

We also use nbsphinx to render our example notebooks directly from our repo. To reduce the complexity of our documentation builds, we only commit executed notebooks to the repo so nbsphinx doesn’t have to spend time executing them itself.

To build the documentation locally, use the environment YAML file in the docs directory to create a new conda environment with all necessary tools:

cd docs/
conda env create -f docs-environment.yml

Activate the new environment, install a local copy of rubicon_ml, and use the make html command from the docs directory to build the documentation locally.

conda activate rubicon-ml-docs
pip install --no-deps -e ../
make html

The newly built documentation can be opened in a browser.

open ./build/html/index.html

Never commit built documentation code directly, only the source. Our .gitignore should handle keeping built docs out of the repo, and our CICD handles deploying newly committed documentation.