Skip to content

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.md
index 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 Commands
CLI commands live in `src/cli/` with implementations in `src/commands/`.