Contributing

We welcome contributions to sim-tools.

Feature requests and bug reports

Before opening an issue, please search existing issues to avoid duplicates. If an issue exists, you can add a comment with additional details and/or upvote (👍) the issue. If there is not an existing issue, please open one and provide as much detail as possible.

Code contributions

You are welcome to make contributions to the code. To do so please:

  1. Fork the repository.
  2. Create a branch for your feature or fix.
  3. Make changes then commit them with clear, descriptive messages.
  4. Open a pull request against our repository. Describe your changes and reference any related GitHub issues.

Environment

You can install development dependencies from pyproject.toml using your preferred environment manager. For example:

conda create -n sim_tools python=3.12
conda activate sim_tools
pip install -e .
pip install --group dev

A pinned conda environment is also provided:

conda env create -f binder/environment.yml
conda activate sim_tools

Tests

pytest

Documentation

The documentation is created with great-docs.

Generate and render the site:

great-docs build

Open in your browser:

great-docs preview

Style

We use Ruff to the lint Python files, with the configuration defined in pyproject.toml. To lint and format the repository, run:

ruff format
ruff check --fix .

To lint Python code in the Quarto files, we use lintquarto, with configuration likewise in pyproject.toml. To run:

lintquarto

NumPy style docstrings are used.

Spellcheck

There is a spellcheck GitHub action.

If you want to run the spellcheck locally, you need to install vale. On Linux:

sudo apt update
sudo apt install snapd
sudo snap install vale

With vale installed, run:

vale sync
vale .

Contributors

If your name or contributions are missing from the README, or if you contributed in ways not captured by the current role emojis, please create an issue and use:

@all-contributors please add @githubuser for ...

Then list appropriate contribution types from allcontributors.org/docs/en/emoji-key (e.g., code, review, doc, content, bug, ideas, infra).

Alternatively, you can update it from the command line. This may be preferable, as the bot will create GitHub issues that email people when they are added.

You’ll need to install the All-Contributors CLI tool:

npm i -D all-contributors-cli

You can then run the following and select/enter relevant information when prompted:

npx all-contributors

If you want to remove specific contributions or people, edit the .all-contributorsrc file then run the following to regenerate the table in README.md. (Don’t edit README.md, as it is just generated based on .all-contributorsrc).

npx all-contributors generate