Ctrl+K

Contributing to Mitiq#

All contributions to this project are welcome, and they are greatly appreciated; every little bit helps. The most common ways to contribute here are

  1. opening an issue to report a bug or propose a new feature, or ask a question, and

  2. opening a pull request to fix a bug, or implement a desired feature.

  3. opening a discussion post to ask a question (no stupid questions!), provide feedback, or show something off!

The rest of this document describes the technical details of getting set up to develop, and make your first contribution to Mitiq.

Development environment#

  1. Ensure you have python 3.9 or greater installed. If not, you can find the downloads here.

  2. Set up a virtual environment to isolate dependencies. This can be done with many different tools including Virtualenv, Pipenv, Poetry, and Anaconda. In what follows we will use Anaconda, but if you’re familiar with other tools feel free to use those.

  3. Set up a local version of the Mitiq repository. To do this you will need to use git which is a version control system. If you’re unfamiliar, check out the docs, and learn about what the typical git workflow looks like.

  4. Inside the Mitiq repository (cd mitiq), activate a virtual environment. With conda this is done using the following command.

conda create --name myenv python=3
conda activate myenv

  1. Install the dependencies. First, to get an updated version of pip inside the virtual environment run conda install pip followed by

pip install -e ".[development]"

  1. You should now have a development environment set up to work on Mitiq! 🎉 To go forward with making the desired changes, please consult the “Making changes” section of the git workflow article. If you’ve encountered any problems thus far, please let us know by opening an issue! More information about workflow can be found below in the lifecycle section.

What follows are recommendations/requirements to keep in mind while contributing.

Making changes#

Adding tests#

When modifying and/or adding new code it is important to ensure the changes are covered by tests. Test thoroughly, but not excessively. Mitiq uses a nested structure for packaging tests in directories named tests at the same level of each module. The only exception to this is that any tests requiring a QVM should be placed in the mitiq_pyquil/tests folder.

Running tests#

After making changes, ensure your changes pass all the existing tests (and any new tests you’ve added). Use pytest mitiq/$MODULE to run the tests for the module you are working on. Once they pass, you can run the entire test suite (excluding those that require the pyQuil QVM) by running the following command.

make test

This can often be slow, however, so testing your changes iteratively using pytest is often faster when doing development.

To run the tests for the pyQuil plugins, run

make test-pyquil

To run all tests, run

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

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.

Style guidelines#

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

We use Ruff 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 linting/formatting violations with

make check-format

Many common issues can be fixed automatically using the following command, but some will require manual intervention to appease Ruff.

make format

We also use Mypy as a type checker to find incompatible types compared to the type hints in your code. To test this locally, run the type check test in the top-level directory of the repository.

To find incorrectly used types by type checking in mypy, use

make check-types

If you aren’t presented with any errors, then that means your code is ready to commit!

Proposing a new feature to Mitiq#

If you are interested in adding a substantial new feature or 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, create a feature request issue and add a link to your proposal document (make sure to enable commenting on the RFC!). For any part of the template that you weren’t able to complete please mention that in the issue description.

List of accepted RFCs#

This is a list of accepted request-for-comments (RFC) documents by date of creation (reverse chronological order):

Code of conduct#

Mitiq development abides to the Contributors’ Covenant.

Lifecycle#

The basic development workflow for Mitiq is done in units of milestones which are usually one month periods where we focus our efforts on thrusts decided by the development team, alongside community members. Milestones are tracked using the GitHub milestone feature and all issues that are planned to be addressed should be tagged accordingly.

All releases for Mitiq are tagged on the master branch with tags for the version number of the release. Find all the previous releases here.

Code of conduct#

Mitiq development abides to the Contributors’ Covenant.

On this page
Show Source