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 (all questions welcome!), 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#

Mitiq uses uv for packaging and dependency management. It may also be used for managing the virtual environment.

  1. Ensure you have uv installed.

  2. Clone the Mitiq repository. If you are unfamiliar with git, check out the docs, and learn about what the typical git workflow looks like.

  3. Inside the Mitiq directory (cd mitiq), use uv to create a virtual environment (/.venv) and install the dependencies by calling make install.

pip install uv
git clone https://github.com/unitaryfoundation/mitiq.git
cd mitiq
make install

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.

Note

Since uv uses a virtual environment, any commands to be run inside the virtual environment will need to be prefaced with uv run or the uv managed virtual environment will need to be activated by running source .venv/bin/activate in your shell.

Running make commands do NOT require prepending uv run.

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 uv run 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, adding examples, and updating the user 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!

It is recommended to install pre-configured Git hooks from Mitiq repository by running make install-hooks from the root of the repository immediately after cloning. In particular, the pre-commit hook will run both make check-format and make check-types before each 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):

Checklist for adding an approved QEM Technique#

After your RFC is accepted, the proposed feature (for example, a new QEM Method) will require the following:

  • Add the new QEM method to mitiq/abbreviated_name_of_qem_method such that the corresponding units tests are in mitiq/abbreviated_name_of_qem_method/tests

  • The code must follow the formatting and style guidelines discussed above,

  • The new module should be added to the API-doc using the instructions found in Automatically add information from the API docs,

  • Add documentation for the new QEM method, additional details are available in Adding files to the user guide,

  • Update docs/source/guide/glossary.md with a one-line summary of what your new feature accomplishes, and

  • Update the Quick Tour section of the README.md with information related to your new technique.

Code of conduct#

Mitiq development abides to the Contributor Covenant Code of Conduct.

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 main branch with tags for the version number of the release. Find all the previous releases here.

AI use policy and guidelines#

Mitiq’s policy is that contributors can use whatever tools they would like to craft their contributions, but there must be a human in the loop. Contributors must read and review all LLM-generated code or text before they ask other project members to review it. The contributor is always the author and is fully accountable for their contributions. Contributors should be sufficiently confident that the contribution is high enough quality that asking for a review is a good use of scarce maintainer time, and they should be able to answer questions about their work during review.

Contributors can use any tools that aid in understanding the mitiq codebase and writing code, including AI tools. However, as noted above, contributors always need to understand and explain the changes they’re proposing to make, whether or not they used an LLM as part of your process to produce them. The answer to “Why is X an improvement?” should never be “I’m not sure. The AI did it.”

Contributors are expected to be transparent and label contributions that contain substantial amounts of tool-generated content. Our policy on labelling is intended to facilitate reviews, and not to track which parts of mitiq are generated. Contributors should note tool usage in their pull request description, commit message, or wherever authorship is normally indicated for the work. For instance, use a commit message trailer like Assisted-by: . This transparency helps the community develop best practices and understand the role of these new tools.

Maintainers have the right to close contributor PRs and after warnings, ban contributors who do not abide by this policy.