Software Practices

Dependencies

Third-party code: selection, version bounds, updates, and downstream exposure.

18 items in this guidance cluster.

Tagged guidance

Guide item

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.

Change Shape rules

RuleChange ShapePublic APIReviewabilityAvoid Unnecessary Dependency ChurnCHANGE-AVOID-UNNECESSARY-DEPENDENCY-CHURNKeep package, manifest, and lockfile movement out of unrelated work. Separate dependency changes make build, compatibility, and downstream risk reviewable on their own.

Documentation rules

RuleDocumentationVerificationSource TruthCompare Libraries AccuratelyDOCS-COMPARE-LIBRARIES-ACCURATELYCheck current upstream behavior before comparing nearby libraries or crates. Charitable, source-backed comparisons preserve trust while still helping users choose.

Performance rules

RulePerformanceReviewabilityChange ShapeJustify Complexity, Churn, and DependenciesPERF-JUSTIFY-COMPLEXITY-CHURN-AND-DEPENDENCIESExplain why a performance win justifies added complexity, churn, unsafe code, caching, or dependencies. Measured speedups still need to pay for the maintenance cost every future reader inherits.

Rust rules

RuleRustPublic APIAvoid Public Dependency CouplingRUST-AVOID-PUBLIC-DEPENDENCY-COUPLINGKeep dependency types out of public APIs unless interoperability is the purpose. This preserves semver freedom and avoids forcing downstream users onto implementation choices.RuleRustDocumentationSource TruthCompare Crates by Fit and TradeoffRUST-COMPARE-CRATES-BY-FIT-AND-TRADEOFFCompare adjacent crates by intended fit, scope, and constraints instead of broad superiority claims. This helps users choose without turning docs into brittle marketing.RuleRustPublic APIDo Not Pin Patch VersionsRUST-DO-NOT-PIN-PATCH-VERSIONSKeep manifest requirements as wide as the crate honestly supports. Patch pins belong in Cargo.toml only when code depends on that patchs API, fix, or behavior.RuleRustDocumentationPublic APIDocument Feature ContractsRUST-DOCUMENT-FEATURE-CONTRACTSExplain what each feature flag enables, requires, and promises. Feature contracts help users choose combinations without guessing from dependency names.RuleRustVerificationKeep Compatible Updates in LockfileRUST-KEEP-COMPATIBLE-UPDATES-IN-LOCKFILELet lockfiles record newer compatible dependency versions when the manifest floor has not changed. This tests fresh releases without narrowing downstream compatibility.RuleRustChange ShapeReviewabilityKeep Dependency Updates IntentionalRUST-KEEP-DEPENDENCY-UPDATES-INTENTIONALSeparate maintenance-only dependency refreshes from updates that change behavior, features, MSRV, or integration. Reviewable grouping lowers noise without hiding downstream risk.RuleRustPublic APIBoundary CorrectnessMake Feature Flags Additive Where PossibleRUST-MAKE-FEATURE-FLAGS-ADDITIVE-WHERE-POSSIBLEDesign feature flags as additive capabilities whenever possible so Cargo feature unification does not surprise downstream builds. Make incompatible combinations explicit when addition cannot model the real choice.RuleRustTestingVerificationRun Feature Gated ValidationRUST-RUN-FEATURE-GATED-VALIDATIONExercise the feature combinations touched by a Rust change so gated code, docs, and integrations actually build. Choose representative combinations when exhaustive feature matrices would be too expensive.RuleRustPublic APIDocumentationTie Optional Dependencies To Named FeaturesRUST-TIE-OPTIONAL-DEPENDENCIES-TO-NAMED-FEATURESConnect optional dependencies to clear feature names that explain the capability callers enable. Avoid leaking dependency names as the public feature design when the capability needs a more stable contract.RuleRustPublic APIVerificationUse Honest Minimum DependenciesRUST-USE-HONEST-MINIMUM-DEPENDENCIESSet dependency requirements to the lowest compatible versions the crate actually supports. Raise minimums only for required APIs, fixes, features, security needs, or MSRV interactions.

Testing rules

RuleTestingRustVerificationValidate Declared Minimum Dependency VersionsTEST-VALIDATE-DECLARED-MINIMUM-DEPENDENCY-VERSIONSCheck that declared minimum dependency versions still build the supported behavior. Lockfile tests can hide newer API usage, so use targeted minimal-version checks when needed.

Pattern item

PatternPublic APIRustChange ShapeKeep Public Dependencies Intentionalkeep-public-dependencies-intentionalPublic dependencies shape downstream compatibility, API expectations, and maintenance cost. Add or raise them only when the public behavior needs that requirement, using lockfile updates for ordinary compatible refreshes.

Principle item

PrinciplePublic APIReleaseRustPublic 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.

Mechanism item

MechanismRustPublic APIReleaseRust 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.