Contributing to QRMI#

Outlines the process for contributing code, documentation, tests, and other improvements to QRMI.

Prerequisites #

If you are new to contributing to Qiskit, we recommend you do the following before diving into the code:

Read the Code of Conduct
Familiarise yourself with the Qiskit community (via Slack, GitHub, etc.)

Quick Start #

The steps below provide the fastest path to making and submitting a contribution to QRMI.

Fork the QRMI repository and clone your fork:

git clone https://github.com/<your-username>/qrmi.git
cd qrmi

Create and activate a Python virtual environment:

python3 -m venv ~/.venvs/qrmi-dev
source ~/.venvs/qrmi-dev/bin/activate

Install the development dependencies:

pip install --upgrade pip
pip install -r requirements-dev.txt

Build QRMI locally:

. ~/.cargo/env
cargo build --locked --release

Create a branch for your work:
```
git checkout -b fix/my-change
```
Make your changes and add any necessary updates to tests or documentation.

Run the formatting, linting, and test checks before submitting:

make fmt-rust
make fmt-python
make lint-wheels
make lint-rust-all
make test

Commit your changes:

git commit -m "Add tests for QRMIService"

Push your branch and open a pull request:
```
git push origin fix/my-change
```
Complete the pull request template and ensure all CI checks pass.

For additional information and more detail, explore the sections below.

It is recommended that contributors fork the QRMI repository. This allows contributors to make changes in their own forked repository, any branches on the fork can be submitted as pull requests to the main QRMI repository.

Once the forked repository is set up, you can clone it to your local machine and create a new branch for your changes.

git clone https://github.com/<your-username>/qrmi.git
cd qrmi
git checkout -b fix/my-change

Setting up the developer environment #

Create a virtual environment #

Virtual environments are used for QRMI 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 QRMI, etc.).

For Conda users, a new environment can be created as follows:

conda create -y -n QRMIDevenv python=3
conda activate QRMIDevenv

Install the QRMI Rust/C dependencies:

. ~/.cargo/env
cargo clean
cargo build --locked --release

Optionally, you can install the Python dependencies too:

pip install -e .

All Python versions supported by Qiskit include a 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 details, see the official Python documentation, Creation of virtual environments.

python3 -m venv ~/.venvs/qrmi-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/qrmi-dev/bin/activate

Upgrade pip within the environment to ensure QRMI dependencies installed in the subsequent sections can be located for your system. You need pip>=25.1 to use the --group feature, used to manage developer dependency groups:

pip install -U pip

You can easily install all the standard developer dependencies for in-place testing, documentation-building, and linting using:

pip install -r requirements-dev.txt

Install QRMI from source #

Refer to Installing QRMI.

Issues and pull requests #

We use GitHub pull requests to accept contributions.

While not required, it is best practice to open a new issue for bug fixes and feature development, before opening a pull request. This allows discussion with the community about your work:

Important

Issues provide a place to talk about the idea and how we can work together to implement it in the code. They let the community know what you are working on and offer help and feedback. Issues are numbered and can be referenced during discussions 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. This indicates to reviewers that the code in the PR isn’t final and will change. Once the PR is finalised, click Ready for review to convert the draft into a review-ready PR.

Before marking your PR as “ready for review”, make sure you have followed the PR checklist below. PRs that adhere to this list are more likely to be reviewed and merged in a timely manner.

Pull request checklist #

When submitting a pull request for review, please ensure that:

The code follows the code style of the project and successfully passes the CI tests. For convenience, you can execute the following commands locally, which will run these checks and report any issues.
- make lint-rust-all
- make lint-wheels
- make fmt-rust
- make fmt-python
The documentation has been updated accordingly and any new documentation has been added. Ensure the documentation can be successfully built locally before requesting workflows to run.
Any changes to functions or classes are reflected in updated docstrings.
Any additional tests, where warranted, have been added and tested locally.
Any changes that impact the end-user (new feature, deprecation, removal, etc.) include a Reno release note for that change and that the PR is tagged for the changelog.
All contributors have signed the CLA.
The PR has a concise and descriptive title.
- Fixes Issue1234 is a bad title. Fix <ERROR_NAME> is much more descriptive.
The PR description includes the Fixes #<ISSUE_NUMBER> syntax to link the PR to the relevant open issue.
- You must use the exact phrasing for GitHub to automatically close the issue when the PR merges.

Pre-commit `detect-secrets`#

detect-secrets is an open-source, developer-friendly tool designed to scan codebases for mistakenly committed secrets (such as API keys, passwords, and private tokens) before they leak. To keep our credentials secure, we recommend that all developers integrate this into their workflow using the following instructions:

Attention

Before you begin, ensure you have a Python virtual environment (i.e. venv) active. You will need to install pre-commit, which manages the hooks that run detect-secrets automatically.

Installing `pre-commit`#

Run the following commands in your virtual environment terminal:

pip install pre-commit
pre-commit install

Find .pre-commit-config.yaml for the initial setup.

Run the following command to generate a .secrets.baseline file.

detect-secrets scan --force-use-all-plugins > .secrets.baseline

The baseline records known false positives so future scans focus on newly introduced secrets.

Handling false positives#

If the pre-commit hook identifies a secret that you have verified is not sensitive (a false positive), please use the following command to audit and update the baseline file. Once updated, include the modified .secrets.baseline in your PR to ensure the pre-commit passes in the future.

pip install detect-secrets
detect-secrets scan --force-use-all-plugins --exclude-files '.secrets.*' --exclude-files '.git*' --baseline .secrets.baseline
detect-secrets audit .secrets.baseline

Manual execution and overrides#

To manually trigger a scan of all files in the repository for a local sanity check, execute the following command:

pre-commit run --all-files

Bypassing the hook#

Warning

Bypassing the hook is not recommended.

If you must force a commit without running the pre-commit checks (e.g. during an emergency fix), you may use the --no-verify flag:

git commit -m "Your message" --no-verify

Code Review #

Code review is transparent and open to anyone. While only maintainers have permission to merge commits, community feedback on pull requests is extremely valuable. It is also a good way 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, therefore it may take some time for your work to be reviewed and merged. PRs that are in a good shape (i.e. following the pull request checklist) are easier for maintainers to review and are 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, in line with the QRMI Code of Conduct.

Documentation #

Documentation contributions are welcome. When modifying public APIs, examples, configuration files, or user-facing behaviour, please update the relevant documentation as part of the same pull request.

Refer to Adding Documentation for further guidance.

Testing #

Once you’ve made a code change, it is important to verify that it doesn’t break any existing tests and that newly added tests run successfully. Before you open a new pull request for your change, run QRMI’s Python test suite. If you’ve modified native code, you should also run its Rust-based unit tests.

More information about QRMI’s testing suite is available in our testing documentation.

Running unit tests #

pytest offers the easiest way to run QRMI’s Python test suite.

You can install pytest using pip:

pip install -U pytest

To run QRMI’s Python test suite:

pip install "$(ls ./target/wheels/qrmi-*.whl)[ibm,pasqal]"
pytest .

Many of QRMI’s core data structures and code are implemented in Rust.

cargo test is responsible for Rust unit testing. Rust tests are integrated directly into the Rust file being tested within a tests module. Functions within these modules decorated with #[test] are built and run as tests.

#[cfg(test)]
mod tests {
   #[test]
   fn my_first_test() {
      assert_eq!(2, 1 + 1);
   }
}

For more detailed information on how to write Rust tests, you can refer to the Rust documentation’s guidance on writing tests.

To execute the tests with the makefile, a make test target is available. The execution of the tests (both via the make target and during manual invocation) takes into account the LOG_LEVEL environment variable.

Style and linting #

Contributors must run the below commands to fix and verify any formatting issues prior to submitting a PR:

Fix any formatting issues:

. ~/.cargo/env
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cd examples/rust
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings

QRMI uses rustfmt for Rust formatting and linting. You can run cargo fmt (if you installed Rust with the default settings using rustup), and it will automatically update the code formatting according to the style guidelines.

For lint checking, QRMI uses clippy which can be invoked using cargo clippy.

Execute the following commands:

source ~/py312_qrmi_venv/bin/activate
cd examples
pylint ./python
black --check ./python

QRMI uses two tools for Python code formatting and lint checking. The first tool is black which is a code formatting tool that will automatically update the code formatting to a consistent style.

The second tool is pylint, which is a code linter capable of deeper analysis of the Python code to find both style issues and potential bugs and other common issues.

Preparing a new release #

Certain files will need to be updated for a new release. Please refer to our release and deploymeny guide for guidance on preparing a new release.

Help and Support #

If you require support, our help and support documentation provides up-to-date links to further guidance and our communication channels. Please don’t hesitate to get in touch!