Release

Versioning, package contents, support claims, and checks required before publication.

12 items in this guidance cluster.

Tagged guidance

Rust maintainabilityRust maintainability guidance applies the repos software-change preferences to Rust code, APIs, modules, errors, tests, dependencies, documentation, and release risk. It favors Rust that is easy to read locally, hard to misuse, and honest about public behavior.

Verify risky changes with canariesUse staged rollout, shadowing, dry runs, or partial publication for changes that can fail only under real conditions. Canaries reduce blast radius while evidence accumulates.

Align release support claimsKeep crate metadata, docs, changelogs, and support statements saying the same thing. The alignment helps downstream users know which compatibility contract to trust.Keep pre-release compatibility intentionalPreserve pre-release compatibility only when it reflects a chosen contract. Early cleanup is often cheaper than freezing accidental names, re-exports, features, or variants.Release only after artifact validationValidate the actual release artifact before publishing instead of trusting the working tree. This catches missing files, stale generated content, and packaging mistakes while the release can still be fixed.Validate package contents before releaseInspect and build the package users will receive, not just the repository checkout. This catches missing assets, accidental inclusions, README drift, and include/exclude mistakes before publication.Validate semver breaks against external useCheck semver-breaking changes against real examples, dependents, or migration paths before treating an API cleanup as cheap. External evidence informs the cost even when security, soundness, or design repair still justify the break.

Confirm GitHub remote topologyInspect origin, upstream, push remote, PR base, and PR head before publication. Fork and owned-repo layouts differ, so defaults can push or target the wrong repository.Dry run surprising publicationUse dry-run for ambiguous or surprising remote publication, not every routine push. Extra verification pays off when remotes, bookmarks, force-like updates, or PR bases are unclear.

Public API changes have downstream costPublic API edits impose migration, semver, documentation, and integration costs beyond the local diff. Prefer additive paths and explicit migration proof when a break is justified.

Rust API and release checksCargo release, semver, feature, packaging, and minimum-version checks protect downstream users from accidental compatibility changes. Use these checks when public API, crate metadata, or release artifacts are part of the changed surface.Rust tooling profileThe broad Rust tooling profile gathers lints, docs, release, CI, performance, and agent workflow checks in one place. Use it as a menu of mechanical supports, not as a substitute for project-specific risk judgment.