Running PR checks

This page documents all the checks that run when raising a PR, how to run the corresponding checks locally and how to resolve them.

All the tasks required to run these checks locally are defined using mise tasks. To run all the PR checks locally:

mise run pr-all

test

The GitHub action runs cargo test against the stable rust toolchain.

To run locally

mise run pr-test

This will show details for all failing test cases.

rust-fmt

The GitHub action runs the cargo pr-format alias defined in the .cargo/config.toml file. It checks the code complies with rust fmt.

To run locally

mise run pr-format

This will show details for all formatting issues.

clippy

The GitHub action runs the cargo pr-clippy alias defined in the .cargo/config.toml file. It checks the code complies with rust clippy.

To run locally

mise run pr-clippy

This will show details for all clippy issues.

rustdoc-links

The GitHub action runs cargo doc with additional flags to check that doc links work correctly.

To run locally

mise run pr-rustdoc

This will show details for all doclink issues.

Note: Most of the cargo docs output will be warnings. This might be quite noisey but won’t necessarily fail your PR checks.

spell-check

This uses the typos-cli crate to check all the docstrings, YAML files and READMEs for typos.

To run locally

mise run pr-spell-check

This will print all the typos in the repo to screen.

To fix all these typos automatically

mise run fix-spelling

This will automatically fix all the detected spelling errors locally.

Before committing to main, manually review the diff to check all spelling errors are actually errors and have been fixed correctly.

If there are any detected spelling errors that should be valid, or files that should be ignored, then update the .typos.toml file at the root of the repo.

lint-markdown

This uses the dprint crate lint the markdown files and ensure consistent style and formatting.

To run locally

mise run pr-markdown

This will highlight any issues with the markdown files.

To fix all these issues automatically

mise run format-markdown

Before committing to main, manually review the diff to check all formatting fixes are desired.

Files can be excluded using the dprint.json file at the root of the repo.

doc-types

All documentation pages must have a valid Diataxis type annotation as the first line of the file:

<!-- diataxis-type: <type> -->

The valid types are explanation, howto, reference, and tutorial. This check ensures every page is intentionally categorised.

To run locally

mise run pr-doc-types

This will print the path of any file that is missing or has an invalid annotation.