scode-dist-rust-setup

name	scode-dist-rust-setup
description	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.

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