Contributor Guide

Attention

This project is still in an early phase of development.

The python API is not yet stable, and some aspects of the schema for the blueprint and workplan will likely evolve. Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility. We expect to reach a more stable version in 2026.

Contributor Guide#

Conda environment#

Install one of the following conda environments, depending on whether you are working on a supported HPC system (environment management by Linux Environment Modules) or a generic machine like a laptop (environment managed by conda):

conda env create -f ci/environment_hpc.yml  # conda environment for supported HPC system
# conda env create -f ci/environment.yml  # conda environment for generic machine

Activate the conda environment:

conda activate cstar_env

Install C-Star in the same environment:

pip install -e ".[dev,docs]"

This conda environment is useful for any of the following steps:

  1. Running the example notebooks

  2. Contributing code and running the testing suite

  3. Building the documentation locally

Running the tests#

You can check the functionality of the C-Star code by running the test suite:

conda activate cstar_env
cd C-Star
pytest

Contributing code#

If you have written new code, you can run the tests as described in the previous step. You will likely have to iterate here several times until all tests pass. The next step is to make sure that the code is formatted properly. Activate the environment (created above) and run all linters as follows:

conda activate cstar_env
pre-commit run --all-files

Some things will automatically be reformatted, others may need manual fixes. Follow the instructions in the terminal until all checks pass. Once you got everything to pass, you can stage and commit your changes and push them to the remote github repository.

Adding Tests for New Code#

Please ensure that your additions are covered by appropriate tests to maintain code quality and reliability. Follow these guidelines:

  • What to Test:

    • Test any new properties, functions, and methods in API using unit tests (cstar/tests/unit_tests)

    • If adding entirely new functionality or complex multi-step processes, add appropriate integration tests (cstar/tests/integration_tests)

  • Best Practices:

    • Focus on areas with multiple options or combinations of behavior, using parameterizations or distinct tests to cover every option

    • Group related tests (e.g. testing different outcomes of the same method under different conditions) in test classes

    • Consider edge cases, such as unexpected input or failure scenarios.

    • Write tests that help identify specific issues quickly (e.g., as if a random return statement was added in your code).

  • Using Fixtures:

    • Use fixtures to set up any expensive operations

    • Ensure the fixture logic is itself independently tested.

  • Useful ``pytest`` Tips:

    • Run specific tests by specifying file paths, directories, or test names:

      pytest path/to/test_file.py

    • Use pytest.mark for categorizing tests (e.g., network-related tests).

Building the documentation locally#

Activate the environment:

conda activate cstar_env

Then navigate to the docs folder and build the docs via:

cd docs
make fresh
make html

You can now open docs/_build/html/index.html in a web browser via:

open _build/html/index.html