Contributing

We welcome contributions. This page covers how to set up a development environment, run tests, lint code, and build the documentation.

Setting up for development

Clone the repository and install in editable mode with all optional dependency groups:

git clone https://github.com/CCPBioSim/biosimdb-interface.git
cd biosimdb-interface
conda create -n biosimdb-interface-dev python=3.12
conda activate biosimdb-interface-dev
pip install -e ".[testing,docs,pre-commit]"

Running the tests

Tests use pytest and are located in the tests/ directory:

pytest

To see a coverage report:

pytest --cov=biosimdb_interface --cov-report=term-missing

Linting and formatting

The project uses ruff for linting and formatting:

ruff check .
ruff format .

Pre-commit hooks

Pre-commit hooks run ruff, pyupgrade, and several file-hygiene checks automatically before each commit. To install them:

pre-commit install

To run all hooks manually across the whole codebase:

pre-commit run --all-files

Hook versions are pinned in .pre-commit-config.yaml at the repository root.

Continuous integration

CI runs automatically on every push to main via GitHub Actions (.github/workflows/ci.yaml). The following jobs must pass before merging:

  • Lint — ruff check and ruff format --check

  • Tests — pytest on Python 3.12 and 3.13

  • Docs — Sphinx HTML build with warnings treated as errors

  • Pre-commit — all pre-commit hooks across all files

Building the documentation

Build the HTML docs locally from the docs/ directory:

cd docs
make html

The built docs will be in docs/build/html/. Open docs/build/html/index.html in a browser to preview them.

To clean the build and rebuild from scratch:

make clean html

The documentation is hosted on ReadTheDocs and is rebuilt automatically on each push to main. The ReadTheDocs configuration is in .readthedocs.yaml at the repository root.

Submitting changes

  1. Create a branch from main for your change.

  2. Make your changes and add tests where appropriate.

  3. Ensure all CI jobs pass locally: pytest, ruff check ., and pre-commit run --all-files.

  4. Open a pull request against main with a clear description of the change.