Contributing to dynamiqs
We warmly welcome all contributions. If you're a junior developer or physicist, you can start with a small utility function, and move on to bigger problems as you discover the library's internals. If you're more experienced and want to implement more advanced features, don't hesitate to get in touch to discuss what would suit you.
To contribute efficiently, a few guidelines are compiled below.
Requirements
The project was written using Python 3.9+, you must have a compatible version of Python (i.e. >= 3.9) installed on your computer.
Setup
Clone the repository and dive in:
git clone git@github.com:dynamiqs/dynamiqs.git
cd dynamiqs
We strongly recommend that you create a virtual environment to install the project dependencies. You can then install the library (in editable mode) with all its dependencies:
pip install -e .
You also need to install the developer dependencies:
pip install -e ".[dev]"
Code style
This project follows PEP8 and uses automatic formatting and linting tools to ensure that the code is compliant.
The maximum line length is 88, we recommend that you set this limit in your IDE.
Workflow
Before submitting a pull request (run all tasks)
Run all tasks before each commit:
task all
Run some tasks automatically before each commit
Alternatively, you can use pre-commit
to automatically run the cleaning tasks (ruff + codespell) before each commit:
pip install pre-commit
pre-commit install
Build the documentation
The documentation is built using MkDocs and the Material for MkDocs theme. MkDocs generates a static website based on the markdown files in the docs/
directory.
To preview the changes to the documentation as you edit the docstrings or the markdown files in docs/
, we recommend starting a live preview server, which will automatically rebuild the website upon modifications:
task docserve
Open http://localhost:8000/ in your web browser to preview the documentation website.
You can build the static documentation website locally with:
task docbuild
This will create a site/
directory with the contents of the documentation website. You can then simply open site/index.html
in your web browser to view the documentation website.
Run specific tasks
You can also execute tasks individually:
> task --list
lint lint the code (ruff)
format auto-format the code (ruff)
codespell check for misspellings (codespell)
clean clean the code (ruff + codespell)
test run the unit tests suite (pytest)
doctest-code check code docstrings examples (doctest)
doctest-docs check documentation examples (doctest)
doctest check all examples (doctest)
docbuild build the documentation website
docserve preview documentation website with hot-reloading
all run all tasks before a commit (ruff + codespell + pytest + doctest)
ci run all the CI checks