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 (PR title + changelog decision validation)
   • 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 and Changelog Decision Tags

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

2. This workflow contains two jobs:

   • conventional-commit: validates PR title against allowed Conventional Commit types.
   • changelog-decision: validates PR body contains exactly one of changelog: include or changelog: skip.

3. Enforce these allowed types:

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

4. Keep scope optional.

5. 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.

6. Update CLAUDE.md to require Conventional Commit style PR titles and changelog decision tags. 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`.
   
   Every PR body must contain exactly one of `changelog: include` or `changelog: skip`. This is enforced by CI.
   

   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. Customize the generated config following references/git-cliff-and-changelog-flow.md:

   • Replace commit_parsers with the robust version that checks message, body, and footer for changelog tags, uses case-insensitive word-boundary regexes, and matches full Conventional Commit syntax with optional scope and !.
   • Set filter_unconventional = true and filter_commits = true.
   • Update the body template to strip changelog: include / changelog: skip from rendered entries.
   • Use distinct group names: "Added" for feat, "Fixed" for fix, "Performance" for perf, "Reverted" for revert.
   • Include by default: feat, fix, perf, revert.
   • Skip by default: refactor, style, test, chore, ci, docs, doc.
   • Parser order matters: changelog: skip overrides first, then type-based grouping, then changelog: include as a rescue for otherwise-skipped types. The include rules must NOT come before the type rules — every PR body carries a changelog tag (CI-enforced), so an early include rule would group every commit under "Changed".
   • 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 and changelog decision tag validation are in .github/workflows/conventional-commit-pr-title.yml.
   • Every PR body must contain exactly one of changelog: include or changelog: skip.
   • Changelog generation uses git-cliff and root CHANGELOG.md.
   • Override tag behavior for changelog: include / changelog: skip.
   • A Release Notes section documenting the release-notes/X.Y.Z.md convention: custom release commentary can be added by creating this file before cutting a release; its contents are inserted into CHANGELOG.md between the version heading and the auto-generated entries as part of the changelog generation step.
   • 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|changelog-decision|github-script' .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|release-notes/' 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