Skip to content

po4yka/rust-skills / skills/rust-crate-release

rust-crate-release

Verified

Use when preparing to publish a Rust crate or a Rust binary release, or recovering from a bad one - deciding a SemVer bump or MSRV change, checking cargo package and cargo publish output, ordering a workspace publish, setting up crates.io trusted publishing, deciding whether to yank a crate version, building a release archive with a release checksum, release SBOM, and attestation, or using cosign to sign release artifacts.

Rust Crate Release

A release has two independent modes: the registry mode publishes a source .crate, and the binary mode distributes built assets. An authorization for one mode does not authorize the other.

Safety rules

Published versions and uploaded assets are permanent, so these rules have no exception:

  • Get explicit authorization before each external write. Name the exact package, version, registry, tag, asset, or account. External writes are: cargo publish, a commit or tag push, creating, editing, or finalizing a hosted release, an asset upload, signing or attestation, cargo yank and --undo, cargo owner changes, crate deletion, and crate settings such as a trusted publisher.
  • Never add --allow-dirty or --no-verify to make a release pass. Both publish bytes that no check saw.
  • Never put a registry token on the command line or in a log: history and CI logs keep it. If a token leaks, revoke it at once and create a new scoped token (crates.io: https://crates.io/settings/tokens).
  • Never reuse a version after a partial or timed-out publish. The upload can have completed.
  • Never release a different commit under an existing version, and never replace a named asset with different bytes. Users and caches already trust the first bytes.

Local checks, cargo package, and cargo publish --dry-run write nothing external. Run them before you ask for authorization.

Failure triage

SymptomLikely causeFix
cargo info output says (from ./...)No --registry, so Cargo describes the local memberPass --registry <registry> and read the result again
A file is missing from the archive, or archive tests fail with E0432 or E0433include/exclude, an ignore rule, a path-only dev-dependency, or an undeclared build inputFollow the triage table in the package-inspection reference
Dry run selects the wrong packageWorkspace defaults or the current directory select another memberPass -p <package> and --registry
docs.rs build fails or lacks a platform APIFeature, target, native dependency, or sandbox differenceFix [package.metadata.docs.rs] or the build behavior, then release a new version if required
A binary digest, upload, or signature check failsSee the binary referenceStop; follow its triage table

Completion report

Report: the published or prepared status of each mode; package, version, registry, commit, and tag; the SemVer and MSRV decision with evidence; the exact checks and observed results; package contents and archive size; for binaries, the target matrix, asset names, checksums, SBOM, provenance, signature status, and the consumer verification of every downloaded asset; the registry and docs.rs result; every external action; remaining risks and blocked checks.

Do not report a release as complete when only a dry run passed, or as failed only because the client timed out.

Release inputs

Read references/release-inputs-and-metadata.md first: it lists the inputs, the evidence each needs, and the read-only checks, which end with cargo metadata --locked --no-deps --format-version 1.

Stop if the candidate worktree is dirty. Use a clean worktree at the candidate commit when other work must stay in place. --locked needs a committed Cargo.lock, libraries included.

Read the repository release policy, CI config, README, changelog, and recent tags. Do not invent a tag prefix or changelog format.

1. Compare the published base with the candidate

Use the previous release tag as the base:

git diff --stat <previous-release-tag>..HEAD
git log --oneline <previous-release-tag>..HEAD

For a first release, review the complete public surface as the initial contract.

Inspect every change to the user contract, not only lines with pub: the checklist is in references/compatibility.md. Mark a public enum that downstream code matches #[non_exhaustive] in its first release.

2. Classify the version change

Apply the repository policy first, then the Cargo SemVer guide and the classification table in references/compatibility.md.

For 0.y.z, y is the breaking position. Choose the larger bump for a possibly breaking change unless policy and downstream evidence support a smaller one. Record the classification and its evidence in the release notes.

Run cargo semver-checks -p <package> --baseline-version <previous-version>; the reference has the install, the other-registry form, and the limits. Treat a reported break as real. A clean result does not prove compatibility: it does not check behavior, documented panics, or every macro change. If the tool cannot run, report the API diff as not run.

3. Verify MSRV, features, and targets

Keep the documented MSRV equal to the rust-version that CI verifies.

rustup toolchain install <msrv> --profile minimal
cargo +<msrv> test --locked -p <package> --all-targets
cargo +<msrv> test --locked -p <package> --doc

Run each --doc line only when the package has a library target. Below MSRV 1.96.1, vendor a third-party registry or SSH git source with a newer Cargo and add --offline to each MSRV command (the rust-security skill owns the rule).

When the MSRV build fails, find the cause before you raise the MSRV. Never run a full cargo update as the fix: it moves every dependency just before publish. Read the cause and fix table in references/compatibility.md when the MSRV build fails or a workspace has several MSRVs.

Test the smallest feature matrix that covers each supported state (the commands are in the reference), and every supported target in CI. A host-only build does not prove target support.

4. Check manifest and documentation metadata

Read the [package] and docs.rs sections of the inputs reference when you write or review these tables. Since 2026-05-01, docs.rs builds only the default target unless [package.metadata.docs.rs] lists targets; list them when the public API differs by target.

5. Prepare the version and changelog

Update only the authoritative version field and respect workspace inheritance. Write the changelog from the release diff, with breaking, MSRV, feature, and platform changes and migration steps.

The archive must come from a clean release commit that holds only the version, lockfile, changelog, and other release files. Land that commit on the remote default branch, with its own authorization, before any publish: .cargo_vcs_info.json records its SHA in the registry forever.

git diff --cached --check
git diff --cached

Confirm that the version is free with cargo info <package>@<version> --registry <registry> (always pass --registry, also for crates.io). Only error: could not find proves it is free; a timeout or an authentication error does not.

6. Run repository gates

Run the repository's canonical format, lint, test, and build commands. Without them, run:

cargo fmt --all --check
cargo clippy --locked -p <package> --all-targets --all-features -- -D warnings
cargo test --locked -p <package> --all-targets --all-features
cargo test --locked -p <package> --doc --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked -p <package> --all-features --no-deps

Replace --all-features with the documented valid sets when features conflict. Keep the --doc line for a library target: --all-targets does not run doctests. Run the advisory gate (cargo deny --config deny.toml --locked check advisories, or else cargo audit), or report it as not run. A .crate carries Cargo.lock, and cargo install --locked builds with it, so a vulnerable locked dependency reaches binary users. Run the MSRV and target checks after the final version change. A green CI run for a different commit is not release evidence.

7. Inspect the exact package

List the files, review the list for missing inputs and for secrets and private keys, then create and verify the archive:

cargo package --locked -p <package> --registry <registry> --list
cargo package --locked -p <package> --registry <registry>
cargo publish --locked -p <package> --registry <registry> --dry-run

Both must pass as written (see Safety rules). cargo package verifies only that the library and binaries build. Read references/package-inspection.md when you review the file list, inspect the .crate, or test the packaged source.

8. Distribute binary artifacts

Read references/binary-distribution.md when users download prebuilt executables, libraries, installers, or firmware. Report each mode separately.

9. Handle workspace release order

Read references/workspace-publish.md when the release publishes more than one workspace package: multi-package cargo publish is not atomic.

10. Request authorization and publish

Choose one channel per version: a direct local cargo publish, tagged only after the registry shows the version, or a CI workflow that a tag push or dispatch starts, with no local publish.

For crates.io from GitHub Actions or GitLab.com, prefer Trusted Publishing to a stored token. Read references/trusted-publishing.md when you write or review a publish workflow or change the crate's publisher settings.

With the authorization request, present the completion-report facts so far, the changelog summary, and the exact command: cargo publish --locked -p <package> --registry <registry>, or the exact tag push that starts the workflow.

After approval, run git status --short and git rev-parse HEAD again. Stop if either differs from the approved candidate, or if git fetch origin && git merge-base --is-ancestor HEAD origin/<default-branch> fails. Run the approved command once. If it times out, check the registry until the result is known, then stop the release chain; an immediate negative cargo info does not prove a failure.

11. Verify the registry and tag the source

Run the same cargo info command. Confirm that the version line names no local (from ./...) path, and that docs.rs built: a docs.rs failure is a release defect. For a direct release, tag the exact published commit. For a CI release, confirm that the pushed tag points to the approved candidate, and create no second tag. Use the repository's prefix and annotated-tag convention:

git tag -a <tag> -m "Release <package> <version>"
git show --no-patch --decorate <tag>

Get authorization before you push the tag. Never move an existing tag; if the remote tag exists at another commit, stop. The release is complete only when the registry version and the remote tag both match the approved source.

12. Recover from a bad release or change owners

If a secret entered the archive, revoke the secret first: a yank or a deletion does not remove it. Read references/recovery.md when you consider a yank, a crate deletion, an owner change, or a RustSec advisory for your own release; each needs its own authorization.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall