Skip to content

Latest commit

 

History

History
146 lines (108 loc) · 9.88 KB

CONTRIBUTING.md

File metadata and controls

146 lines (108 loc) · 9.88 KB
Raw

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

  1. Ensure you have python 3.10 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
make install
  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, 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 using the instructions found in ,
  • Add documentation for the new QEM method, additional details are available in ,
  • Update docs/source/guide/glossary.md with a one-line summary of what your new feature accomplishes, and
  • Update the section of the README.md with information related to your new technique.

Code of conduct

Mitiq development abides to the .

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.