Welcome to pyQuil, and thanks for wanting to be a contributor! 🎉
This guide is to help walk you through how to open issues and pull requests for the pyQuil project, as well as share some general how-tos for development, testing, and maintenance.
If all you want to do is ask a question, you should do so in our Rigetti Forest Slack Workspace rather than opening an issue. Otherwise, read on to learn more!
This project and everyone participating in it is governed by pyQuil's Code of Conduct. In contributing, you are expected to uphold this code. Please report unacceptable behavior by contacting support@rigetti.com.
If you've encountered an error or unexpected behavior when using pyQuil, please file a bug report. Make sure to fill out the sections that allow us to reproduce the issue and understand the context of your development environment. We welcome the opportunity to improve pyQuil, so don't be shy if you think you've found a problem!
If you have an idea for a new addition to pyQuil, please let us know by creating a feature request. The more information you can provide, the easier it will be for the pyQuil developers to implement! A clear description of the problem being addressed, a potential solution, and any alternatives you've considered are all great things to include.
Rather than opening an issue, if you'd like to work on one that currently exists, we have some issue labels that make it easy to figure out where to start. The good first issue label references issues that we think a newcomer wouldn't have too much trouble taking on. In addition, the help wanted label is for issues that the team would like to see completed, but that we don't currently have the bandwidth for.
Once you've selected an issue to tackle, forked the repository, and made your changes, the next step is to open a pull request! We've made opening one easy by providing a Pull Request Template that includes a checklist of things to complete before asking for code review. We look forward to reviewing your work! 🙂
We use flake8 to automatically lint the code and enforce style requirements as part of the
CI pipeline. You can run these style tests yourself locally by running flake8 pyquil in the
top-level directory of the repository. If you aren't presented with any errors, then that means
your code is good enough for the linter. In addition to these tests, we have a collection of
self-imposed style guidelines regarding typing, docstrings, and line length:
- Use type hints for parameters and return types with the PEP 484 syntax.
- Write useful Sphinx-style
docstrings, but without the
typeandrtypeentries (use type hints instead). - Limit line length to 100 characters in code and documentation.
We use pytest to run the pyQuil unit tests. These are run automatically on Python 3.6 and
3.7 as part of the CI pipeline. But, you can run them yourself locally as well. Some of the
tests depend on having running QVM and quilc servers, and otherwise will be skipped. Thus,
to run the tests, you should begin by spinning up these servers via qvm -S and quilc -S,
respectively. Once this is done, run pytest in the top-level directory of pyQuil, and the
full unit test suite will start!
NOTE: Some tests (particularly those related to operator estimation and readout
symmetrization) require a nontrivial amount of computation. For this reason, they have been marked
as slow and are not run by default unless pytest is given the --runslow option. For a
full, up-to-date list of these tests, you may invoke (from the top-level directory):
grep -A 1 -r pytest.mark.slow pyquil/tests/NOTE: When making considerable changes to operator_estimation.py, we recommend that you set
the pytest option --use-seed to False to make sure you have not broken anything. You will
additionally need to provide the pyquil directory to the command, as pytest doesn't try
very hard to find the conftest.py file. The full command is as follows:
pytest --use-seed=False pyquilThe pyQuil docs build automatically as part of the CI pipeline.
However, you can also build them locally to make sure that everything renders correctly. We use
Sphinx to build the documentation, and
then host it on Read the Docs (RTD). Before you can build the docs
locally, you must make sure to install the additional Python-based requirements by
running pip install -r requirements.txt, which will pick up the Sphinx RTD theme and
autodocumentation functionality. In addition, you will need to install pandoc via your
favorite OS-level package manager (e.g. brew, apt, yum) in order to convert the
Changelog into reStructuredText (RST). Once you have done this, navigate into the docs
directory and run the following:
make htmlIf the build is successful, then you can navigate to the newly-created docs/build
directory and open the index.html file in your browser (open index.html works on macOS,
for example). You can then click around the docs just as if they were hosted on RTD, and
verify that everything looks right!
Working with the ANTLR parser involves some extra steps, see the Parser README for more information. Note that you only need to install ANTLR if you want to change the grammar, simply running the parser involves no additional steps beyond installing PyQuil as usual.
When merging PRs, we have a couple of guidelines:
-
Double-check that the PR author has completed everything in the PR checklist that is applicable to the changes.
-
Always use the "squash and merge" option so that every PR corresponds to one commit. This keeps the git history clean and encourages many small (quickly reviewable) PRs rather than behemoth ones with lots of commits.
-
When pressing the merge button, each commit message will be turned into a bullet point below the title of the issue. Make sure to truncate the PR title to ~50 characters (unless completely impossible) so it fits on one line in the commit history, and delete any spurious bullet points that add no meaningful content.
-
Make sure that the PR is associated with the current release milestone once it is merged. We use this to keep track of overall release progress, along with the Changelog.
Once it is time to perform a release of pyQuil, the maintainer must perform the following steps:
-
Push a commit to
masterthat bumps the version of pyQuil inpyquil/__init__.pyand changes the latest heading in the Changelog from "in development" to the current date. We try to follow Semantic Versioning (SemVer), which means that versions correspond toMAJOR.MINOR.PATCH, and thus for most (hopefully backwards compatible) releases, we should increment theMINORversion number. -
Tag that commit with
git tag vX.Y.Z, whereX.Y.Zcorresponds to theMAJOR.MINOR.PATCHversion bump in the previous step, and push the tag to GitHub. -
Create a GitHub release where the "Tag version" is the tag you just pushed, the "Release title" is the same as the "Tag version", and "Describe this release" contains the latest section of the Changelog, but with level-3 headings changed to level-2 headings, and with all mid-bullet newlines removed.
We use a collection of labels to add metadata to the issues and pull requests in the pyQuil project.
| Label | Description |
|---|---|
bug 🐛 |
An issue that needs fixing. |
devops 🚀 |
An issue related to CI/CD. |
discussion 🤔 |
For design discussions. |
documentation 📝 |
An issue for improving docs. |
enhancement ✨ |
A request for a new feature. |
good first issue 👶 |
A place to get started. |
help wanted 👋 |
Looking for takers. |
quality 🎨 |
Improve code quality. |
refactor 🔨 |
Rework existing functionality. |
work in progress 🚧 |
This PR is not ready to be merged. |