Contributions are welcome, and they are greatly appreciated, every little bit helps.

You can begin contributing to mitiq code by raising an issue, reporting a bug or proposing a new feature request, using the labels to organize it. Please use mitiq.about() to document your dependencies and working environment.

You can open a pull request by pushing changes from a local branch, explaining the bug fix or new feature.

git is a language that helps keeping track of the changes made. Have a look at these guidelines for getting started with git workflow. Use short and explanatory comments to document the changes with frequent commits.

You can fork mitiq from the github repository, so that your changes are applied with respect to the current master branch. Use the Fork button, and then use git from the command line to clone your fork of the repository locally on your machine.

(base) git clone https://github.com/your_github_username/mitiq.git

You can also use SSH instead of a HTTPS protocol.

It is best to set up a clean environment with anaconda, to keep track of all installed applications.

(base) conda create -n myenv python=3

accept the configuration ([y]) and switch to the environment

(base) conda activate myenv
(myenv) conda install pip

Once you will finish the modifications, you can deactivate the environment with

(myenv) conda deactivate myenv

In order to install all the libraries useful for contributing to the development of the library, from your local clone of the fork, run

(myenv) pip install -e .
(myenv) pip install -r requirements.txt

If you add new features to a function or class, it is required to add tests for such object. Mitiq uses a nested structure for packaging tests in directories named tests at the same level of each module.

Follow these instructions for contributing to the documentation which include guidelines about updating the API-doc list of modules and writing examples in the users guide.

You can check that tests run with pytest. The Makefile contains some commands for running different collections of tests for the repository.

To run just the tests contained in mitiq/tests and mitiq/benchmarks/tests run

(myenv) make test

To run the tests for the pyQuil and Qiskit plugins (which of course require for pyQuil and Qiskit to be installed) run

(myenv) make test

NOTE: For the pyQuil tests to run, you will need to have QVM & quilc servers running in the background. The easiest way to do this is with Docker via

docker run --rm -idt -p 5000:5000 rigetti/qvm -S
docker run --rm -idt -p 5555:5555 rigetti/quilc -R

You can also check that all tests run also in the documentation examples and docstrings with

(myenv) make docs

If you add new /tests directories, you will need to update the Makefile so that they will be included as part of continuous integration.

Mitiq code is developed according the best practices of Python development.

• Please get familiar with PEP 8 (code) and PEP 257 (docstrings) guidelines.
• Use annotations for type hints in the objects' signature.
• Write google-style docstrings.

We use Black and flake8 to automatically lint the code and enforce style requirements as part of the CI pipeline. You can run these style tests yourself locally by running make check-style (to check for violations of the flake8 rules) and make check-format (to see if black would reformat the code) in the top-level directory of the repository. If you aren't presented with any errors, then that means your code is good enough for the linter (flake8) and formatter (black). If make check-format fails, it will present you with a diff, which you can resolve by running make format. Black is very opinionated, but saves a lot of time by removing the need for style nitpicks in PR review. We only deviate from its default behavior in one category: we choose to use a line length of 79 rather than the Black default of 88 (this is configured in the pyproject.toml file).

Mitiq development abides to the Contributors' Covenant.