Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
157 lines (121 loc) · 9.76 KB

CONTRIBUTING.md

File metadata and controls

157 lines (121 loc) · 9.76 KB

Contributing to Mitiq

All contributions to this project are welcome, and they are greatly appreciated; every little bit helps. The two 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.

That said, feel free to open an issue to ask a question, provide general feedback, etc.

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

Running tests

After making changes, please ensure your changes pass all the existing tests (and any new tests you've added). You can run the tests using the pytest CLI, but the Makefile contains many of the common commands you'll need to ensure your code is aligned with our standards.

For example, to run all the tests that do not require a pyQuil QVM, run

make test

This is typically suitable for most development tasks and is the easiest, and most common way to test.

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

If you've modified any docstrings/added new functions, run make doctest to ensure they are formatted correctly. You may need to run make docs before you are able to run make doctest.

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 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

make check-style

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

make check-format

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

make format

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.

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 __init__.py 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/__init__.py.
  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__
else:
    from .unix_events import *  # pragma: no cover
    __all__ += unix_events.__all__

    • Replacement Code

      if sys.platform == 'win32':  # pragma: no cover
    from .windows_events import *
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
    __all__ += windows_events.__all__
else:
    from .unix_events import *  # pragma: no cover
    __all__ += unix_events.__all__

Code of conduct

Mitiq development abides to the Contributors' Covenant.