mirror of https://github.com/Qiskit/qiskit.git
Combined contribute_to_qiskit.rst with contributing.md (#11217)
* Combined contribut_to_qiskit.rst with contributing.md * Update CONTRIBUTING.md Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jake Lishman <jake@binhbar.com> * applied review comments and removed old contributing guide * fixed docs warning --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Co-authored-by: Jake Lishman <jake@binhbar.com>
This commit is contained in:
parent
f3857f18d0
commit
b3a422a9ba
298
CONTRIBUTING.md
298
CONTRIBUTING.md
|
@ -1,23 +1,20 @@
|
|||
# Contributing
|
||||
|
||||
First read the overall project contributing guidelines. These are all
|
||||
included in the qiskit documentation:
|
||||
Qiskit is an open-source project committed to bringing quantum computing to
|
||||
people of all backgrounds. This page describes how you can join the Qiskit
|
||||
community in this goal.
|
||||
|
||||
https://qiskit.org/documentation/contributing_to_qiskit.html
|
||||
|
||||
## Contributing to Qiskit Terra
|
||||
|
||||
In addition to the general guidelines there are specific details for
|
||||
contributing to terra, these are documented below.
|
||||
|
||||
### Contents
|
||||
## Contents
|
||||
* [Before you start](#before-you-start)
|
||||
* [Choose an issue to work on](#Choose-an-issue-to-work-on)
|
||||
* [Pull request checklist](#pull-request-checklist)
|
||||
* [Set up Python virtual development environment](#set-up-python-virtual-development-environment)
|
||||
* [Installing Qiskit from source](#installing-qiskit-from-source)
|
||||
* [Pull requests](#pull-requests)
|
||||
* [Contributor Licensing Agreement](#contributor-licensing-agreement)
|
||||
* [Changelog generation](#changelog-generation)
|
||||
* [Release Notes](#release-notes)
|
||||
* [Installing Qiskit Terra from source](#installing-qiskit-terra-from-source)
|
||||
* [Test](#test)
|
||||
* [Snapshot testing for visualizations](#snapshot-testing-for-visualizations)
|
||||
* [Release notes](#release-notes)
|
||||
* [Testing](#testing)
|
||||
* [Style and Lint](#style-and-lint)
|
||||
* [Development Cycle](#development-cycle)
|
||||
* [Branches](#branches)
|
||||
|
@ -29,12 +26,139 @@ contributing to terra, these are documented below.
|
|||
* [Checking for optionals](#checking-for-optionals)
|
||||
* [Dealing with git blame ignore list](#dealing-with-the-git-blame-ignore-list)
|
||||
|
||||
### Choose an issue to work on
|
||||
Qiskit Terra uses the following labels to help non-maintainers find issues best suited to their interests and experience level:
|
||||
|
||||
* [good first issue](https://github.com/Qiskit/qiskit-terra/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) - these issues are typically the simplest available to work on, perfect for newcomers. They should already be fully scoped, with a clear approach outlined in the descriptions.
|
||||
* [help wanted](https://github.com/Qiskit/qiskit-terra/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) - these issues are generally more complex than good first issues. They typically cover work that core maintainers don't currently have capacity to implement and may require more investigation/discussion. These are a great option for experienced contributors looking for something a bit more challenging.
|
||||
* [short project](https://github.com/Qiskit/qiskit-terra/issues?q=is%3Aopen+is%3Aissue+label%3A%22short+project%22) - these issues are bigger pieces of work that require greater time commitment. Good options for hackathons, internship projects etc.
|
||||
## Before you start
|
||||
|
||||
If you are new to Qiskit contributing we recommend you do the following before diving into the code:
|
||||
|
||||
* Read the [Code of Conduct](https://github.com/Qiskit/qiskit/blob/main/CODE_OF_CONDUCT.md)
|
||||
* Familiarize yourself with the Qiskit community (via [Slack](https://qisk.it/join-slack),
|
||||
[Stack Exchange](https://quantumcomputing.stackexchange.com), [GitHub](https://github.com/qiskit-community/feedback/discussions) etc.)
|
||||
|
||||
|
||||
## Choose an issue to work on
|
||||
Qiskit uses the following labels to help non-maintainers find issues best suited to their interests and experience level:
|
||||
|
||||
* [good first issue](https://github.com/Qiskit/qiskit/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) - these issues are typically the simplest available to work on, ideal for newcomers. They should already be fully scoped, with a clear approach outlined in the descriptions.
|
||||
* [help wanted](https://github.com/Qiskit/qiskit/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) - these issues are generally more complex than good first issues. They typically cover work that core maintainers don't currently have capacity to implement and may require more investigation/discussion. These are a great option for experienced contributors looking for something a bit more challenging.
|
||||
* [short project](https://github.com/Qiskit/qiskit/issues?q=is%3Aopen+is%3Aissue+label%3A%22short+project%22) - these issues are bigger pieces of work that require greater time commitment. Good options for hackathons, internship projects etc.
|
||||
|
||||
|
||||
## Set up Python virtual development environment
|
||||
|
||||
Virtual environments are used for Qiskit development to isolate the development environment
|
||||
from system-wide packages. This way, we avoid inadvertently becoming dependent on a
|
||||
particular system configuration. For developers, this also makes it easy to maintain multiple
|
||||
environments (e.g. one per supported Python version, for older versions of Qiskit, etc.).
|
||||
|
||||
|
||||
|
||||
### Set up a Python venv
|
||||
|
||||
All Python versions supported by Qiskit include built-in virtual environment module
|
||||
[venv](https://docs.python.org/3/tutorial/venv.html).
|
||||
|
||||
Start by creating a new virtual environment with `venv`. The resulting
|
||||
environment will use the same version of Python that created it and will not inherit installed
|
||||
system-wide packages by default. The specified folder will be created and is used to hold the environment's
|
||||
installation. It can be placed anywhere. For more detail, see the official Python documentation,
|
||||
[Creation of virtual environments](https://docs.python.org/3/library/venv.html).
|
||||
|
||||
```
|
||||
python3 -m venv ~/.venvs/qiskit-dev
|
||||
```
|
||||
|
||||
Activate the environment by invoking the appropriate activation script for your system, which can
|
||||
be found within the environment folder. For example, for bash/zsh:
|
||||
|
||||
|
||||
```
|
||||
source ~/.venvs/qiskit-dev/bin/activate
|
||||
```
|
||||
|
||||
Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections
|
||||
can be located for your system.
|
||||
|
||||
```
|
||||
pip install -U pip
|
||||
```
|
||||
|
||||
```
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Set up a Conda environment
|
||||
|
||||
For Conda users, a new environment can be created as follows.
|
||||
|
||||
```
|
||||
conda create -y -n QiskitDevenv python=3
|
||||
conda activate QiskitDevenv
|
||||
```
|
||||
|
||||
```
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Installing Qiskit from source
|
||||
|
||||
Qiskit is primarily written in Python but there are some core routines
|
||||
that are written in the [Rust](https://www.rust-lang.org/) programming
|
||||
language to improve the runtime performance. For the released versions of
|
||||
qiskit we publish precompiled binaries on the
|
||||
[Python Package Index](https://pypi.org/) for all the supported platforms
|
||||
which only requires a functional Python environment to install. However, when
|
||||
building and installing from source you will need a rust compiler installed. You can do this very easily
|
||||
using rustup: https://rustup.rs/ which provides a single tool to install and
|
||||
configure the latest version of the rust compiler.
|
||||
[Other installation methods](https://forge.rust-lang.org/infra/other-installation-methods.html)
|
||||
exist too. For Windows users, besides rustup, you will also need install
|
||||
the Visual C++ build tools so that Rust can link against the system c/c++
|
||||
libraries. You can see more details on this in the
|
||||
[rustup documentation](https://rust-lang.github.io/rustup/installation/windows.html).
|
||||
|
||||
If you use Rustup, it will automatically install the correct Rust version
|
||||
currently used by the project.
|
||||
|
||||
Once you have a Rust compiler installed, you can rely on the normal Python
|
||||
build/install steps to install Qiskit. This means you just run
|
||||
`pip install .` in your local git clone to build and install Qiskit.
|
||||
|
||||
Do note that if you do use develop mode/editable install (via `python setup.py develop` or `pip install -e .`) the Rust extension will be built in debug mode
|
||||
without any optimizations enabled. This will result in poor runtime performance.
|
||||
If you'd like to use an editable install with an optimized binary you can
|
||||
run `python setup.py build_rust --release --inplace` after you install in
|
||||
editable mode to recompile the rust extensions in release mode.
|
||||
|
||||
Note that in order to run `python setup.py ...` commands you need have build
|
||||
dependency packages installed in your environment, which are listed in the
|
||||
`pyproject.toml` file under the `[build-system]` section.
|
||||
|
||||
|
||||
## Pull requests
|
||||
|
||||
We use [GitHub pull requests](https://help.github.com/articles/about-pull-requests) to accept
|
||||
contributions.
|
||||
|
||||
While not required, opening a new issue about the bug you're fixing or the
|
||||
feature you're working on before you open a pull request is an important step
|
||||
in starting a discussion with the community about your work. The issue gives us
|
||||
a place to talk about the idea and how we can work together to implement it in
|
||||
the code. It also lets the community know what you're working on, and if you
|
||||
need help, you can reference the issue when discussing it with other community
|
||||
and team members.
|
||||
|
||||
If you've written some code but need help finishing it, want to get initial
|
||||
feedback on it prior to finishing it, or want to share it and discuss prior
|
||||
to finishing the implementation, you can open a *Draft* pull request and prepend
|
||||
the title with the **\[WIP\]** tag (for Work In Progress). This will indicate
|
||||
to reviewers that the code in the PR isn't in its final state and will change.
|
||||
It also means that we will not merge the commit until it is finished. You or a
|
||||
reviewer can remove the [WIP] tag when the code is ready to be fully reviewed for merging.
|
||||
|
||||
Before marking your Pull Request as "ready for review" make sure you have followed the
|
||||
PR Checklist below. PRs that adhere to this list are more likely to get reviewed and
|
||||
merged in a timely manner.
|
||||
|
||||
### Pull request checklist
|
||||
|
||||
|
@ -42,7 +166,7 @@ When submitting a pull request and you feel it is ready for review,
|
|||
please ensure that:
|
||||
|
||||
1. The code follows the code style of the project and successfully
|
||||
passes the tests. For convenience, you can execute `tox` locally,
|
||||
passes the CI tests. For convenience, you can execute `tox` locally,
|
||||
which will run these checks and report any issues.
|
||||
|
||||
If your code fails the local style checks (specifically the black
|
||||
|
@ -55,18 +179,54 @@ please ensure that:
|
|||
If your pull request is adding a new class, function, or module that is
|
||||
intended to be user facing ensure that you've also added those to a
|
||||
documentation `autosummary` index to include it in the api documentation.
|
||||
For more details you can refer to:
|
||||
|
||||
https://qiskit.org/documentation/contributing_to_qiskit.html#documentation-structure
|
||||
|
||||
|
||||
3. If it makes sense for your change that you have added new tests that
|
||||
cover the changes.
|
||||
4. Ensure that if your change has an end user facing impact (new feature,
|
||||
deprecation, removal etc) that you have added a reno release note for that
|
||||
change and that the PR is tagged for the changelog.
|
||||
5. All contributors have signed the CLA.
|
||||
6. The PR has a concise and explanatory title (e.g. `Fixes Issue1234` is a bad title!).
|
||||
7. If the PR addresses an open issue the PR description includes the `fixes #issue-number`
|
||||
syntax to link the PR to that issue (**you must use the exact phrasing in order for GitHub
|
||||
to automatically close the issue when the PR merges**)
|
||||
|
||||
### Changelog generation
|
||||
### Code Review
|
||||
|
||||
Code review is done in the open and is open to anyone. While only maintainers have
|
||||
access to merge commits, community feedback on pull requests is extremely valuable.
|
||||
It is also a good mechanism to learn about the code base.
|
||||
|
||||
Response times may vary for your PR, it is not unusual to wait a few weeks for a maintainer
|
||||
to review your work, due to other internal commitments. If you have been waiting over a week
|
||||
for a review on your PR feel free to tag the relevant maintainer in a comment to politely remind
|
||||
them to review your work.
|
||||
|
||||
Please be patient! Maintainers have a number of other priorities to focus on and so it may take
|
||||
some time for your work to get reviewed and merged. PRs that are in a good shape (i.e. following the [Pull request checklist](#pull-request-checklist))
|
||||
are easier for maintainers to review and more likely to get merged in a timely manner. Please also make
|
||||
sure to always be kind and respectful in your interactions with maintainers and other contributors, you can read
|
||||
[the Qiskit Code of Conduct](https://github.com/Qiskit/qiskit/blob/main/CODE_OF_CONDUCT.md).
|
||||
|
||||
|
||||
## Contributor Licensing Agreement
|
||||
|
||||
Before you can submit any code, all contributors must sign a
|
||||
contributor license agreement (CLA). By signing a CLA, you're attesting
|
||||
that you are the author of the contribution, and that you're freely
|
||||
contributing it under the terms of the Apache-2.0 license.
|
||||
|
||||
When you contribute to the Qiskit project with a new pull request,
|
||||
a bot will evaluate whether you have signed the CLA. If required, the
|
||||
bot will comment on the pull request, including a link to accept the
|
||||
agreement. The [individual CLA](https://qiskit.org/license/qiskit-cla.pdf)
|
||||
document is available for review as a PDF.
|
||||
|
||||
Note: If your contribution is part of your employment or your contribution
|
||||
is the property of your employer, then you will more than likely need to sign a
|
||||
[corporate CLA](https://qiskit.org/license/qiskit-corporate-cla.pdf) too and
|
||||
email it to us at <qiskit@us.ibm.com>.
|
||||
|
||||
## Changelog generation
|
||||
|
||||
The changelog is automatically generated as part of the release process
|
||||
automation. This works through a combination of the git log and the pull
|
||||
|
@ -89,10 +249,10 @@ The current categories for each label are as follows:
|
|||
| Changelog: Removal | Removed |
|
||||
| Changelog: Bugfix | Fixed |
|
||||
|
||||
### Release Notes
|
||||
## Release notes
|
||||
|
||||
When making any end user facing changes in a contribution we have to make sure
|
||||
we document that when we release a new version of qiskit-terra. The expectation
|
||||
we document that when we release a new version of qiskit. The expectation
|
||||
is that if your code contribution has user facing changes that you will write
|
||||
the release documentation for these changes. This documentation must explain
|
||||
what was changed, why it was changed, and how users can either use or adapt
|
||||
|
@ -109,7 +269,7 @@ documentation at the same time as the code. To accomplish this we use the
|
|||
[reno](https://docs.openstack.org/reno/latest/) tool which enables a git based
|
||||
workflow for writing and compiling release notes.
|
||||
|
||||
#### Adding a new release note
|
||||
### Adding a new release note
|
||||
|
||||
Making a new release note is quite straightforward. Ensure that you have reno
|
||||
installed with:
|
||||
|
@ -181,7 +341,7 @@ After you've finished writing your release notes you'll want to add the note
|
|||
file to your commit with `git add` and commit them to your PR branch to make
|
||||
sure they're included with the code in your PR.
|
||||
|
||||
##### Linking to issues
|
||||
#### Linking to issues
|
||||
|
||||
If you need to link to an issue or other github artifact as part of the release
|
||||
note this should be done using an inline link with the text being the issue
|
||||
|
@ -192,7 +352,7 @@ as:
|
|||
fixes:
|
||||
- |
|
||||
Fixes a race condition in the function ``foo()``. Refer to
|
||||
`#12345 <https://github.com/Qiskit/qiskit-terra/issues/12345>` for more
|
||||
`#12345 <https://github.com/Qiskit/qiskit/issues/12345>` for more
|
||||
details.
|
||||
```
|
||||
|
||||
|
@ -202,7 +362,7 @@ After release notes have been added, you can use reno to see what the full outpu
|
|||
of the release notes is. In general the output from reno that we'll get is a rst
|
||||
(ReStructuredText) file that can be compiled by
|
||||
[sphinx](https://www.sphinx-doc.org/en/master/). To generate the rst file you
|
||||
use the ``reno report`` command. If you want to generate the full terra release
|
||||
use the ``reno report`` command. If you want to generate the full release
|
||||
notes for all releases (since we started using reno during 0.9) you just run:
|
||||
|
||||
reno report
|
||||
|
@ -219,48 +379,14 @@ https://github.com/Qiskit/qiskit/blob/master/docs/release_notes.rst)
|
|||
|
||||
#### Building release notes locally
|
||||
|
||||
Building The release notes are part of the standard qiskit-terra documentation
|
||||
Building The release notes are part of the standard qiskit documentation
|
||||
builds. To check what the rendered html output of the release notes will look
|
||||
like for the current state of the repo you can run: `tox -edocs` which will
|
||||
build all the documentation into `docs/_build/html` and the release notes in
|
||||
particular will be located at `docs/_build/html/release_notes.html`
|
||||
|
||||
## Installing Qiskit Terra from source
|
||||
|
||||
Qiskit Terra is primarily written in Python but there are some core routines
|
||||
that are written in the [Rust](https://www.rust-lang.org/) programming
|
||||
language to improve the runtime performance. For the released versions of
|
||||
qiskit-terra we publish precompiled binaries on the
|
||||
[Python Package Index](https://pypi.org/) for all the supported platforms
|
||||
which only requires a functional Python environment to install. However, when
|
||||
building and installing from source you will need a rust compiler installed. You can do this very easily
|
||||
using rustup: https://rustup.rs/ which provides a single tool to install and
|
||||
configure the latest version of the rust compiler.
|
||||
[Other installation methods](https://forge.rust-lang.org/infra/other-installation-methods.html)
|
||||
exist too. For Windows users, besides rustup, you will also need install
|
||||
the Visual C++ build tools so that Rust can link against the system c/c++
|
||||
libraries. You can see more details on this in the
|
||||
[rustup documentation](https://rust-lang.github.io/rustup/installation/windows.html).
|
||||
|
||||
If you use Rustup, it will automatically install the correct Rust version
|
||||
currently used by the project.
|
||||
|
||||
Once you have a Rust compiler installed, you can rely on the normal Python
|
||||
build/install steps to install Qiskit Terra. This means you just run
|
||||
`pip install .` in your local git clone to build and install Qiskit Terra.
|
||||
|
||||
Do note that if you do use develop mode/editable install (via `python setup.py develop` or `pip install -e .`) the Rust extension will be built in debug mode
|
||||
without any optimizations enabled. This will result in poor runtime performance.
|
||||
If you'd like to use an editable install with an optimized binary you can
|
||||
run `python setup.py build_rust --release --inplace` after you install in
|
||||
editable mode to recompile the rust extensions in release mode.
|
||||
|
||||
Note that in order to run `python setup.py ...` commands you need have build
|
||||
dependency packages installed in your environment, which are listed in the
|
||||
`pyproject.toml` file under the `[build-system]` section.
|
||||
|
||||
|
||||
## Test
|
||||
## Testing
|
||||
|
||||
Once you've made a code change, it is important to verify that your change
|
||||
does not break any existing tests and that any new tests that you've added
|
||||
|
@ -389,7 +515,7 @@ you will need to check that your changes don't break any snapshot tests, and add
|
|||
new tests where necessary. You can do this as follows:
|
||||
|
||||
1. Make sure you have pushed your latest changes to your remote branch.
|
||||
2. Go to link: `https://mybinder.org/v2/gh/<github_user>/<repo>/<branch>?urlpath=apps/test/ipynb/mpl_tester.ipynb`. For example, if your GitHub username is `username`, your forked repo has the same name the original, and your branch is `my_awesome_new_feature`, you should visit https://mybinder.org/v2/gh/username/qiskit-terra/my_awesome_new_feature?urlpath=apps/test/ipynb/mpl_tester.ipynb.
|
||||
2. Go to link: `https://mybinder.org/v2/gh/<github_user>/<repo>/<branch>?urlpath=apps/test/ipynb/mpl_tester.ipynb`. For example, if your GitHub username is `username`, your forked repo has the same name the original, and your branch is `my_awesome_new_feature`, you should visit https://mybinder.org/v2/gh/username/qiskit/my_awesome_new_feature?urlpath=apps/test/ipynb/mpl_tester.ipynb.
|
||||
This opens a Jupyter Notebook application running in the cloud that automatically runs
|
||||
the snapshot tests (note this may take some time to finish loading).
|
||||
3. Each test result provides a set of 3 images (left: reference image, middle: your test result, right: differences). In the list of tests the passed tests are collapsed and failed tests are expanded. If a test fails, you will see a situation like this:
|
||||
|
@ -400,7 +526,7 @@ can sometimes result in minor changes elsewhere to spacing etc. In these cases
|
|||
you just need to update the reference images as follows:
|
||||
- download the mismatched images (link at top of Jupyter Notebook output)
|
||||
- unzip the folder
|
||||
- copy and paste the new images into `qiskit-terra/test/ipynb/mpl/references`,
|
||||
- copy and paste the new images into `qiskit/test/ipynb/mpl/references`,
|
||||
replacing the existing reference images
|
||||
- add, commit and push your changes, then restart the Jupyter Notebook app in your browser. The
|
||||
tests should now pass.
|
||||
|
@ -414,7 +540,7 @@ you just need to update the reference images as follows:
|
|||
|
||||
<img width="1002" alt="Screenshot_2021-03-26_at_15 38 31" src="https://user-images.githubusercontent.com/23662430/112665215-b9c3a000-8e52-11eb-89e7-b18550718522.png">
|
||||
|
||||
- download the new images, then copy and paste into `qiskit-terra/test/ipynb/mpl/references`
|
||||
- download the new images, then copy and paste into `qiskit/test/ipynb/mpl/references`
|
||||
- add, commit and push your changes, restart the Jupyter Notebook app in your browser. The
|
||||
new tests should now pass.
|
||||
|
||||
|
@ -422,14 +548,14 @@ Note: If you have run `test/ipynb/mpl_tester.ipynb` locally it is possible some
|
|||
|
||||
## Style and lint
|
||||
|
||||
Qiskit Terra uses three tools for verify code formatting and lint checking. The
|
||||
Qiskit uses three tools for verify code formatting and lint checking. The
|
||||
first tool is [black](https://github.com/psf/black) which is a code formatting
|
||||
tool that will automatically update the code formatting to a consistent style.
|
||||
The second tool is [pylint](https://www.pylint.org/) which is a code linter
|
||||
which does a deeper analysis of the Python code to find both style issues and
|
||||
potential bugs and other common issues in Python. The third tool is the linter
|
||||
[ruff](https://github.com/charliermarsh/ruff), which has been recently
|
||||
introduced into Qiskit Terra on an experimental basis. Only a very small number
|
||||
introduced into Qiskit on an experimental basis. Only a very small number
|
||||
of rules are enabled.
|
||||
|
||||
You can check that your local modifications conform to the style rules by
|
||||
|
@ -451,9 +577,9 @@ rather than via `tox`. If you have installed the development packages in your py
|
|||
`pip install -r requirements-dev.txt`, then `ruff` and `black` will be available and can be run from
|
||||
the command line. See [`tox.ini`](tox.ini) for how `tox` invokes them.
|
||||
|
||||
## Development Cycle
|
||||
## Development cycle
|
||||
|
||||
The development cycle for qiskit-terra is all handled in the open using
|
||||
The development cycle for qiskit is all handled in the open using
|
||||
the project boards in Github for project management. We use milestones
|
||||
in Github to track work for specific releases. The features or other changes
|
||||
that we want to include in a release will be tagged and discussed in Github.
|
||||
|
@ -464,12 +590,12 @@ previous version in the release notes.
|
|||
|
||||
* `main`:
|
||||
|
||||
The main branch is used for development of the next version of qiskit-terra.
|
||||
The main branch is used for development of the next version of qiskit.
|
||||
It will be updated frequently and should not be considered stable. The API
|
||||
can and will change on main as we introduce and refine new features.
|
||||
|
||||
* `stable/*` branches:
|
||||
Branches under `stable/*` are used to maintain released versions of qiskit-terra.
|
||||
Branches under `stable/*` are used to maintain released versions of qiskit.
|
||||
It contains the version of the code corresponding to the latest release for
|
||||
that minor version on pypi. For example, stable/0.8 contains the code for the
|
||||
0.8.2 release on pypi. The API on these branches are stable and the only changes
|
||||
|
@ -486,7 +612,7 @@ PR is opened after this date it will not be considered for inclusion in that
|
|||
release. Note, that meeting these deadlines does not guarantee inclusion in a
|
||||
release: they are preconditions. You can refer to the milestone page for each
|
||||
release to see these dates for each release (for example for 0.21.0 the page is:
|
||||
https://github.com/Qiskit/qiskit-terra/milestone/23).
|
||||
https://github.com/Qiskit/qiskit/milestone/23).
|
||||
|
||||
After the proposal freeze a release review period will begin, during this time
|
||||
release candidate PRs will be reviewed as we finalize the feature set and merge
|
||||
|
@ -501,7 +627,7 @@ is a need additional release candidates can be published from `stable/*` and whe
|
|||
release is ready a full release will be tagged and published from `stable/*`.
|
||||
|
||||
## Adding deprecation warnings
|
||||
The qiskit-terra code is part of Qiskit and, therefore, the [Qiskit Deprecation Policy](https://qiskit.org/documentation/contributing_to_qiskit.html#deprecation-policy) fully applies here. Additionally, qiskit-terra does not allow `DeprecationWarning`s in its testsuite. If you are deprecating code, you should add a test to use the new/non-deprecated method (most of the time based on the existing test of the deprecated method) and alter the existing test to check that the deprecated method still works as expected, [using `assertWarns`](https://docs.python.org/3/library/unittest.html#unittest.TestCase.assertWarns). The `assertWarns` context will silence the deprecation warning while checking that it raises.
|
||||
The qiskit code is part of Qiskit and, therefore, the [Qiskit Deprecation Policy](https://qiskit.org/documentation/contributing_to_qiskit.html#deprecation-policy) fully applies here. Additionally, qiskit does not allow `DeprecationWarning`s in its testsuite. If you are deprecating code, you should add a test to use the new/non-deprecated method (most of the time based on the existing test of the deprecated method) and alter the existing test to check that the deprecated method still works as expected, [using `assertWarns`](https://docs.python.org/3/library/unittest.html#unittest.TestCase.assertWarns). The `assertWarns` context will silence the deprecation warning while checking that it raises.
|
||||
|
||||
For example, if `Obj.method1` is being deprecated in favour of `Obj.method2`, the existing test (or tests) for `method1` might look like this:
|
||||
|
||||
|
@ -529,21 +655,21 @@ def test_method2(self):
|
|||
|
||||
## Using dependencies
|
||||
|
||||
We distinguish between "requirements" and "optional dependencies" in qiskit-terra.
|
||||
A requirement is a package that is absolutely necessary for core functionality in qiskit-terra, such as Numpy or Scipy.
|
||||
We distinguish between "requirements" and "optional dependencies" in qiskit.
|
||||
A requirement is a package that is absolutely necessary for core functionality in qiskit, such as Numpy or Scipy.
|
||||
An optional dependency is a package that is used for specialized functionality, which might not be needed by all users.
|
||||
If a new feature has a new dependency, it is almost certainly optional.
|
||||
|
||||
### Adding a requirement
|
||||
|
||||
Any new requirement must have broad system support; it needs to be supported on all the Python versions and operating systems that qiskit-terra supports.
|
||||
Any new requirement must have broad system support; it needs to be supported on all the Python versions and operating systems that qiskit supports.
|
||||
It also cannot impose many version restrictions on other packages.
|
||||
Users often install qiskit-terra into virtual environments with many different packages in, and we need to ensure that neither we, nor any of our requirements, conflict with their other packages.
|
||||
Users often install qiskit into virtual environments with many different packages in, and we need to ensure that neither we, nor any of our requirements, conflict with their other packages.
|
||||
When adding a new requirement, you must add it to [`requirements.txt`](requirements.txt) with as loose a constraint on the allowed versions as possible.
|
||||
|
||||
### Adding an optional dependency
|
||||
|
||||
New features can also use optional dependencies, which might be used only in very limited parts of qiskit-terra.
|
||||
New features can also use optional dependencies, which might be used only in very limited parts of qiskit.
|
||||
These are not required to use the rest of the package, and so should not be added to `requirements.txt`.
|
||||
Instead, if several optional dependencies are grouped together to provide one feature, you can consider adding an "extra" to the package metadata, such as the `visualization` extra that installs Matplotlib and Seaborn (amongst others).
|
||||
To do this, modify the [`setup.py`](setup.py) file, adding another entry in the `extras_require` keyword argument to `setup()` at the bottom of the file.
|
||||
|
@ -552,7 +678,7 @@ You should also add a new "tester" to [`qiskit.utils.optionals`](qiskit/utils/op
|
|||
|
||||
### Checking for optionals
|
||||
|
||||
You cannot `import` an optional dependency at the top of a file, because if it is not installed, it will raise an error and qiskit-terra will be unusable.
|
||||
You cannot `import` an optional dependency at the top of a file, because if it is not installed, it will raise an error and qiskit will be unusable.
|
||||
We also largely want to avoid importing packages until they are actually used; if we import a lot of packages during `import qiskit`, it becomes sluggish for the user if they have a large environment.
|
||||
Instead, you should use [one of the "lazy testers" for optional dependencies](https://qiskit.org/documentation/apidoc/utils.html#module-qiskit.utils.optionals), and import your optional dependency inside the function or class that uses it, as in the examples within that link.
|
||||
Very lightweight _requirements_ can be imported at the tops of files, but even this should be limited; it's always ok to `import numpy`, but Scipy modules are relatively heavy, so only import them within functions that use them.
|
||||
|
@ -560,7 +686,7 @@ Very lightweight _requirements_ can be imported at the tops of files, but even t
|
|||
|
||||
## Dealing with the git blame ignore list
|
||||
|
||||
In the qiskit-terra repository we maintain a list of commits for git blame
|
||||
In the qiskit repository we maintain a list of commits for git blame
|
||||
to ignore. This is mostly commits that are code style changes that don't
|
||||
change the functionality but just change the code formatting (for example,
|
||||
when we migrated to use black for code formatting). This file,
|
||||
|
|
|
@ -1,189 +0,0 @@
|
|||
######################
|
||||
Contributing to Qiskit
|
||||
######################
|
||||
|
||||
Qiskit is an open-source project committed to bringing quantum computing to
|
||||
people of all backgrounds. This page describes how you can join the Qiskit
|
||||
community in this goal.
|
||||
|
||||
****************
|
||||
Before You Start
|
||||
****************
|
||||
|
||||
If you are new to Qiskit contributing we recommend you do the following before diving into the code:
|
||||
|
||||
#. Read the `Code of Conduct <https://github.com/Qiskit/qiskit/blob/master/CODE_OF_CONDUCT.md>`__
|
||||
#. Read the repo-specific :ref:`Contributing Guidelines <contributing_links>` for the repo you have decided to contribute to.
|
||||
#. :ref:`Set up your development environment <dev-env-setup>`
|
||||
#. Familiarize yourself with the Qiskit community (via `Slack <https://qisk.it/join-slack>`__,
|
||||
`Stack Exchange <https://quantumcomputing.stackexchange.com/>`__, `GitHub <https://github.com/qiskit-community/feedback/discussions>`__ etc.)
|
||||
|
||||
.. _contributing_links:
|
||||
|
||||
********************************
|
||||
Contributing to a Specific Repo
|
||||
********************************
|
||||
|
||||
Each Qiskit package has its own set of Contributing Guidelines (kept in the ``CONTRIBUTING.md`` file) which
|
||||
details specific information on contributing to that repository. Make sure you read through the repo-specific
|
||||
Contributing Guidelines prior to making your contribution to a specific repo as each project may have
|
||||
slightly different requirements and processes. For Qiskit Terra, the main repository, the contributing guidelines
|
||||
may be be found `here <https://github.com/Qiskit/qiskit-terra/blob/main/CONTRIBUTING.md>`__. Other Qiskit packages that
|
||||
are able to receive contributions may be found as separate repositories in the official `Qiskit Github <https://github.com/Qiskit>`__.
|
||||
|
||||
.. _dev-env-setup:
|
||||
|
||||
Set up Your Development Environment
|
||||
===================================
|
||||
|
||||
To get started contributing to the Python-based Qiskit repos you will need to set up a Python Virtual
|
||||
Development Environment and install the appropriate package **from source**.
|
||||
|
||||
For a quick guide on how to do this for qiskit-terra take a look at the
|
||||
`How to Install Qiskit - Contributors <https://www.youtube.com/watch?v=Pix2MFCtiOo>`__ YouTube video.
|
||||
|
||||
For non-python packages you should check the CONTRIBUTING.md file for specific details on setting up your dev environment.
|
||||
|
||||
Set up Python Virtual Development Environment
|
||||
---------------------------------------------
|
||||
|
||||
Virtual environments are used for Qiskit development to isolate the development environment
|
||||
from system-wide packages. This way, we avoid inadvertently becoming dependent on a
|
||||
particular system configuration. For developers, this also makes it easy to maintain multiple
|
||||
environments (e.g. one per supported Python version, for older versions of Qiskit, etc.).
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Python venv
|
||||
|
||||
All Python versions supported by Qiskit include built-in virtual environment module
|
||||
`venv <https://docs.python.org/3/tutorial/venv.html>`__.
|
||||
|
||||
Start by creating a new virtual environment with ``venv``. The resulting
|
||||
environment will use the same version of Python that created it and will not inherit installed
|
||||
system-wide packages by default. The specified folder will be created and is used to hold the environment's
|
||||
installation. It can be placed anywhere. For more detail, see the official Python documentation,
|
||||
`Creation of virtual environments <https://docs.python.org/3/library/venv.html>`__.
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
python3 -m venv ~/.venvs/qiskit-dev
|
||||
|
||||
Activate the environment by invoking the appropriate activation script for your system, which can
|
||||
be found within the environment folder. For example, for bash/zsh:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
source ~/.venvs/qiskit-dev/bin/activate
|
||||
|
||||
Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections
|
||||
can be located for your system.
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip install -U pip
|
||||
|
||||
.. tab-item:: Conda
|
||||
|
||||
For Conda users, a new environment can be created as follows.
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
conda create -y -n QiskitDevenv python=3
|
||||
conda activate QiskitDevenv
|
||||
|
||||
|
||||
|
||||
.. code:: sh
|
||||
|
||||
pip install -e .
|
||||
|
||||
|
||||
Pull Requests
|
||||
=============
|
||||
|
||||
We use `GitHub pull requests
|
||||
<https://help.github.com/articles/about-pull-requests>`__ to accept
|
||||
contributions.
|
||||
|
||||
While not required, opening a new issue about the bug you're fixing or the
|
||||
feature you're working on before you open a pull request is an important step
|
||||
in starting a discussion with the community about your work. The issue gives us
|
||||
a place to talk about the idea and how we can work together to implement it in
|
||||
the code. It also lets the community know what you're working on, and if you
|
||||
need help, you can reference the issue when discussing it with other community
|
||||
and team members.
|
||||
|
||||
If you've written some code but need help finishing it, want to get initial
|
||||
feedback on it prior to finishing it, or want to share it and discuss prior
|
||||
to finishing the implementation, you can open a *Draft* pull request and prepend
|
||||
the title with the **\[WIP\]** tag (for Work In Progress). This will indicate
|
||||
to reviewers that the code in the PR isn't in its final state and will change.
|
||||
It also means that we will not merge the commit until it is finished. You or a
|
||||
reviewer can remove the [WIP] tag when the code is ready to be fully reviewed for merging.
|
||||
|
||||
Before marking your Pull Request as "ready for review" make sure you have followed the
|
||||
PR Checklist below. PRs that adhere to this list are more likely to get reviewed and
|
||||
merged in a timely manner.
|
||||
|
||||
.. _pr-checklist:
|
||||
|
||||
**Pull Request Checklist:**
|
||||
---------------------------
|
||||
- You have followed the requirements in the CONTRIBUTING.md file for the specific repo you are
|
||||
contributing to.
|
||||
- All CI checks pass (it's recommended to run tests and lint checks locally before pushing).
|
||||
- New tests have been added for any new functionality that has been introduced.
|
||||
- The documentation has been updated accordingly for any new/modified functionality.
|
||||
- A release note has been added if the change has a user-facing impact.
|
||||
- Any superfluous comments or print statements have been removed.
|
||||
- All contributors have signed the :ref:`cla`.
|
||||
- The PR has a concise and explanatory title (e.g. ``Fixes Issue1234`` is a bad title!).
|
||||
- If the PR addresses an open issue the PR description includes the ``fixes #issue-number``
|
||||
syntax to link the PR to that issue (**you must use the exact phrasing in order for GitHub
|
||||
to automatically close the issue when the PR merges**)
|
||||
|
||||
|
||||
|
||||
Code Review
|
||||
===========
|
||||
|
||||
Code review is done in the open and is open to anyone. While only maintainers have
|
||||
access to merge commits, community feedback on pull requests is extremely valuable.
|
||||
It is also a good mechanism to learn about the code base.
|
||||
|
||||
Response times may vary for your PR, it is not unusual to wait a few weeks for a maintainer
|
||||
to review your work, due to other internal commitments. If you have been waiting over a week
|
||||
for a review on your PR feel free to tag the relevant maintainer in a comment to politely remind
|
||||
them to review your work.
|
||||
|
||||
Please be patient! Maintainers have a number of other priorities to focus on and so it may take
|
||||
some time for your work to get reviewed and merged. PRs that are in a good shape (i.e. following the :ref:`pr-checklist`)
|
||||
are easier for maintainers to review and more likely to get merged in a timely manner. Please also make
|
||||
sure to always be kind and respectful in your interactions with maintainers and other contributors, you can read
|
||||
`the Qiskit Code of Conduct <https://github.com/Qiskit/qiskit/blob/master/CODE_OF_CONDUCT.md>`__.
|
||||
|
||||
|
||||
|
||||
.. _cla:
|
||||
|
||||
Contributor License Agreement
|
||||
=============================
|
||||
|
||||
Before you can submit any code, all contributors must sign a
|
||||
contributor license agreement (CLA). By signing a CLA, you're attesting
|
||||
that you are the author of the contribution, and that you're freely
|
||||
contributing it under the terms of the Apache-2.0 license.
|
||||
|
||||
When you contribute to the Qiskit project with a new pull request,
|
||||
a bot will evaluate whether you have signed the CLA. If required, the
|
||||
bot will comment on the pull request, including a link to accept the
|
||||
agreement. The `individual CLA <https://qiskit.org/license/qiskit-cla.pdf>`__
|
||||
document is available for review as a PDF.
|
||||
|
||||
.. note::
|
||||
|
||||
If your contribution is part of your employment or your contribution
|
||||
is the property of your employer, then you will more than likely need to sign a
|
||||
`corporate CLA <https://qiskit.org/license/qiskit-corporate-cla.pdf>`__ too and
|
||||
email it to us at <qiskit@us.ibm.com>.
|
|
@ -83,6 +83,5 @@ Main Qiskit-related projects
|
|||
:caption: Contributing
|
||||
:hidden:
|
||||
|
||||
contributing_to_qiskit
|
||||
deprecation_policy
|
||||
maintainers_guide
|
||||
|
|
Loading…
Reference in New Issue