-
Notifications
You must be signed in to change notification settings - Fork 2.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update contributing guide with more details on Rust process #13170
base: main
Are you sure you want to change the base?
Conversation
As we're using an increasing amount of rust in Qiskit (as of this commit the repository is roughly 17% Rust by lines of code) the CONTRIBUTING.md file was a bit out of date as the guidance on working with Rust was a bit lacking. As an increasing number of code contributors to Qiskit will likely be writing some Rust code updating the guidance to be a bit more clear will be helpful. This commit goes through and expands on some details of working with and contributing Rust code. It also updates some other small details in the guide which were out of date.
One or more of the following people are relevant to this code:
|
Pull Request Test Coverage Report for Build 10909185640Details
💛 - Coveralls |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good, just one small typo / extra word.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
`cargo fmt` to automatically fix update the code formatting. | |
`cargo fmt` to automatically fix the code formatting. |
@@ -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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like how you corrected "rust" to "Rust" in other parts of the document, then introduced some more lower case here lol
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. | |
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). |
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``. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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``. | |
For formatting and lint checking Rust code, you'll need to use different tools than you would for Python. Qiskit uses [rustfmt](https://github.com/rust-lang/rustfmt) for | |
code formatting. You can simply run `cargo fmt` (if you installed Rust with the | |
default settings using `rustup`), and it will update the code formatting automatically to | |
conform to the style guidelines. This is very similar to running `tox -eblack` for Python code. For lint checking, Qiskit uses [clippy](https://github.com/rust-lang/rust-clippy) which can be invoked via `cargo clippy`. | |
Rust lint and formatting checks are included in the the `tox -elint` command. For CI to pass you will need both checks to pass without any warnings or errors. Note that this command checks the code but won't apply any modifications, if you need to update formatting, you'll need to run `cargo fmt`. |
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 | |
Many Rust-accelerated functions are generally tested from Python space, but in cases | |
where new Rust-native APIs are being added, or there are Rust-specific internal details | |
to be tested, `#[test]` functions can be included inline. It's typically most | |
convenient to place these in a separate inline module that is only conditionally | |
compiled in, such as |
@@ -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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
or rust code formatting check) you can use `tox -eblack` and | |
or Rust code formatting check) you can use `tox -eblack` and |
Summary
As we're using an increasing amount of rust in Qiskit (as of this commit the repository is roughly 17% Rust by lines of code) the CONTRIBUTING.md file was a bit out of date as the guidance on working with Rust was a bit lacking. As an increasing number of code contributors to Qiskit will likely be writing some Rust code updating the guidance to be a bit more clear will be helpful. This commit goes through and expands on some details of working with and contributing Rust code. It also updates some other small details in the guide which were out of date.
Details and comments