Contributing to Mitiq#

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

Opening an issue#

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.

Opening a pull request#

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

Version control with git#

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.

Forking the repository#

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

You can also use SSH instead of a HTTPS protocol.

Working in a virtual environment#

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

Development install#

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 dev_requirements.txt

Special Note for Windows Users Using Python 3.8:#

To prevent errors when running make docs and make doctest, Windows developers using Python 3.8 will also need to edit in their environment’s asyncio directory. This is due to Python changing asyncio’s default event loop in Windows beginning in Python 3.8. The new default event loop will not support Unix-style APIs used by some dependencies.

  1. Locate your environment directory (likely C:\Users\{username}\anaconda3\envs\{your_env}), and open {env_dir}/Lib/asyncio/

  2. Add import asyncio to the file’s import statements.

  3. Find the block of code below and replace it with the provided replacement.

    • Original Code

      if sys.platform == 'win32':  # pragma: no cover
          from .windows_events import *
          __all__ += windows_events.__all__
          from .unix_events import *  # pragma: no cover
          __all__ += unix_events.__all__
    • Replacement Code

      if sys.platform == 'win32':  # pragma: no cover
          from .windows_events import *
          __all__ += windows_events.__all__
          from .unix_events import *  # pragma: no cover
          __all__ += unix_events.__all__

Adding tests#

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. The only except to this is that any tests requiring a QVM should be placed in the mitiq_pyquil/tests folder.

Updating the documentation#

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.

Running local tests#

After making changes, please ensure your changes still pass all the existing tests. You can check that tests run with pytest. The Makefile contains some commands for running different collections of tests for the repository.

To only run tests that do not require a pyQuil QVM running, run

(myenv) make test

To run the tests for the pyQuil plugins, run

(myenv) make test-pyquil

To run all tests, run

(myenv) make test-all

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

Please also remember to check that all tests run also in the documentation examples and docstrings with

(myenv) make doctest

You may need to run make docs before you are able to run make doctest.

Style Guidelines#

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

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 in the top-level directory of the repository.

You can check for violations of the flake8 rules with

(myenv) make check-style

In order to check if black would reformat the code, use

(myenv) make check-format

If above format check fails then you will be presented with a diff which can be resolved by running

(myenv) make format

If you aren’t presented with any errors, then that means your code is good enough for the linter (flake8) and formatter (black). 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).

Proposing a new feature to Mitiq#

If you are interested in adding a larger new feature or other functionality to Mitiq, please make a copy of our Request For Comments (RFC) template and fill out the details of your enhancement proposal. Take a look at previous RFCs for examples on how to fill out your proposal. Once you have completed your proposal, then please create a feature request issue and add a link to your proposal document (make sure to enable commenting!). For any part of the template that you weren’t able to complete please mention that in the PR description and/or discuss with us on discord.

Code of conduct#

Mitiq development abides to the Contributors’ Covenant.