Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Document config deprecation recipe in CLAUDE.md (#1857)
Maximilian Roos4197f09cf88a
diff --git a/CLAUDE.md b/CLAUDE.mdindex 9691fbcbe..e23a22fc2 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -363,6 +363,47 @@ if worktree.is_dirty() {- **Don't `logger.error` before raising** — include context in the error message itself- **Let errors propagate** — don't catch and re-raise without adding information+## Config Deprecation++Config deprecation has two layers, both required for a complete migration.++### Layer 1: Pre-deserialization scanning (`src/config/deprecation.rs`)++`check_and_migrate()` scans raw TOML text before serde parses it. It detects deprecated template variables, renamed sections, and removed fields, then generates a migration file (e.g., `config.deprecated.toml`) with upgrade instructions. Warnings are deduplicated per-process via `WARNED_DEPRECATED_PATHS`.++To register a new deprecation at this layer:++1. Add detection logic to `detect_deprecations()` and extend the `Deprecations` struct+2. Add the migration instructions to `write_migration_file()`+3. If it's a top-level section, add the key to `DEPRECATED_SECTION_KEYS` (this prevents `warn_unknown_fields` from also flagging it)++### Layer 2: Post-deserialization normalization (`src/config/user/mod.rs`)++After serde parses the config, `normalize_deprecated_sections()` moves deprecated values to their canonical locations. This runs on every load path (`load()`, `load_from_str()`, and `mutation.rs` reloads). Existing examples: `[commit-generation]` → `[commit.generation]`, `[select]` → `[switch.picker]`.++### Renaming a field within a section++This is the most common case. Serde's `#[serde(deny_unknown_fields)]` is not used on config sections, so unrecognized fields inside a section like `[merge]` are silently ignored — they won't trigger `warn_unknown_fields`, which only checks top-level keys. The serde-level approach below is the only way to catch and migrate inner-section fields.++Recipe for renaming `old-name` → `new-name` inside an existing section:++1. **Keep the old field in the struct** so serde still deserializes it:++ ```rust+ /// **DEPRECATED**: Use `new-name` instead.+ #[serde(rename = "old-name", skip_serializing, default)]+ #[schemars(skip)]+ pub old_name: Option<bool>,+ ```++ `skip_serializing` prevents writing the old name back. `schemars(skip)` hides it from the JSON schema.++2. **Add a normalization method** on the section struct that transfers the old value to the new field, applying any inversion or transformation needed, and emits a deprecation warning via `warning_message()`.++3. **Call it from `normalize_deprecated_sections()`** in `src/config/user/mod.rs`, alongside the existing normalizations.++Do not silently drop old config keys — this causes silent behavior changes for users.+## Adding CLI CommandsCLI commands live in `src/cli/` with implementations in `src/commands/`.