Skip to content

Commit 930d1b2

Browse files
JoshuaEstesJoshuaEstes
committed
docs
1 parent 09c9682 commit 930d1b2

10 files changed

Lines changed: 283 additions & 48 deletions

File tree

‎docs/SUMMARY.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,15 @@
1414
## 🔧 Tools
1515

1616
* [Chorale](tools/chorale.md)
17+
* [Commands](tools/chorale/commands/README.md)
18+
* [Setup](tools/chorale/commands/setup.md)
19+
* [Plan](tools/chorale/commands/plan.md)
20+
* [Apply](tools/chorale/commands/apply.md)
21+
* [Run](tools/chorale/commands/run.md)
1722
* [Concepts](tools/chorale/concepts.md)
1823
* [Configuration](tools/chorale/config.md)
1924
* [Mirroring & Overrides](tools/chorale/mirroring.md)
2025
* [Rule Matrix & Examples](tools/chorale/rules-matrix.md)
21-
* [Plan Command](tools/chorale/plan.md)
2226

2327
## Symfony Bundles
2428

‎docs/tools/chorale.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Chorale automatically merges all package `composer.json` files into the root `co
3737
- `apply` – execute steps from a JSON plan file.
3838

3939
See also:
40-
- Plan command reference: tools/chorale/plan.md
40+
- Commands: tools/chorale/commands/README.md
4141
- Core concepts: tools/chorale/concepts.md
4242
- Configuration and chorale.yaml: tools/chorale/config.md
4343
- Composer mirroring and overrides: tools/chorale/mirroring.md

‎docs/tools/chorale/commands/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Chorale Commands
2+
3+
This section documents each Chorale CLI command in detail.
4+
5+
- Setup: initializes or updates `chorale.yaml` by scanning packages.
6+
- Plan: builds a dry‑run plan of steps.
7+
- Apply: applies steps from a JSON plan file.
8+
- Run: builds and applies a plan in one command.
9+
10+
See also the configuration reference and rule matrix for how values are computed.

‎docs/tools/chorale/commands/apply.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Apply Command
2+
3+
Applies steps from a JSON plan previously exported by `chorale plan --json`.
4+
5+
## Usage
6+
7+
```bash
8+
chorale apply --file plan.json [--project-root PATH]
9+
```
10+
11+
## Options
12+
13+
- `--project-root=PATH`: Override project root (defaults to current directory)
14+
- `--file=FILE` (or `-f`): Path to JSON plan file (default: `plan.json`)
15+
16+
## Examples
17+
18+
```bash
19+
# Apply a plan from the current directory
20+
chorale apply --file plan.json
21+
22+
# Apply a plan from a different root
23+
chorale apply --project-root /path/to/repo --file /tmp/plan.json
24+
```
25+
26+
## Plan File Format (pretty‑printed)
27+
28+
The plan file is the JSON output produced by `chorale plan --json`:
29+
30+
```json
31+
{
32+
"version": 1,
33+
"steps": [
34+
{
35+
"type": "package-version-update",
36+
"name": "sonsofphp/cache",
37+
"version": "1.2.3"
38+
}
39+
],
40+
"noop": {}
41+
}
42+
```

‎docs/tools/chorale/commands/plan.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Plan Command
2+
3+
For the full Plan command reference, see the dedicated page:
4+
5+
- Plan reference: ../plan.md
6+
7+
Key points:
8+
- Default output is concise; increase detail with `-v`, `-vv`, `-vvv`.
9+
- Use `--json` to export a machine‑readable plan for `apply`.

‎docs/tools/chorale/commands/run.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Run Command
2+
3+
Builds a plan and applies it in one step. Equivalent to `chorale plan` followed by `chorale apply`.
4+
5+
## Usage
6+
7+
```bash
8+
chorale run [options]
9+
```
10+
11+
## Options
12+
13+
- `--project-root=PATH`: Override project root (defaults to current directory)
14+
- `--paths=DIR ...`: Limit discovery to specific package paths
15+
- `--force-split`: Plan split steps even if content appears unchanged
16+
- `--verify-remote`: Verify remote state if lockfiles are missing/stale
17+
- `--strict`: Exit non‑zero on issues (e.g., missing root version, conflicts)
18+
- `--show-all`: Include no‑op summaries in output
19+
20+
## Examples
21+
22+
```bash
23+
# Standard run
24+
chorale run
25+
26+
# Limit scope and enable strict mode
27+
chorale run --paths src/SonsOfPHP/Component/Cache --strict
28+
```

‎docs/tools/chorale/commands/setup.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Setup Command
2+
3+
Initializes or updates `chorale.yaml` by scanning your repository for packages and applying sensible defaults.
4+
5+
## Usage
6+
7+
```bash
8+
chorale setup [options]
9+
```
10+
11+
## Options
12+
13+
- `--project-root=PATH`: Override project root (defaults to current directory)
14+
- `--paths=DIR ...`: Limit discovery to specific paths (relative to root)
15+
- `--discover-only`: Only scan and print results; do not write
16+
- `--write`: Write without confirmation (pair with `--non-interactive` in CI)
17+
- `--non-interactive`: Never prompt for confirmation
18+
- `--accept-all`: Accept suggested adds/renames during interactive runs
19+
- `--strict`: Treat warnings as errors (non‑zero exit)
20+
- `--json`: Emit a machine‑readable JSON report
21+
22+
## Examples
23+
24+
```bash
25+
# Interactive scan and write
26+
chorale setup
27+
28+
# Discover only; do not write any changes
29+
chorale setup --discover-only
30+
31+
# CI‑style non‑interactive write
32+
chorale setup --write --non-interactive
33+
34+
# Limit discovery to a subset of paths
35+
chorale setup --paths src/SonsOfPHP/Component/Cache src/SonsOfPHP/Component/Clock
36+
37+
# Strict mode with JSON report
38+
chorale setup --json --strict > setup-report.json
39+
```
40+
41+
## JSON Report (pretty‑printed)
42+
43+
Example shape of the JSON emitted by `--json` (fields omitted for brevity):
44+
45+
```json
46+
{
47+
"defaults": {
48+
"repo_host": "github.com",
49+
"repo_vendor": "sonsofphp",
50+
"repo_name_template": "{name:kebab}",
51+
"default_repo_template": "git@{repo_host}:{repo_vendor}/{name:kebab}.git"
52+
},
53+
"groups": {
54+
"ok": ["src/SonsOfPHP/Component/Cache"],
55+
"new": ["src/SonsOfPHP/Component/Clock"],
56+
"renamed": [],
57+
"drift": [],
58+
"issues": [],
59+
"conflicts": []
60+
},
61+
"actions": [
62+
{ "type": "add", "path": "src/SonsOfPHP/Component/Clock" }
63+
]
64+
}
65+
```

‎docs/tools/chorale/config.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,48 @@ split:
7272
- "**/.DS_Store"
7373
```
7474

75+
## Complete Example
76+
77+
A cohesive `chorale.yaml` showing common settings together:
78+
79+
```yaml
80+
patterns:
81+
- match: "src/SonsOfPHP/*"
82+
- match: "src/SonsOfPHP/Component/*"
83+
84+
targets:
85+
- path: "src/SonsOfPHP/Component/Cache"
86+
repo_vendor: SonsOfPHP
87+
composer_overrides:
88+
values:
89+
description: "{name} component for the Sons of PHP monorepo"
90+
rules:
91+
homepage: mirror
92+
- path: "src/SonsOfPHP/Component/Clock"
93+
composer_overrides:
94+
values:
95+
description: "Clock utilities for Sons of PHP"
96+
97+
composer_sync:
98+
rules:
99+
authors: mirror
100+
license: mirror
101+
support: merge-object
102+
funding: merge-object
103+
extra: merge-object
104+
keywords: append-unique
105+
homepage: mirror-unless-overridden
106+
description: ignore
107+
108+
split:
109+
ignore:
110+
- "vendor/**"
111+
- "**/composer.lock"
112+
- "**/.DS_Store"
113+
```
114+
75115
## Notes
76116

77117
- Overrides win over rules for specific packages (see Mirroring & Overrides).
78118
- Patterns determine discovery roots; paths let you limit plan scope quickly.
79119
- Use `plan --strict` in CI to require explicit action when needed.
80-

0 commit comments

Comments
 (0)