Contributing

Thank you for your interest in contributing! 🤗

This file covers:

• 🐞 Workflow for bug reports, feature requests and documentation improvements
• 🚀 Workflow for code contributions (bug fixes, enhancements)
• 🛠️ Development and testing
• 📦 Updating the package
• 🤝 Code of conduct

🐞 Workflow for bug reports, feature requests and documentation improvements

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.

• For feature requests or documentation improvements, please describe your suggestion clearly.
• For bugs, include:
  • Steps to reproduce.
  • Expected and actual behaviour.
  • Environment details (operating system, python version, dependencies).
  • Relevant files (e.g. problematic .qmd files).

Handling bug reports (for maintainers):

• Confirm reproducibility by following the reported steps.
• Label the issue appropriately (e.g. bug).
• Request additional information if necessary.
• Link related issues or pull requests.
• Once resolved, close the issue with a brief summary of the fix.

🚀 Workflow for code contributions (bug fixes, enhancements)

1. Fork the repository and clone your fork.

2. Create a new branch for your feature or fix:

git checkout -b my-feature

3. Make your changes and commit them with clear, descriptive messages using the conventional commits standard.

4. Push your branch to your fork:

git push origin my-feature

5. Open a pull request against the main branch. Describe your changes and reference any related issues.

🛠️ Development and testing

Dependencies

Set up the Python environment using conda (recommended):

conda env create --file environment.yaml
conda activate

There is also a requirements.txt file which can be used to set up the environment with virtualenv, but this won't fetch a specific version of Python - so please note the version listed in environment.yaml.

Docstrings

We follow the numpydoc style for docstrings.

Tests

Run all tests (with coverage):

pytest --cov

Run tests in parallel:

pytest -n auto

Run an individual test file:

pytest tests/testfile.py

Run a specific test:

pytest tests/testfile.py::testname

Linting

Lint all files:

bash lint.sh

Lint a specific .py file:

pylint simulation/model.py

Lint a specific .ipynb file:

nbqa pylint notebooks/analysis.ipynb

📦 Updating the package

If you are a maintainer and need to publish a new release:

1. Update the CHANGELOG.md.

2. Update the version number in simulation/__init__.py and CITATION.cff, and update the date in CITATION.cff.

3. Create a release on GitHub, which will automatically archive to Zenodo.

🤝 Code of conduct

Please be respectful and considerate. See the code of conduct for details.