Developer Guide

Thanks for helping us build rubicon-ml! This guide will help you get set up to start contributing to the project.

Clone 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

Create a Development Environment

We recommended setting up a development environment with `uv https://github.com/astral-sh/uv`_:

uv venv --python 3.13

After you’ve cloned the repository and created a virtual environment, use uv to install rubicon-ml and its developer dependencies locally:

uv sync --extra dev

All future uv invocations from the rubicon-ml repository will leverage the new environment.

Run the Tests

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

uv run pytest

Build the 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 provided Makefile:

cd docs/
uv run make clean html

The newly built documentation can be opened in a browser locally.

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.

Check the Style

rubicon_ml uses ruff for linting and formatting. To check and update the code style, run:

uv run ruff check --fix
uv run ruff format

Install and configure pre-commit to automatically run each of these tools before committing. Once installed, run uv run pre-commit install to set up the git hooks and uv run pre-commit run --all-files to run the checks. To skip these checks, run git commit --no-verify.

Cut a Release

To release a new version of rubicon-ml, follow these steps to open a release PR. Then rubicon-ml’s CICD will handle the rest.

First, checkout a new release branch following the release/vx.y.z naming convention, where x.y.z is the version to be released. Then, update the project’s version throughout the codebase with bumpver:

uv run bumpver update --set-version x.y.z

Other valid options are --patch, --minor and --major. These will update the version accordingly, following the MAJOR.MINOR.PATCH pattern.

Next, commit and push your changes. Then open a PR using the release pull request template. Follow the instructions in the template to populate the PR body. This will become the contents of the release notes for the new version, so make sure it is accurate. Once the PR is approved and merged, the CICD will automatically publish the new version of the package and create a new release on GitHub with the appropriate tag.