microsoft/ox-tools

microsoft/ox-tools

Description: Collection of CI tools for Rust Workflows

Language: Rust

License: MIT

Stars: 9

Forks: 0

Open issues: 1

Created: 2026-03-10T18:22:33Z

Pushed: 2026-06-10T18:56:46Z

Default branch: main

Fork: no

Archived: no

README:

This repository contains a set of tools that help you build robust highly scalable services in Rust.

• [Crates](#crates)
• [About this Repo](#about-this-repo)
• [Adding New Crates](#adding-new-crates)
• [Publishing Crates](#publishing-crates)
• [Documenting Crates](#documenting-crates)
• [CI Workflows](#ci-workflows)
• [Pull Request Gates](#pull-request-gates)
• [Tool Versions](#tool-versions)
• [Trademarks](#trademarks)

Crates

These are the primary crates built out of this repo:

• [cargo-coverage-gate](./crates/cargo-coverage-gate/README.md) - A cargo subcommand that gates pull requests on per-package line coverage measured by cargo-llvm-cov
• [cargo-heather](./crates/cargo-heather/README.md) - A cargo sub-command to validate license headers in Rust, TOML, PowerShell, Just, and env source files

About this Repo

The following sections explain the overall engineering process we use in this repo.

To set up a local PC environment capable of exercising all the tooling used by this repo's development processes, you can follow the guide in [DEVELOPMENT.md](./DEVELOPMENT.md).

Adding New Crates

Adding a new crate to this repo is done by running the scripts\add-crate.ps1 script. It will prompt you for a few bits of state, and then will get everything wired up that needs to be.

The add-crate script does the following:

• Adds an entry for the crate to the [Crates](#crates) section in this README file.

• Adds an entry for the crate to the top-level [CHANGELOG.md](./CHANGELOG.md) file.

• Prepares a README.md file for the crate, setup for use with [

cargo-doc2readme](https://crates.io/crates/cargo-doc2readme) with a set of appropriate CI badges.

• Creates an empty CHANGELOG.md file for the crate, which will later get populated by the scripts\release-crate.ps1

script.

• Creates placeholder logo.png and favicon.ico files for the crate, which you're expected to replace with legit

crab-themed logo and icon.

Publishing Crates

Releasing new versions of crates to crates.io is handled by an internal Microsoft automation process. To release a new version of any crate, follow this simple process:

1. Make sure the changes you want to release have all been committed to the repo.

2. Create a branch off of main.

3. Run ./scripts/release-crate.ps1 [new_version] to bump a crate's version and update the crate's CHANGELOG.md file. Run the script many times if you want to release several crates in the same PR.

4. Create a PR like normal to push changes out.

Once your PR is merged, automation will kick in. It will tag the commit and push the crate to crates.io.

Documenting Crates

We want our crates to have world-class documentation such that our customers can enjoy discovering and using our features. We expect our Rust code to be fully documented in the normal Rust way, and we introduce two doc-related automation processes:

• The README.md file in each crate's directory is auto-generated from the crate-level documentation.

We use the `cargo-doc2readme` tool which reads the crate docs, resolves intra-doc links, and generates the README.md file using a shared template. A pull request gate ensures the README.md file always reflects the latest crate documentation.

• The CHANGELOG.md file in each crate's directory is auto-generated from the commits to a crate's directory by the

scripts/release-crate.ps1 script.

To generate documentation locally with all features enabled (including feature-gated items), run:

just docs

This requires the Rust nightly toolchain to be installed. The script will generate documentation and open it in your default browser.

CI Workflows

We have two primary workflows:

• main. Runs on all pull requests and commits to the main branch. This

performs quite a bit of validation to ensure high-quality outcomes. Any issues found by this workflow blocks the pull request from being merged.

• nightly. Runs nightly on the main branch. This executes repo-wide mutation testing

(as opposed to the main workflow which does incremental testing). Any issues found by this workflow result in an issue being opened reporting the problem.

Pull Request Gates

We strive to deliver high-quality code and as such, we've put in place a number of PR gates, described here:

• Build. We build all the crates in the repo for Windows and Linux.

We use `cargo-hack` to iterate through different crate feature combinations to make sure everything builds properly.

• Testing. We run cargo nextest --all-features to run every normal test and documentation test in the repo.

• Code Coverage. We calculate code coverage for the whole repo using [

cargo-llvm-cov](https://crates.io/crates/cargo-llvm-cov). We capture coverage for Windows and Linux, with --all-features and --no-features. Coverage is collected using the nightly Rust compiler which makes it possible to use coverage(off) annotations in the source code to suppress coverage collection for a chunk of code. We require 100% coverage for any checked in code.

• Mutation Testing. We use `cargo-mutants` to help maintain

high test quality.

• Source Linting. We run Clippy with most warnings enabled and all treated as errors.

• Doc Linting. We lint documentation to help find bad links and other anti-patterns.

• Source Formatting. We ensure the source code complies with the Rust standard format.

• Cargo.toml Formatting. We use `cargo-sort` to keep Cargo.toml

files in a consistent format and layout.

• Unsafe Verification. We use Miri and `cargo-careful` to verify that our

unsafe code doesn't induce undefined behaviors.

• External Type Exposure. We use `cargo-check-external-types` to track

which external types our crates depend on. Exposing a 3P type from a crate creates a coupling between the crate and the exporter of the type which can be problematic over time. This check is there to prevent…