First read the overall project contributing guidelines. These are all included in the qiskit documentation:
https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md
In addition to the general guidelines there are specific details for contributing to qiskit-ibm-runtime, these are documented below.
- For documentation issues relating to pages in the Start, Build, Transpile, Verify, Run, and Migration guides sections of https://docs.quantum.ibm.com, please open an issue in the Qiskit/documentation repo rather than the Qiskit/qiskit-ibm-runtime repo. In other words, any page that DOES NOT have
/api/in the url should be addressed in the Qiskit/documentation repo. (Exception: the Migration guide urls contain/api/but are managed in the Qiskit/documentation repo.) - For issues relating to API reference pages (any page that contains /api/ in the url), please open an issue in the repo specific to that API reference.
Before pushing your contribution please ensure that:
- The code follows the code style of this project. For convenience, you can check Style guide
- If it makes sense, add tests that cover the new changes.
- All tests pass. For convenience, you can verify the Test Types.
- The documentation has been updated accordingly. In particular, if a function or class has been modified during your contribution, please update the docstring accordingly. For convenience, you can check Building the Documentation Locally.
When submitting a pull request and your updates have end user facing impact (new feature, deprecation, removal etc), please ensure that you add a release note.
The changelog is automatically generated as part of the release process
automation. This works through a combination of the git log and the pull
request. When a release is tagged and pushed to github the release automation
bot looks at all commit messages from the git log for the release. It takes the
PR numbers from the git log (assuming a squash merge) and checks if that PR had
a Changelog: label on it. If there is a label it will add the git commit
message summary line from the git log for the release to the changelog.
If there are multiple Changelog: tags on a PR the git commit message summary
line from the git log will be used for each changelog category tagged.
The current categories for each label are as follows:
| PR Label | Changelog Category |
|---|---|
| Changelog: Deprecation | Deprecated |
| Changelog: New Feature | Added |
| Changelog: API Change | Changed |
| Changelog: Removal | Removed |
| Changelog: Bugfix | Fixed |
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-ibm. 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 to the change. The idea behind release documentation is that when a naive user with limited internal knowledge of the project is upgrading from the previous release to the new one, they should be able to read the release notes, understand if they need to update their program which uses qiskit, and how they would go about doing that. It ideally should explain why they need to make this change too, to provide the necessary context.
To make sure we don't forget a release note or if the details of user facing changes over a release cycle we require that all user facing changes include documentation at the same time as the code. To accomplish this we use the reno tool which enables a git based workflow for writing and compiling release notes.
Making a new release note is quite straightforward. Ensure that you have reno installed with::
pip install -U reno
Once you have reno installed you can make a new release note by running in your local repository checkout's root::
reno new short-description-string
where short-description-string is a brief string (with no spaces) that describes what's in the release note. This will become the prefix for the release note file. Once that is run it will create a new yaml file in releasenotes/notes. Then open that yaml file in a text editor and write the release note. The basic structure of a release note is restructured text in yaml lists under category keys. You add individual items under each category and they will be grouped automatically by release when the release notes are compiled. A single file can have as many entries in it as needed, but to avoid potential conflicts you'll want to create a new file for each pull request that has user facing changes. When you open the newly created file it will be a full template of the different categories with a description of a category as a single entry in each category. You'll want to delete all the sections you aren't using and update the contents for those you are. For example, the end result should look something like::
features:
- |
Introduced a new feature foo, that adds support for doing something to
``QuantumCircuit`` objects. It can be used by using the foo function,
for example::
from qiskit import foo
from qiskit import QuantumCircuit
foo(QuantumCircuit())
- |
The ``qiskit.QuantumCircuit`` module has a new method ``foo()``. This is
the equivalent of calling the ``qiskit.foo()`` to do something to your
QuantumCircuit. This is the equivalent of running ``qiskit.foo()`` on
your circuit, but provides the convenience of running it natively on
an object. For example::
from qiskit import QuantumCircuit
circ = QuantumCircuit()
circ.foo()
deprecations:
- |
The ``qiskit.bar`` module has been deprecated and will be removed in a
future release. Its sole function, ``foobar()`` has been superseded by the
``qiskit.foo()`` function which provides similar functionality but with
more accurate results and better performance. You should update your calls
``qiskit.bar.foobar()`` calls to ``qiskit.foo()``.You can also look at other release notes for other examples.
You can use any restructured text feature in them (code sections, tables, enumerated lists, bulleted list, etc) to express what is being changed as needed. In general you want the release notes to include as much detail as needed so that users will understand what has changed, why it changed, and how they'll have to update their code.
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.
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 number. For example you would write a release note with a link to issue 12345 as:
fixes:
- |
Fixes a race condition in the function ``foo()``. Refer to
`#12345 <https://github.com/Qiskit/qiskit-ibm-runtime/issues/12345>`_ for
more details.After release notes have been added if you want to see what the full output of
the release notes. In general the output from reno that we'll get is a rst
(ReStructuredText) file that can be compiled by
sphinx. To generate the rst file you
use the reno report command. If you want to generate the full Qiskit IBM provider
release notes for all releases (since we started using reno during 0.9) you just
run::
reno report
but you can also use the --version argument to view a single release (after
it has been tagged::
reno report --version 0.9.0
At release time reno report is used to generate the release notes for the
release and the output will be submitted as a pull request to the documentation
repository's release notes file
Building The release notes are part of the standard qiskit-ibm
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
There are three different types of tests in qiskit-ibm-runtime. The
implementation is based upon the well-documented unittest
Unit testing framework.
Run locally without connecting to an external system. They are short-running, stable and give a basic level of confidence during development.
To execute all unit tests, run:
$ make unit-test
Executed against an external system configured via a (token, instance, url) tuple. Detailed coverage of happy and non-happy paths. They are long-running and unstable at times. A successful test run gives a high level of confidence that client and APIs work well together.
To execute all integration tests, run
$ make integration-test
Executed against an external system configured via a (token, instance, url) tuple. Basic coverage of most important user-facing happy paths. Test suite runs faster than integration but slower than unit tests and is stable.
To execute all e2e tests, run
$ make e2e-test
Integration and E2E tests require an environment configuration and can be run agains both IBM Quantum APIs (ibm_quantum, and ibm_cloud).
Sample configuration for IBM Quantum
QISKIT_IBM_TOKEN=... # IBM Quantum API token
QISKIT_IBM_URL=https://auth.quantum-computing.ibm.com/api # IBM Quantum API URL
QISKIT_IBM_INSTANCE=ibm-q/open/main # IBM Quantum provider to use (hub/group/project)Sample configuration for IBM Cloud
QISKIT_IBM_TOKEN=... # IBM Cloud API key
QISKIT_IBM_URL=https://cloud.ibm.com # Cloud URL
QISKIT_IBM_INSTANCE=crn:v1:bluemix:... # The CRN value of the Quantum service instanceTo enable test cases against external system in your private fork, make sure to set above values as encrypted environment secrets. The names of the environments must match the ones that the CI workflow relies upon.
Please submit clean code and please make effort to follow existing conventions in order to keep it as readable as possible. We use:
To ensure your changes respect the style guidelines, you can run the following commands:
make lint
make style
make mypy
If you edit any documentation, refer to IBM Quantum's writing style guide. You can use Vale to automatically check some of these rules for you. With Vale installed, run the following command
make docs-testThis test also runs on CI and will fail if Vale encounters any spelling
mistakes. To add a word to the dictionary, add it to
test/docs/dictionary.txt.
The development cycle for qiskit-ibm 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. As we're preparing a new release we'll document what has changed since the previous version in the release notes.
main:
The main branch is used for development of the next version of qiskit-ibm. 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 understable/*are used to maintain released versions of qiskit-ibm. 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 merged to it are bugfixes.
When it is time to release a new minor version of qiskit-ibm we will:
- Create a new tag with the version number and push it to github
- Change the
mainversion to the next release version.
The release automation processes will be triggered by the new tag and perform the following steps:
- Create a stable branch for the new minor version from the release tag
on the
mainbranch - Build and upload binary wheels to pypi
- Create a github release page with a generated changelog
- Generate a PR on the meta-repository to bump the Qiskit IBM Provider version and meta-package version.
The stable/* branches should only receive changes in the form of bug fixes.