From b3a422a9bacb298486072feaa5a85bd6df1ab0cb Mon Sep 17 00:00:00 2001 From: Abby Mitchell <23662430+javabster@users.noreply.github.com> Date: Mon, 20 Nov 2023 13:58:06 -0500 Subject: [PATCH] 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 * 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 --- CONTRIBUTING.md | 298 +++++++++++++++++++++++--------- docs/contributing_to_qiskit.rst | 189 -------------------- docs/index.rst | 1 - 3 files changed, 212 insertions(+), 276 deletions(-) delete mode 100644 docs/contributing_to_qiskit.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 49d0d0ee37..87b4344134 100644 --- a/CONTRIBUTING.md +++ b/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 . + +## 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 ` for more + `#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///?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///?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: Screenshot_2021-03-26_at_15 38 31 - - 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, diff --git a/docs/contributing_to_qiskit.rst b/docs/contributing_to_qiskit.rst deleted file mode 100644 index bd02628fa8..0000000000 --- a/docs/contributing_to_qiskit.rst +++ /dev/null @@ -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 `__ -#. Read the repo-specific :ref:`Contributing Guidelines ` for the repo you have decided to contribute to. -#. :ref:`Set up your development environment ` -#. Familiarize yourself with the Qiskit community (via `Slack `__, - `Stack Exchange `__, `GitHub `__ 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 `__. Other Qiskit packages that -are able to receive contributions may be found as separate repositories in the official `Qiskit Github `__. - -.. _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 `__ 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 `__. - - 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 `__. - - .. 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 -`__ 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 `__. - - - -.. _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 `__ -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 `__ too and - email it to us at . diff --git a/docs/index.rst b/docs/index.rst index b82e864ccf..edb770ceee 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -83,6 +83,5 @@ Main Qiskit-related projects :caption: Contributing :hidden: - contributing_to_qiskit deprecation_policy maintainers_guide