references/rust.md
Rust Release Practices
Use cargo for everything: building, testing (cargo test), formatting
(cargo fmt), linting (cargo clippy), and documentation (cargo doc).
Toolchain and edition
- Prefer the latest stable compiler and the latest edition for new code.
- If older-compiler support matters, declare it explicitly with
package.rust-versioninCargo.tomland test that version in CI.
Crate-level lints
Add these to lib.rs/main.rs before release:
#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links)]
forbid(unsafe_code)prevents directunsafe(transitive uses through dependencies are still allowed). Omit only for crates that genuinely needunsafe, and isolate those blocks with// SAFETY:comments.deny(missing_docs)fails the build when a public API lacks a rustdoc comment.- Optionally forbid explicit panics in library code with
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]— but note panics are often appropriate; apply this only where callers needResult-based error handling throughout.
Supply-chain checks
cargo auditin CI flags dependencies with known advisories.cargo denyadditionally enforces license and source policies on the dependency tree — useful for catching a copyleft dependency slipping into a permissively licensed project.
Publishing to crates.io
- Use crates.io trusted publishing (OIDC from GitHub Actions) instead of long-lived API tokens.
cargo releasemanages version bumps, tagging, and pushing. A common configuration inCargo.toml, with the actual publish performed by CI:
[package.metadata.release]
publish = false # handled by GitHub Actions
push = true
- Set
license(SPDX expression),description,repository, anddocumentationinCargo.toml; crates.io and docs.rs surface these directly. docs.rs builds documentation automatically on publish.
Binary distribution
For tools with end-user binaries, use cargo-dist or goreleaser to build multi-platform release artifacts and installers from CI on each tag.