shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

scode-dist-rust-setup

Set up or standardize a Rust repository with cargo-dist release automation, Linux-focused CI with macOS release-plan tag gates, git-cliff changelog generation, Conventional Commit PR title enforcement, and Homebrew publishing to scode/homebrew-dist-tap. Use when creating a new Rust release pipeline or migrating an existing repo to this exact distribution model.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Scode Dist Rust Setup

Set up a Rust repository to match the release/distribution pattern used in juggler: dist-generated release workflow, Homebrew publishing through scode/homebrew-dist-tap, Linux-focused CI, macOS release-plan gating on tags, and git-cliff changelog governance.

Required Inputs

Collect these values before making changes:

  • crate_name: Required. Read from Cargo.toml ([package].name).
  • github_owner/repo: Derive from git remote get-url origin. Prompt only if parsing is ambiguous.
  • cargo_dist_version: Install/update dist first, then pin the discovered version in dist-workspace.toml.

Hard Defaults

Apply these defaults unless the user explicitly asks to diverge:

  • Homebrew tap repository: scode/homebrew-dist-tap
  • Homebrew token secret: HOMEBREW_TAP_TOKEN
  • Homebrew install command namespace: scode/dist-tap/<crate_name>
  • Dist installers: homebrew only
  • Dist targets: aarch64-apple-darwin, x86_64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu
  • Dist plan hook: plan-jobs = ["./release-plan-tests"]
  • CI platform focus: Linux for standard CI, macOS only as tag-gated release-plan test

Workflow

Phase A: Discover Project Facts

  1. Confirm the repository root contains Cargo.toml.
  2. Extract crate_name from Cargo.toml.
  3. Derive github_owner/repo from git remote get-url origin.
  4. Detect existing files that may need updates instead of replacement:
    • dist-workspace.toml
    • .github/workflows/ci.yml
    • .github/workflows/release.yml
    • .github/workflows/release-plan-tests.yml
    • .github/workflows/conventional-commit-pr-title.yml
    • cliff.toml
    • CONTRIBUTING.md
    • README.md

Phase B: Install or Update cargo-dist and Capture Version

  1. Install or update dist using your preferred method.
  2. Capture the version from dist --version.
  3. Pin that exact version string as cargo-dist-version in dist-workspace.toml.
  4. Do not leave cargo-dist-version unpinned.

Phase C: Configure dist-workspace.toml

  1. Create or update dist-workspace.toml using references/dist-workspace-template.md.
  2. Keep these values exact unless the user explicitly asks otherwise:
    • ci = "github"
    • installers = ["homebrew"]
    • install-path = "CARGO_HOME"
    • install-updater = true
    • tap = "scode/homebrew-dist-tap"
    • publish-jobs = ["homebrew"]
    • plan-jobs = ["./release-plan-tests"]
  3. Use the discovered dist version from Phase B for cargo-dist-version.

Phase D: Ensure Cargo.toml is ready for dist

  1. Ensure Cargo.toml has repository = "https://github.com/<owner>/<repo>" — dist requires this for GitHub CI.
  2. Ensure Cargo.toml has description and homepage — Homebrew publishing warns without them.
  3. [profile.dist] will be added automatically by dist init --yes in Phase E.

Phase E: Generate Dist Release Workflow with dist init

dist init --yes is the primary tool for this phase. It:

  • Adds [profile.dist] to Cargo.toml if missing.
  • Reformats dist-workspace.toml with comments (preserving values).
  • Generates .github/workflows/release.yml — this file is dist-managed and must never be hand-edited.

Steps:

  1. Write dist-workspace.toml first (Phase C).
  2. Ensure Cargo.toml has repository, description, homepage (Phase D).
  3. Run dist init --yes to generate everything. The --yes flag auto-accepts defaults (required for non-interactive).
  4. If dist-workspace.toml is changed later, re-run dist init --yes.

Phase F: Install Linux/macOS CI Pattern

  1. Create or update .github/workflows/ci.yml using references/ci-linux-macos-pattern.md.
  2. Keep standard CI Linux-focused.
  3. Keep a macOS job disabled in standard CI for cost control.
  4. Omit Windows baseline jobs unless explicitly requested.

Phase G: Add Release Plan Test Workflow

This file is NOT generated by dist init. It is a manually-maintained reusable workflow that the dist-generated release.yml calls via plan-jobs = ["./release-plan-tests"]. Create it AFTER running dist init (Phase E) so you can verify release.yml references it correctly.

  1. Create or update .github/workflows/release-plan-tests.yml using references/release-plan-tests-template.md.
  2. Run Linux tests on workflow call.
  3. Run macOS tests only when github.ref is a tag ref.
  4. Ensure dist-workspace.toml includes plan-jobs = ["./release-plan-tests"].
  5. Verify the generated release.yml contains a custom-release-plan-tests job that calls this workflow.

Phase H: Enforce Conventional Commit PR Titles

  1. Create or update .github/workflows/conventional-commit-pr-title.yml using references/conventional-commit-pr-title-workflow.md.

  2. Enforce these allowed types:

    • feat, fix, docs, doc, perf, refactor, style, test, chore, ci, revert

  3. Keep scope optional.

  4. Enforce classification policy in repository docs:

    • Type must reflect user-visible behavior, not implementation activity.
    • CLI interface/behavior changes (commands, flags/options, arguments, output contract, exit codes, documented usage) must be feat, fix, or perf (use ! when breaking), not refactor.
    • refactor, style, test, chore, ci, docs, and doc are for non-user-visible changes only.

  5. Update CLAUDE.md to require Conventional Commit style PR titles. Add a section like:

    # PR titles

PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) style. This is enforced by CI
and used by git-cliff for changelog generation.

Allowed types: `feat`, `fix`, `docs`, `doc`, `perf`, `refactor`, `style`, `test`, `chore`, `ci`, `revert`.
Scope is optional. Examples: `feat: add user login`, `fix(parser): handle empty input`.

Type must reflect user-visible behavior, not implementation activity.
CLI interface/behavior changes must be `feat`, `fix`, or `perf` (use `!` when breaking), not `refactor`.

    If CLAUDE.md already has a section about commit messages or PR titles, extend it rather than duplicating.

Phase I: Set Up git-cliff and Release Documentation

  1. If cliff.toml is missing, initialize it with:

    • git cliff --init keepachangelog

  2. If cliff.toml already exists, avoid replacing it with a hardcoded template unless the user explicitly requests that migration.

  3. Keep the config compatible with Conventional Commit-driven changelogs and default it to user-visible entries only.

    • Include by default: feat, fix, perf, revert.
    • Skip by default: refactor, style, test, chore, ci, docs, doc.
    • Parse override tags first: changelog: include forces inclusion, changelog: skip forces exclusion.
    • If both tags are present, changelog: skip wins.

  4. Update CONTRIBUTING.md with:

    • Conventional Commit requirements for commit messages and PR titles.
    • Classification policy: type reflects user-visible behavior; CLI interface changes are never refactor.
    • Note that PR title enforcement is implemented in .github/workflows/conventional-commit-pr-title.yml.
    • Changelog generation uses git-cliff and root CHANGELOG.md.
    • Override tag behavior for changelog: include / changelog: skip.
    • An agent-centric Releasing section using the content from references/release-checklist.md. This section is written as instructions for an AI agent so that a user can say "cut a release" and the agent guides them through the entire version bump, changelog, PR, merge, tag, and release watch flow.

  5. Update CLAUDE.md with a Releasing section that tells agents to follow CONTRIBUTING.md:

    # Releasing

When the user asks to "make a release" or "cut a release", follow the Releasing section of `CONTRIBUTING.md`.

    If CLAUDE.md already has a releasing section, update it rather than duplicating.

Phase J: Wire Homebrew Distribution

  1. Ensure dist config uses tap = "scode/homebrew-dist-tap".
  2. Ensure the repository has secret HOMEBREW_TAP_TOKEN for release publishing.
  3. Verify generated release workflow includes publish-homebrew-formula and checks out scode/homebrew-dist-tap.
  4. Document installation in README.md as:
    • brew install scode/dist-tap/<crate_name>

Verification Checklist

Run these checks after setup:

  1. rg -n 'cargo-dist-version|tap = "scode/homebrew-dist-tap"|plan-jobs' dist-workspace.toml
  2. rg -n '^\[profile\.dist\]' Cargo.toml
  3. rg -n 'custom-release-plan-tests|publish-homebrew-formula|HOMEBREW_TAP_TOKEN' .github/workflows/release.yml
  4. rg -n 'test-linux|test-macos' .github/workflows/release-plan-tests.yml
  5. rg -n 'action-semantic-pull-request|types:' .github/workflows/conventional-commit-pr-title.yml
  6. rg -n 'Conventional Commits|PR titles|Releasing|CONTRIBUTING.md' CLAUDE.md
  7. rg -n 'conventional_commits = true' cliff.toml
  8. rg -n 'git-cliff --tag|CHANGELOG\.md|Conventional Commits|cut a release|bump' CONTRIBUTING.md
  9. rg -n 'brew install scode/dist-tap/' README.md

Resources

Use these files to avoid rewriting long templates:

  • references/dist-workspace-template.md
  • references/ci-linux-macos-pattern.md
  • references/release-plan-tests-template.md
  • references/conventional-commit-pr-title-workflow.md
  • references/git-cliff-and-changelog-flow.md
  • references/release-checklist.md