CodeEntropy is open-source, and we welcome contributions from the wider community to help improve and extend its functionality. This guide walks you through setting up a development environment, running tests, contributing code, and understanding the continuous integration workflows.
Create a development environment using either venv or Conda.
Using venv:
python -m venv codeentropy-dev source codeentropy-dev/bin/activate # Linux/macOS codeentropy-dev\Scripts\activate # Windows
Using Conda:
conda create -n codeentropy-dev python=3.14 conda activate codeentropy-dev
Clone the repository:
git clone https://github.com/CCPBioSim/CodeEntropy.git cd CodeEntropy
Install development dependencies:
pip install -e ".[testing,docs,pre-commit]"
CodeEntropy uses pytest with separate unit and regression suites.
Run all tests:
pytest
Run only unit tests:
pytest tests/unit
Run regression tests:
pytest tests/regression
Run regression tests excluding slow systems:
pytest tests/regression -m "not slow"
Run slow regression tests:
pytest tests/regression --run-slow
Run tests with coverage:
pytest --cov CodeEntropy --cov-report=term-missing
Run a specific test:
pytest tests/unit/.../test_file.py::test_function
Regression baselines should only be updated when a change intentionally alters the expected numerical output of CodeEntropy. Do not update baselines simply because a regression test fails.
Before updating baselines, confirm that:
- The code change is intentional and understood.
- The new output has been reviewed.
- The regression difference is expected.
- The pull request explains why the baselines changed.
For local updates, run:
pytest tests/regression --update-baselines
For pull requests, baselines can also be updated using the GitHub Actions workflow Update Regression Baselines.
To use it:
- Push your changes to your PR branch.
- Open the Actions tab on GitHub.
- Select Update Regression Baselines.
- Click Run workflow.
- Select your PR branch.
- Run the workflow.
The workflow runs the regression tests with --update-baselines and commits
any changed baseline files back to the selected branch.
Only use this workflow when the baseline changes are intentional. If a regression test fails unexpectedly, investigate the failure instead of updating the baseline.
Regression datasets are automatically downloaded from the CCPBioSim filestore
and cached locally in .testdata/ when tests are run.
No manual setup is required.
The test configuration files reference datasets using the ${TESTDATA}
placeholder, which is expanded automatically during test execution.
We use pre-commit hooks to maintain code quality and consistent style.
Enable hooks:
pre-commit install
Our tooling stack:
- Linting and formatting via
ruff - Basic repository checks via
pre-commit-hooks
Ruff performs:
- Code formatting
- Import sorting
- Static analysis
- Style enforcement
Run checks manually:
pre-commit run --all-files
Skip checks for a commit (not recommended):
git commit -n
Note
Pull requests must pass all pre-commit checks before being merged.
CodeEntropy uses GitHub Actions with multiple workflows to ensure stability across platforms and Python versions.
Pull Request checks include:
- Unit tests on Linux, macOS, and Windows
- Python versions 3.12-3.14
- Quick regression tests
- Documentation build
- Pre-commit validation
Daily workflow:
- Runs automated test validation
Weekly workflows:
- Full regression suite including slow tests
- Documentation build across all Python versions
- Dependency floor checks (see :ref:`dependency-policy`)
CI also caches regression datasets to improve performance.
Runtime dependencies in pyproject.toml are declared as ranges. The lower
bound (floor) is the oldest release CodeEntropy is known to work with, so that it
stays installable alongside other scientific packages. Floors are only raised
when the code needs a newer release. Upper bounds are widened by Renovate.
The unit job in the pull request workflow and the weekly dependency-floors.yaml
workflow check this. They check that the lowest allowed versions resolve to
installable wheels on each platform and Python version, and that the unit tests
pass with them installed.
Run the same checks locally with uv:
uv pip install --resolution lowest-direct -e ".[testing]" python -m pytest tests/unit
Build documentation locally:
cd docs make html
The generated HTML files will be in docs/build/html/.
Open index.html in your browser to preview.
Documentation sources are located in:
docs/user_guide/docs/developer_guide/
If you would like to contribute to CodeEntropy, please refer to the Contributing Guidelines.
If you encounter bugs or want to request features:
- Open an issue on GitHub.
- Provide a clear description and input files if applicable.
Never commit directly to
main.Create a branch named after the issue:
git checkout -b 123-feature-description
- Make your changes in a branch.
- Ensure tests and pre-commit checks pass.
- Submit a pull request.
- At least one core developer will review it.
- Include updated documentation and tests for new code.
Full developer setup:
git clone https://github.com/CCPBioSim/CodeEntropy.git cd CodeEntropy pip install -e ".[testing,docs,pre-commit]" pre-commit install pytest