diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53043ffaa28..ebc8f6ffc3f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,8 +53,6 @@ from system-wide packages. This way, we avoid inadvertently becoming dependent o 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 @@ -107,17 +105,17 @@ pip install -e . 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 +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 +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). +[rustup documentation](https://rust-lang.github.io/rustup/installation/windows-msvc.html). If you use Rustup, it will automatically install the correct Rust version currently used by the project. @@ -145,7 +143,7 @@ Python gate objects when accessing them from a `QuantumCircuit` or `DAGCircuit`. This makes a tradeoff between runtime performance for Python access and memory overhead. Caching gates will result in better runtime for users of Python at the cost of increased memory consumption. If you're working with any custom -transpiler passes written in python or are otherwise using a workflow that +transpiler passes written in Python or are otherwise using a workflow that repeatedly accesses the `operation` attribute of a `CircuitInstruction` or `op` attribute of `DAGOpNode` enabling caching is recommended. @@ -187,8 +185,8 @@ please ensure that: which will run these checks and report any issues. If your code fails the local style checks (specifically the black - code formatting check) you can use `tox -eblack` to automatically - fix update the code formatting. + or rust code formatting check) you can use `tox -eblack` and + `cargo fmt` to automatically fix update the code formatting. 2. The documentation has been updated accordingly. In particular, if a function or class has been modified during the PR, please update the *docstring* accordingly. @@ -396,11 +394,6 @@ 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]( -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 documentation @@ -572,10 +565,11 @@ Note: If you have run `test/ipynb/mpl_tester.ipynb` locally it is possible some ### Testing Rust components -Rust-accelerated functions are generally tested from Python space, but in cases -where there is Rust-specific internal details to be tested, `#[test]` functions -can be included inline. Typically it's most convenient to place these in a -separate inline module that is only conditionally compiled in, such as +Many Rust-accelerated functions are generally tested from Python space, but in cases +where new Rust-native APIs are being added or there is Rust-specific internal details +to be tested, `#[test]` functions can be included inline. Typically it's most +convenient to place these in a separate inline module that is only conditionally +compiled in, such as ```rust #[cfg(test)] @@ -587,6 +581,10 @@ mod tests { } ``` +For more detailed guidance on how to add Rust testing you can refer to the Rust +documentation's [guide on writing tests](https://doc.rust-lang.org/book/ch11-01-writing-tests.html) +for more details and suggestions. + To run the Rust-space tests, do ```bash @@ -652,6 +650,20 @@ 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. +### Rust style and lint + +If you're working on Rust code the Rust formatting and lint checking are done +using different tooling. Qiskit uses [rustfmt](https://github.com/rust-lang/rustfmt) for +code formatting, and you can simply run `cargo fmt` (if you installed Rust with the +default settings using `rustup`) and it will update the code formating automatically to +conform to the style guidelines. This is very similar manner to what `black` and running +`tox -eblack` for Python code. For lint Qiskit uses [clippy](https://github.com/rust-lang/rust-clippy) +which can be invoked via `cargo clippy`. For CI to pass you will need clippy to pass +without any warnings or errors. + +These still get checked via the tox lint commands but if you need to update formating +you'll need to run ``cargo fmt``. + ## Building API docs locally @@ -733,7 +745,7 @@ developers to test the release ahead of time. When the pre-release is tagged the automation will publish the pre-release to PyPI (but only get installed on user request), create the `stable/*` branch, and generate a pre-release changelog/release page. At this point the `main` opens up for development of the next release. The `stable/*` -branches should only receive changes in the form of bug fixes at this point. If there +branches should only receive changes in the form of bug fixes at this point. If there is a need additional release candidates can be published from `stable/*` and when the release is ready a full release will be tagged and published from `stable/*`.