diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4108fa072..44139113f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -365,6 +365,34 @@ There are samples of performance tests under `sdk/core/azure_core/benches` folde To execute the performance tests in `azure_core` folder you can run `cargo bench` in the `sdk/core/azure_core` folder. The output of the tests will be presented in the command line as well as saved under the `target/criterion` folder. +## Releases + +### Versions + +To provide a helpful versioning experience, the Azure SDK for Rust libraries follow conventions similar to other Azure SDKs. + +Release builds will fail if a library depends on another Azure SDK for Rust library which has not been released and is not included in the current release build. + +#### Workspace dependencies + +The root `Cargo.toml` file represents released versions of crates which can be used by other Azure SDK for Rust libraries. To use a released version of a library, use `workspace = true` in your library's `Cargo.toml`. + +```toml +azure_core = { workspace = true } +``` + +If an SDK library depends on an unreleased SDK library, specify that dependency using a path-based dependency (`version` is required for the library to release): + +```toml +azure_core = { path = "../../core/azure_core", version = "0.31.0" } +``` + +#### Version increment on release + +When a release to crates.io completes, the Engineering System opens a pull request to increment versions of released packages. This PR should be merged as soon as possible to put the `main` branch in a "releasable" state and to provide context that code at the HEAD of `main` may not reflect code in a previously released version of a library. + +The incremented version will be a "beta" of an incrementally higher release. This incremented version in the PR is a placeholder. The version can be updated in another PR to reflect the intended release version. + ## Samples ### Third-party dependencies diff --git a/doc/checks.md b/doc/checks.md new file mode 100644 index 0000000000..d7773a7008 --- /dev/null +++ b/doc/checks.md @@ -0,0 +1,103 @@ +# Engineering System checks + +These checks run in addition to logic tests. + +## Standard checks + +The Engineering System provides a set of [standard checks](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/1215/Source-and-Artifact-scans-and-checks). + +## Rust-specific checks + +### Checks included in `cargo` + +The following checks are included in the Rust toolchain or are part of cargo. + +#### Audit + +Documentation: [cargo-audit](https://github.com/rustsec/rustsec/tree/main/cargo-audit) + +Runs in: [Analyze-Code.ps1](https://github.com/Azure/azure-sdk-for-rust/blob/main/eng/scripts/Analyze-Code.ps1) + +``` +cargo audit +``` + +#### Fmt + +Documentation: [cargo-fmt](https://doc.rust-lang.org/cargo/commands/cargo-fmt.html) + +Runs in: [Analyze-Code.ps1](https://github.com/Azure/azure-sdk-for-rust/blob/main/eng/scripts/Analyze-Code.ps1) + +``` +cargo fmt +``` + +#### Clippy + +Documentation: [cargo-clippy](https://doc.rust-lang.org/cargo/commands/cargo-clippy.html) + +Runs in: [Analyze-Code.ps1](https://github.com/Azure/azure-sdk-for-rust/blob/main/eng/scripts/Analyze-Code.ps1) + +``` +cargo clippy +``` + +#### Check + +> [!NOTE] +> This only runs against `azure-core` and not against other packages in the build + +Documentation: [cargo-check](https://doc.rust-lang.org/cargo/commands/cargo-check.html) + +Runs in: [Analyze-Code.ps1](https://github.com/Azure/azure-sdk-for-rust/blob/main/eng/scripts/Analyze-Code.ps1) + +``` +cargo check +``` + +#### Doc + +Documentation: [cargo-doc](https://doc.rust-lang.org/cargo/commands/cargo-doc.html) + +Runs in: [Analyze-Code.ps1](https://github.com/Azure/azure-sdk-for-rust/blob/main/eng/scripts/Analyze-Code.ps1) + +``` +cargo doc +``` + +#### Docs-rs + +Documentation: [cargo-docs-rs](https://github.com/dtolnay/cargo-docs-rs) + +Runs in: [Analyze-Code.ps1](https://github.com/Azure/azure-sdk-for-rust/blob/main/eng/scripts/Analyze-Code.ps1) + +``` +cargo install --locked cargo-docs-rs +cargo +nightly docs-rs +``` + +### Checks installed as tools + +Additional checks can be installed as tools by `cargo install` and run in relevant parts of the build system. + +### Deny + +Documentation: [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) + +Runs in [Analyze-Code.ps1](https://github.com/Azure/azure-sdk-for-rust/blob/main/eng/scripts/Analyze-Code.ps1) + +``` +cargo install cargo-deny +cargo deny +``` + +### Semver + +Documentation: [cargo-semver-checks](https://github.com/obi1kenobi/cargo-semver-checks) + +Runs in [Test-Semver.ps1](https://github.com/Azure/azure-sdk-for-rust/blob/main/eng/scripts/Test-Semver.ps1) + +``` +cargo install cargo-semver-checks +cargo semver-checks +```