Contributing

To contribute to the library, you need to clone the repo using git:

git clone https://github.com/PLAID-lib/plaid.git

4.1 Development dependencies

To configure an environment manually, you can follow the dependencies listed in environment.yml, or generate it using conda:

conda env create -f environment.yml

Then, to install the library:

pip install -e .

Note

The development dependency Muscat=2.5.0 is available on conda-forge but not on PyPi. A a consequence, using a conda environment is the only way to run tests and examples, and compile the documentation.

4.2 Tests and examples

To check the installation, you can run the unit test suite:

pytest tests

To test further and learn about simple use cases, you can run and explore the examples:

cd examples
bash run_examples.sh  # [unix]
run_examples.bat      # [win]

4.3 Documentation

To compile locally the documentation, you can run:

cd docs
make html

Various notebooks are executed during compilation. The documentation can then be explored in docs/_build/html.

4.4 Formatting and linting with Ruff

We use Ruff for linting and formatting.

The configuration is defined in ruff.toml, and some folders like docs/ and examples/ are excluded from checks.

You can run Ruff manually as follows:

ruff --config ruff.toml check . --fix      # auto-fix linting issues
ruff --config ruff.toml format .           # auto-format code

4.5 Setting up pre-commit

Pre-commit is configured to run the following hooks:

  • Ruff check

  • Ruff format

  • Pytest

The selected hooks are defined in the .pre-commit-config.yaml file.

To run all hooks manually on the full codebase:

pre-commit run --all-files

You can also run (once):

pre-commit install

4.6 How to contribute

Before contributing, please review our guidelines and backward-compatibility policy.

  • Coding standards: PEP 8, PEP 257; snake_case, 80-char lines; one class per file preferred.

  • Rules: simple/flexible API, local/unit tests, examples preferred, 100% coverage.

  • Reporting issues: include steps, expected behavior, PLAID version, logs.

  • Feature requests: describe the feature and use cases.

  • Contributor License Agreement (CLA): see details below.

Backward compatibility (API and disk format): see policy in this page and details in issues #97 and #14.

CGNS resources: http://cgns.github.io/

Contributor License Agreement (CLA)

By contributing, you agree to the CLA terms summarized below (full text previously in Contributing page):

  • Perpetual, worldwide, non-exclusive licenses for copyright and patent.

  • You represent rights to contribute, originality, and disclose third-party restrictions.

  • Contributions are provided “AS IS” without warranties.

Pre-commit is configured to run the following hooks:

  • Ruff check

  • Ruff format

  • Pytest

The selected hooks are defined in the .pre-commit-config.yaml file.

To run all hooks manually on the full codebase:

pre-commit run --all-files

You can also run (once):

pre-commit install