Contributing - OEDI-SI

Contributions are welcome across the OEDI-SI project. This page covers where to contribute, how to set up a development environment, and the checks your change should pass.

Where to contribute¶

Repository	What lives there
`oedisi`	The framework, `oedisi.types` data models, and the `oedisi` CLI.
`oedisi-components`	Reusable HELICS components (feeders, estimators, recorders, …).
`oedisi-frontend-app`	The web UI and its FastAPI backend.

Development setup¶

Clone the repository you want to work on and install it with its development dependencies:

git clone https://github.com/openEDI/oedisi.git
cd oedisi
pip install -e ".[test]"      # framework + dev tools (pytest, ruff, black, mypy, …)
pre-commit install            # run formatters/linters on each commit

The frontend app uses npm install plus uv --directory server sync; see the install guide.

Run the checks¶

Before opening a pull request, make sure the tests and quality gates pass:

pytest                 # unit + integration tests
ruff check .           # lint
black --check .        # formatting
mypy src               # type checking

The oedisi repository also has an end-to-end script at tests/runtests.sh.

Contributing a component or algorithm¶

New simulation blocks are the most common contribution:

Follow Build a component for the required files, the component_definition.json contract, and the HELICS federate pattern.
The algorithm interface (static/dynamic inputs, publications, endpoints) is described in ALGORITHM_DEVELOPERS.md.
Register it so it appears in the UI — see Register it in the UI.

Contributing to the docs¶

These docs are a MyST (Jupyter Book) project in docs/.

Edit the Markdown and notebook files directly, then preview with myst start.
The CLI, API, data-type, and component-catalog pages are generated — don’t edit them by hand. After changing the CLI or the oedisi API, regenerate them:
```
python docs/tools/generate.py
```
Build the static site with myst build --html (see Deployment).

Pull requests & issues¶

Open pull requests against the main branch of the relevant repository.
Keep changes focused, and include tests where it makes sense.
Report bugs and request features on the issue tracker, e.g. https://github.com/openEDI/oedisi/issues.

License¶

By contributing, you agree that your contributions are licensed under the project’s BSD 3-Clause License (see Cite & license).