Skip to content

Commit 63dd986

Browse files
loadingaliasloadingalias
committed
docs: reorganize examples and consolidate change detection docs
- Rename VALIDATION_RESULTS.md → unify-results.md - Add examples/config/ with full annotated rail.toml - Consolidate examples/change_detection/ to two patterns: - with-task-runner/ (plan + xtask/just/make) - standalone/ (cargo rail run) - Update split-sync/README.md with Copybara comparison - Update release/README.md with cargo-release/git-cliff comparison - Move large-repo-validation.md → examples/validation-protocol.md - Consolidate 3 change detection docs into docs/change-detection.md - Update all internal references
1 parent 7978f33 commit 63dd986

File tree

24 files changed

+773
-408
lines changed

24 files changed

+773
-408
lines changed

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,6 @@ distribution/
2626
todo.md
2727
MERGE_CHECKLIST.md
2828
VALIDATION_REPORT.md
29-
examples/unify/VALIDATION_RESULTS.md
29+
examples/unify/unify-results.md
3030
dominance-plan.md
3131
upgrades.md

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ clap = { version = "4.5.58", features = ["derive", "cargo"] }
3939
clap_complete = "4.5.66"
4040
cargo_metadata = "0.23.1"
4141
petgraph = { version = "0.8.3", default-features = false }
42-
toml_edit = { version = "0.25.1+spec-1.1.0", features = ["serde"] }
42+
toml_edit = { version = "0.25.1", features = ["serde"] }
4343
serde = { version = "1.0.228", features = ["derive"] }
4444
serde_json = "1.0.149"
4545
semver = "1.0.27"

‎README.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -157,9 +157,7 @@ By default, on `cargo rail init`, the `rail.toml` file is written to the `.confi
157157
- [Configuration Reference](docs/config.md)
158158
- [Command Reference](docs/commands.md)
159159
- [Architecture](docs/architecture.md)
160-
- [Change Detection Recipe](docs/change-detection-recipe.md)
161-
- [Change Detection Operations Guide](docs/change-detection-operations.md)
162-
- [How to Use Change Detection Effectively](docs/how-to-use-cargo-rail-change-detection.md)
160+
- [Change Detection Guide](docs/change-detection.md)
163161
- [Troubleshooting](docs/troubleshooting.md)
164162

165163
## Migration Guides
@@ -182,7 +180,7 @@ All core workflows (`plan`/`run`, `unify`) validated on production repos with fu
182180

183181
**How to Validate:**
184182

185-
1. **Reproducibility**: Every command in [docs/large-repo-validation.md](docs/large-repo-validation.md) runs on forked repos with real merge history
183+
1. **Reproducibility**: Every command in [examples/validation-protocol.md](examples/validation-protocol.md) runs on forked repos with real merge history
186184
2. **Metrics collection**: Automated scripts measure execution reduction, surface accuracy, plan duration, unify impact
187185
3. **Quality audit**: Heuristics flag potential false positives/negatives for human review
188186
4. **Real-world scenarios**: Tests run on actual merge commits and real dependency graphs, not synthetic fixtures
@@ -202,7 +200,7 @@ Each workflow includes working config files and reproducible command sequences:
202200
| Workflow | Examples | Real-World Configs |
203201
|---|---|---|
204202
| Change detection | [examples/change_detection/](examples/change_detection/) | [tokio](https://github.com/loadingalias/cargo-rail-testing/blob/main/tokio/.config/rail.toml), [helix](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix/.config/rail.toml), [meilisearch](https://github.com/loadingalias/cargo-rail-testing/blob/main/meilisearch/.config/rail.toml) |
205-
| Unify | [examples/unify/](examples/unify/) | [Validation results](examples/unify/VALIDATION_RESULTS.md) |
203+
| Unify | [examples/unify/](examples/unify/) | [Validation results](examples/unify/unify-results.md) |
206204
| Split/sync | [examples/split-sync/](examples/split-sync/) | — |
207205
| Release | [examples/release/](examples/release/) | — |
208206

‎docs/change-detection-operations.md‎

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎docs/change-detection-recipe.md‎

Lines changed: 0 additions & 61 deletions
This file was deleted.

docs/how-to-use-cargo-rail-change-detection.md renamed to docs/change-detection.md

File renamed without changes.

‎docs/config.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -401,8 +401,8 @@ Use `cargo rail plan -f github` as the CI source of truth:
401401
run: cargo rail run --merge-base --surface docs
402402
```
403403

404-
For a full end-to-end operating recipe (local + CI + trust checklist), see:
405-
`docs/change-detection-recipe.md`.
404+
For a full end-to-end operating guide (local + CI + trust checklist), see:
405+
[docs/change-detection.md](change-detection.md).
406406

407407
**`plan -f github` outputs:**
408408

‎docs/migrate-plan-run.md‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎examples/README.md‎

Lines changed: 31 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,46 @@
11
# Examples
22

3-
Simple, copy-paste-first examples for cargo-rail workflows.
3+
Copy-paste-ready examples for cargo-rail workflows.
44

5-
## Change Detection
5+
## By Workflow
66

7-
Progressive configs from minimal to full-featured:
7+
| Workflow | Example | Description |
8+
|----------|---------|-------------|
9+
| **Config** | [config/](config/) | Full annotated `rail.toml` |
10+
| **Change Detection** | [change_detection/](change_detection/) | Plan + run patterns |
11+
| **Unify** | [unify/](unify/) | Dependency unification |
12+
| **Split/Sync** | [split-sync/](split-sync/) | Crate extraction and sync |
13+
| **Release** | [release/](release/) | Version, changelog, publish |
814

9-
| Example | Description |
10-
|---------|-------------|
11-
| [01-minimal](change_detection/01-minimal/) | Smallest usable setup |
12-
| [02-balanced-monorepo](change_detection/02-balanced-monorepo/) | Practical baseline (recommended) |
13-
| [03-strict-bot-pr](change_detection/03-strict-bot-pr/) | Stricter mode for bot PRs |
14-
| [04-github-actions](change_detection/04-github-actions/) | Minimal planner-first GHA workflow |
15-
| [05-custom-profiles](change_detection/05-custom-profiles/) | Custom profiles and workflow mapping |
15+
## Change Detection Patterns
1616

17-
## Unify
18-
19-
- [unify/](unify/) — Config + validation results
20-
21-
**Validated on 4 production repos (53 crates):** [VALIDATION_RESULTS.md](unify/VALIDATION_RESULTS.md)
22-
23-
## Split/Sync
24-
25-
- [split-sync/](split-sync/) — Config template (sandbox first)
26-
27-
## Release
28-
29-
- [release/](release/) — Config template (check mode only)
30-
31-
---
17+
| Pattern | For Projects With | Link |
18+
|---------|-------------------|------|
19+
| **With task runner** | just, make, xtask | [change_detection/with-task-runner/](change_detection/with-task-runner/) |
20+
| **Standalone** | No task runner | [change_detection/standalone/](change_detection/standalone/) |
3221

3322
## Real-World Configs
3423

3524
Full production configs validated on real repositories:
3625

37-
| Repository | Config | Integration Guide | Metrics |
38-
|------------|--------|-------------------|---------|
39-
| tokio | [rail.toml](https://github.com/loadingalias/cargo-rail-testing/blob/main/tokio/.config/rail.toml) | [Guide](https://github.com/loadingalias/cargo-rail-testing/blob/main/tokio/docs/cargo-rail-integration-guide.md) | [Metrics](https://github.com/loadingalias/cargo-rail-testing/blob/main/tokio/docs/CHANGE_DETECTION_METRICS.md) |
40-
| helix | [rail.toml](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix/.config/rail.toml) | [Guide](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix/docs/cargo-rail-integration-guide.md) | [Metrics](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix/docs/CHANGE_DETECTION_METRICS.md) |
41-
| meilisearch | [rail.toml](https://github.com/loadingalias/cargo-rail-testing/blob/main/meilisearch/.config/rail.toml) | [Guide](https://github.com/loadingalias/cargo-rail-testing/blob/main/meilisearch/docs/cargo-rail-integration-guide.md) | [Metrics](https://github.com/loadingalias/cargo-rail-testing/blob/main/meilisearch/docs/CHANGE_DETECTION_METRICS.md) |
42-
| helix-db | [rail.toml](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix-db/.config/rail.toml) | [Guide](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix-db/docs/cargo-rail-integration-guide.md) | [Metrics](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix-db/docs/CHANGE_DETECTION_METRICS.md) |
26+
| Repository | Config | Integration Guide |
27+
|------------|--------|-------------------|
28+
| [tokio](https://github.com/loadingalias/cargo-rail-testing/tree/main/tokio) | [rail.toml](https://github.com/loadingalias/cargo-rail-testing/blob/main/tokio/.config/rail.toml) | [Guide](https://github.com/loadingalias/cargo-rail-testing/blob/main/tokio/docs/cargo-rail-integration-guide.md) |
29+
| [helix](https://github.com/loadingalias/cargo-rail-testing/tree/main/helix) | [rail.toml](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix/.config/rail.toml) | [Guide](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix/docs/cargo-rail-integration-guide.md) |
30+
| [meilisearch](https://github.com/loadingalias/cargo-rail-testing/tree/main/meilisearch) | [rail.toml](https://github.com/loadingalias/cargo-rail-testing/blob/main/meilisearch/.config/rail.toml) | [Guide](https://github.com/loadingalias/cargo-rail-testing/blob/main/meilisearch/docs/cargo-rail-integration-guide.md) |
31+
| [helix-db](https://github.com/loadingalias/cargo-rail-testing/tree/main/helix-db) | [rail.toml](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix-db/.config/rail.toml) | [Guide](https://github.com/loadingalias/cargo-rail-testing/blob/main/helix-db/docs/cargo-rail-integration-guide.md) |
4332

4433
**Validation forks**: [cargo-rail-testing](https://github.com/loadingalias/cargo-rail-testing)
4534

46-
---
35+
## Validation Results
36+
37+
- **Unify**: [unify-results.md](unify/unify-results.md) — 96 deps unified, 258 undeclared features fixed across 53 crates
38+
- **Change Detection**: See each fork's `docs/CHANGE_DETECTION_METRICS.md`
39+
40+
## Quick Validation
4741

48-
All examples are intentionally minimal and designed to avoid ornamental complexity.
42+
```bash
43+
cargo rail config validate --strict
44+
cargo rail plan --merge-base --explain
45+
cargo rail unify --check
46+
```

‎examples/change_detection/01-minimal/rail.toml‎

Lines changed: 0 additions & 40 deletions
This file was deleted.

0 commit comments

Comments
 (0)