Merge branch 'main' into patch-2

.github/workflows/miri.yml

@@ -0,0 +1,46 @@
+name: Miri
+on:
+  push:
+  pull_request:
+concurrency:
+  group: ${{ github.repository }}-${{ github.ref }}-${{ github.head_ref }}-${{ github.workflow }}
+  # Only cancel in PR mode.  In push mode, don't cancel so we don't see spurious test "failures",
+  # and we get coverage reports on Coveralls for every push.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  miri:
+    if: github.repository_owner == 'Qiskit'
+    name: Miri
+    runs-on: ubuntu-latest
+    env:
+      RUSTUP_TOOLCHAIN: nightly
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: miri
+
+      - name: Prepare Miri
+        run: |
+          set -e
+          # Some of our dependencies aren't Miri-safe with their current release versions.  These
+          # need overriding with known-good versions to run against until the Miri-safe versions are
+          # released and updated in our Cargo.lock.
+          cat >>Cargo.toml <<EOF
+
+          [patch.crates-io]
+          crossbeam-epoch = { git = "https://github.com/crossbeam-rs/crossbeam", rev = "9e859610" }
+          EOF
+          cargo miri setup
+
+      - name: Run Miri
+        run: cargo miri test
+        env:
+          # - `tree-borrows` is required for crossbeam components.
+          # - `symbolic-alignment-check` is extra checking.
+          # - `strict-provenance` is extra checking.
+          MIRIFLAGS: '-Zmiri-tree-borrows -Zmiri-symbolic-alignment-check -Zmiri-strict-provenance'

CONTRIBUTING.md

@@ -556,6 +556,58 @@ you just need to update the reference images as follows:
 
 Note: If you have run `test/ipynb/mpl_tester.ipynb` locally it is possible some file metadata has changed, **please do not commit and push changes to this file unless they were intentional**.
 
+
+### 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
+
+```rust
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn my_first_test() {
+        assert_eq!(2, 1 + 1);
+    }
+}
+```
+
+To run the Rust-space tests, do
+
+```bash
+cargo test --no-default-features
+```
+
+Our Rust-space components are configured such that setting the
+``-no-default-features`` flag will compile the test runner, but not attempt to
+build a linked CPython extension module, which would cause linker failures.
+
+### Unsafe code and Miri
+
+Any `unsafe` code added to the Rust logic should be exercised by Rust-space
+tests, in addition to the more complete Python test suite.  In CI, we run the
+Rust test suite under [Miri](https://github.com/rust-lang/miri) as an
+undefined-behavior sanitizer.
+
+Miri is currently only available on `nightly` Rust channels, so to run it
+locally you will need to ensure you have that channel available, such as by
+```bash
+rustup install nightly --components miri
+```
+
+After this, you can run the Miri test suite with
+```bash
+MIRIFLAGS="<flags go here>" cargo +nightly miri test
+```
+
+For the current set of `MIRIFLAGS` used by Qiskit's CI, see the
+[`miri.yml`](https://github.com/Qiskit/qiskit/blob/main/.github/workflows/miri.yml)
+GitHub Action file.  This same file may also include patches to dependencies to
+make them compatible with Miri, which you would need to temporarily apply as
+well.
+
 ## Style and lint
 
 Qiskit uses three tools for verify code formatting and lint checking. The