Contributing

OpenSoil welcomes provider research, canonical vocabulary review, adapter code, fixtures that can be redistributed, documentation corrections, tests, and developer examples.

Local setup

git clone https://github.com/jdj333/OpenSoil.git
cd OpenSoil
python3 -m venv .venv
.venv/bin/pip install -r api/requirements-dev.txt
.venv/bin/pip install -r docs-site/requirements.txt

cd api
../.venv/bin/ruff check app tests
../.venv/bin/ruff format --check app tests
../.venv/bin/mypy app
../.venv/bin/pytest

cd ../docs-site
../.venv/bin/mkdocs build --strict

Run the API locally:

cd api
../.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --port 8100

Repository structure

api/app/                 FastAPI application, models, registries, adapters
api/tests/               routine mocked tests and opt-in integration test
docs-site/docs/          Markdown documentation
deploy/nginx/            source-controlled virtual hosts
deploy/systemd/          hardened service units
sites/api/               static API landing pages
sites/docs/              generated MkDocs release output

Standards

Python must pass Ruff, formatting, MyPy, pytest, and dependency audit. Documentation builds in MkDocs strict mode and must not overstate provider support or licensing. Keep routes provider-agnostic, preserve original data, and add no scientific conversion without a reviewed decision record.

Pull requests

Describe the problem, provider/product version, scientific assumptions, licensing evidence, test strategy, public-contract changes, and rollback impact. Include fixture provenance and prove routine tests do not depend on a live external service. Update OpenAPI-linked explanations and the decision log when behavior changes.