cargo-rail: preparing for asciinema demos

Author: loadingalias

.gitignore

@@ -21,15 +21,11 @@ AGENTS.md
 *.key
 
 # Documentation
-docs/design-no_op-experimental
 rules.md
-ARCHITECTURE.md
 style.md
-demos/
-test.md
-examples/RECORDING_TEMPLATE.md
-examples/issues.md
-commands_check.md
+examples/split-recording-guide.txt
+examples/unify-recording-guide.txt
+examples/release-recording-guide.txt
 
 # Cargo-Rail (Testing)
 *rail.toml

examples/release/README.md

@@ -0,0 +1,45 @@
+# release demo
+
+Demonstrates release validation and planning using tikv (70+ component workspace).
+
+## Workflow
+
+```bash
+cargo rail init                              # Base config
+cargo rail release init tikv                 # Configure crate for release
+cargo rail release check tikv                # Basic validation
+cargo rail release check tikv --extended     # Full validation (dry-run, MSRV)
+cargo rail release run tikv --check          # Preview release plan
+cargo rail release run tikv --bump minor     # Execute minor release
+```
+
+## Config
+
+```toml
+[release]
+tag_prefix = "v"
+tag_format = "{crate}-{prefix}{version}"
+require_clean = true
+publish_delay = 5
+create_github_release = false
+require_changelog_entries = false
+
+[crates.tikv.release]
+publish = false
+```
+
+| Option | Value | Why |
+|--------|-------|-----|
+| `tag_format` | `{crate}-{prefix}{version}` | Produces `tikv-v9.0.1` style tags |
+| `require_clean` | `true` | Enforce clean git state |
+| `create_github_release` | `false` | Skip gh CLI for demo |
+| `publish` | `false` | tikv isn't published to crates.io |
+
+## What this shows
+
+- `cargo rail release init` - Configure a crate for release
+- `cargo rail release check` - Basic validation
+- `cargo rail release check --extended` - Full dry-run + MSRV check
+- `cargo rail release run --check` - Preview release plan
+- `--bump patch/minor/major` - Version bump options
+- `--skip-publish` - Tag-only releases

examples/split/README.md

@@ -0,0 +1,39 @@
+# split/sync demo
+
+Demonstrates crate extraction with git history preservation using ruff's `ruff_cache` crate.
+
+## Workflow
+
+```bash
+cargo rail init                        # Base config
+cargo rail split init ruff_cache       # Configure crate for split
+cargo rail split run ruff_cache --check  # Preview
+cargo rail split run ruff_cache        # Execute split
+cargo rail sync ruff_cache --check     # Preview sync
+```
+
+## Config
+
+```toml
+[crates.ruff_cache.split]
+remote = "/tmp/ruff-split-test"
+branch = "main"
+mode = "single"
+paths = [{ crate = "crates/ruff_cache" }]
+include = ["LICENSE"]
+```
+
+| Option | Value | Why |
+|--------|-------|-----|
+| `remote` | `/tmp/...` | Local path for demo (use git URL in production) |
+| `mode` | `single` | One crate per split repo |
+| `paths` | `[{ crate = "..." }]` | Crate location in monorepo |
+| `include` | `["LICENSE"]` | Extra files to copy |
+
+## What this shows
+
+- `cargo rail split init` - Configure a crate for splitting
+- `cargo rail split run --check` - Preview before executing
+- `cargo rail split run` - Extract crate with full git history
+- `cargo rail sync --to-remote` - Push monorepo changes to split
+- `cargo rail sync --from-remote` - Pull split repo changes back

examples/unify/helix-db/README.md

@@ -0,0 +1,28 @@
+# helix-db unify demo
+
+Emerging graph database workspace (6 crates). Demonstrates unification on a growing project.
+
+## Config choices
+
+```toml
+[unify]
+msrv = true
+detect_unused = true
+remove_unused = true
+prune_dead_features = true
+strict_version_compat = true
+```
+
+| Option | Value | Why |
+|--------|-------|-----|
+| `msrv` | true | Compute MSRV as project matures |
+| `detect_unused` | true | Keep deps clean during rapid development |
+| `remove_unused` | true | Auto-clean unused deps |
+| `prune_dead_features` | true | Remove feature cruft |
+| `strict_version_compat` | true | Safe defaults for new project |
+
+## What this shows
+
+- cargo-rail on a small, actively developed workspace
+- Clean unification for projects heading toward v1
+- Standard workflow: init → check → unify → verify

examples/unify/polars/README.md

@@ -0,0 +1,37 @@
+# polars unify demo
+
+Large data processing workspace (50+ crates, pyo3 bindings). Aggressive settings.
+
+## Config choices
+
+```toml
+targets = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
+
+[unify]
+msrv = true
+detect_unused = true
+remove_unused = true
+prune_dead_features = true
+pin_transitives = true
+transitive_host = "root"
+strict_version_compat = false
+major_version_conflict = "bump"
+```
+
+| Option | Value | Why |
+|--------|-------|-----|
+| `msrv` | true | Compute floor for edition 2024 workspace |
+| `detect_unused` | true | Find orphaned deps in large workspace |
+| `remove_unused` | true | Auto-clean |
+| `prune_dead_features` | true | Many optional features across crates |
+| `pin_transitives` | true | **Key demo**: workspace-hack replacement |
+| `transitive_host` | root | Pin transitives in root Cargo.toml |
+| `strict_version_compat` | false | Allow version flexibility |
+| `major_version_conflict` | bump | Force highest resolved version |
+
+## What this shows
+
+- Handling large workspace with 50+ crates
+- `pin_transitives` as cargo-hakari replacement
+- Aggressive `major_version_conflict = "bump"` for leaner graph
+- polars already uses `[workspace.dependencies]` - cargo-rail enhances it

examples/unify/ripgrep/README.md

@@ -0,0 +1,30 @@
+# ripgrep unify demo
+
+Small, focused CLI workspace (9 crates). Demonstrates baseline unification.
+
+## Config choices
+
+```toml
+targets = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
+
+[unify]
+msrv = true
+detect_unused = true
+remove_unused = true
+prune_dead_features = true
+strict_version_compat = true
+```
+
+| Option | Value | Why |
+|--------|-------|-----|
+| `msrv` | true | ripgrep already sets `rust-version`; verify cargo-rail computes same |
+| `detect_unused` | true | Find any deps declared but not resolved |
+| `remove_unused` | true | Auto-clean them |
+| `prune_dead_features` | true | Remove empty feature no-ops |
+| `strict_version_compat` | true | Default safety - no surprises |
+
+## What this shows
+
+- Basic unification flow on a well-maintained workspace
+- MSRV computation matching existing `rust-version = "1.85"`
+- Fast execution on small workspace

examples/unify/tokio/README.md

@@ -0,0 +1,34 @@
+# tokio unify demo
+
+Foundational async runtime (5 public + 5 internal crates). Conservative settings.
+
+## Config choices
+
+```toml
+targets = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
+
+[unify]
+msrv = true
+detect_unused = true
+remove_unused = true
+prune_dead_features = true
+strict_version_compat = true
+exact_pin_handling = "warn"
+major_version_conflict = "warn"
+```
+
+| Option | Value | Why |
+|--------|-------|-----|
+| `msrv` | true | Compute buildable floor from deps |
+| `detect_unused` | true | Ecosystem crate - should be clean |
+| `remove_unused` | true | Auto-apply cleanup |
+| `prune_dead_features` | true | tokio has many conditional features |
+| `strict_version_compat` | true | Conservative - don't break ecosystem |
+| `exact_pin_handling` | warn | Report any exact pins but don't fail |
+| `major_version_conflict` | warn | Skip conflicts, don't force bump |
+
+## What this shows
+
+- Safe unification on core ecosystem library
+- Conservative version handling (warn, don't break)
+- Multi-crate workspace with internal test crates