Release

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

12 items in this guidance cluster.

Tagged guidance

GuideRustPublic APIReader LocalityRust Maintainabilityrust-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.

RuleAgent WorkflowVerificationAutomationVerify Risky Changes With CanariesAGENT-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.

RuleRustDocumentationSource TruthAlign Release Support ClaimsRUST-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.RuleRustPublic APIChange ShapeKeep Pre-Release Compatibility IntentionalRUST-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.RuleRustVerificationRelease Only After Artifact ValidationRUST-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.RuleRustVerificationValidate Package Contents Before ReleaseRUST-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.RuleRustPublic APIVerificationValidate Semver Breaks Against External UseRUST-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.

RuleVCS JJReview HandoffVerificationConfirm GitHub Remote TopologyVCS-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.RuleVCS JJVerificationReview HandoffDry Run Surprising PublicationVCS-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.

PrinciplePublic APIDependenciesRustPublic API Changes Have Downstream Costpublic-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.

MechanismRustPublic APIDependenciesRust API And Release Checksrust-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.MechanismRustToolingAutomationRust Tooling Profilerust-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.