Contributing#

1. Install Development Build#

From a command line, execute the following commands:

git clone https://github.com/MSDLLCpapers/obsidian
cd obsidian
git checkout main
pip install -e .[dev]

2. Style#

Linting is enforced with ruff based on configurations in pyproject.toml.

We recommend using VS Code with the ruff extension to automatically aid adherence to code style.

All function and method signatures should contain Python 3.10+ type hints.

Each module, class, method, and function should have a docstring. We use Google style docstrings.

We prefer that class docstrings be written under class definition instead of __init__.

3. Documentation#

For documentation building, obsidian uses sphinx with autodoc and autosummary

In order to rebuild documentation, first be sure to have installed the documentation build

pip install -e .[docs]

Then perform the following steps:

cd docs
make clean
make html

Documentation HTML output will be built in docs/build with the homepage at docs/build/html/index.html.

Guidance Documentation#

New or major changes to subpackages or modules (e.g. acquisition, surrogate, optimizer.BO_optimizer, objectives.scalarize) should be covered by informative documentation detailing API usage in Wiki articles.

Major features or configurations should be documented as examples in Tutorial notebooks.

4. Testing#

For testing, obsidian uses pytest.

From the repository root, run the test suite with:

pytest obsidian/tests

Test discovery and warning filters are configured in pytest.ini, and coverage is configured in .coveragerc. To generate a coverage report, pass the coverage flags explicitly:

pytest obsidian/tests --cov=obsidian --cov-report=html

We have also enabled fast testing with majority coverage and flagged slow tests that can be avoided until major pull requests.

pytest obsidian/tests -m fast
pytest obsidian/tests -m "not slow"

All new features should be fully covered by newly written pytests.

5. License#

By contributing to obsidian, you agree that your contributions will be licensed under the package LICENSE.