Evolving DSH plugin config: add fields, rename, migrate
Once a plugin ships, its config stops belonging to you. A user may have written values in cordis.yml, or overridden a single field in their profile patch.
Every new field and every rename must assume someone is still using the old shape.
A concrete DSH plugin release scenario
Start evolving a DSH plugin from the config your users run today, not from the new design. Version 1.1 looks like this:
export interface Config {
greeting: string
maxRetries: number
}
export const Config: Schema<Config> = Schema.object({
greeting: Schema.string().default('Hello'),
maxRetries: Schema.number().default(3),
})
Three months later, users have gone from 3 to 300. Version 1.2 wants three changes: a request timeout, a feature switch, and renaming maxRetries to the more accurate retryLimit.
Those three have very different risk profiles and must be handled separately.
Three DSH plugin config changes, three risk levels
Classify DSH plugin config changes before touching code.
| Change | What happens to old config | Risk |
|---|---|---|
| New field with a default | Missing value is filled | Low |
| Changed default | Unchanged if the user set it | Medium |
| Rename, semantic change, or required | Old key ignored or validation fails | High |
Additions are safe; renames are dangerous. The former loads old config fine; the latter starts successfully while behavior quietly changes, which is harder to diagnose than a crash.
Default changes depend on the user. Explicit values are unaffected; users who never set the field will notice. If the default affects safety or cost, call it out in the release notes.
Safe DSH plugin changes: new fields
One rule for DSH plugin config: every new field needs a default.
- Add the field to the interface;
- Declare
.default(...)in the schema rather thanconfig.x ?? valueinsideapply; - Use
config.xdirectly, keeping the type non-optional; - Start with a minimal config and confirm the default is filled;
- Start with a full config and confirm explicit values win.
Why insist on the schema? Only schema defaults are applied at load time. A ?? inside apply is a runtime fallback, the type stays optional, and callers never get a guarantee that a value exists.
Never add required() to a new field. Every old config then fails validation on upgrade and the plugin stops loading. If the field truly cannot have a default, move it to the next major version and announce it.
Dangerous DSH plugin changes: renames and meaning
The rename trap is the absence of an error. A user writes maxRetries: 5; your code reads retryLimit and gets the default 3. The plugin starts, and retries silently drop from five to three.
The recommended transition is a dual read:
export interface Config {
retryLimit: number
/** @deprecated use retryLimit */
maxRetries?: number
newSwitch: boolean
}
export const Config: Schema<Config> = Schema.object({
retryLimit: Schema.number(),
maxRetries: Schema.number(),
newSwitch: Schema.boolean().default(false),
})
export function apply(ctx: Context, config: Config) {
const retryLimit = config.retryLimit ?? config.maxRetries ?? 3
// ...
}
Three points matter: give the new field no default, or the old value is never read; keep the old field and mark it deprecated; and read in the order new, old, hard fallback. Semantic changes hide better than renames: the same field name switching from milliseconds to seconds turns a user's 30000 into 30000 seconds. Dual read cannot fix that; rename the field and treat it as breaking.
Why wholesale replacement makes DSH plugin renames worse
Many config systems deep-merge; DSH plugin does not. A patch replaces the target row's entire config value, key by key it does not merge.
Two consequences follow:
- When a user writes one field, the rest fall back to your schema defaults rather than inheriting a lower layer's values;
- After a rename, the user's old key is not migrated and usually does not even produce an "unknown field" error — it is simply ignored.
So do not rely on merge logic to catch compatibility. Manage the field lifecycle yourself: defaults for additions, dual read for renames, removal only in a major version. Document it in the upgrade notes: "1.2 adds timeoutMs, default 30000", "2.0 removes maxRetries, use retryLimit".
Verifying DSH plugin config before release
DSH plugin compatibility needs three config shapes, and all three must run:
- Old config: copy a typical previous-release config with no new fields;
- Minimal config: only required fields, everything else omitted;
- New config: every field written explicitly.
For each, confirm three things: it starts, --dump-config shows the expected values, and behavior matches the docs.
Also test one invalid config. Put a string where a number belongs and confirm loading fails on that field. Validation that cannot fail is not validation; a schema that silently accepts bad values does nothing. Finally, check whether defaults leak into logs: some contain paths or internal addresses, and after an upgrade they may appear in startup output.
The goal is not "nothing breaks this time" but "when it breaks, users can understand why". Clear errors, release notes, and a transition window on old fields do more for retention than a bug-free release. For the basics of Config and schemas, read plugin config; for ids and wholesale replacement, read cordis.yml ids; for version ranges, read plugin version compatibility.
FAQ
Adding a field to a DSH plugin does not break existing users if the schema gives it a default. Missing fields are filled at load time. But if the new field uses required(), every old config fails validation and the plugin will not load after upgrade.
Deleting a DSH plugin config field falls back to default behavior. A renamed field leaves the old key unread and the new key at its default, so the plugin starts but behavior silently changes and users see no error.
No, because a DSH plugin patch replaces the target config wholesale rather than merging keys. User layers only contain what they wrote, and a renamed key is simply ignored, so migration has to live in your code.
Three DSH plugin config shapes must be tested before releasing: the previous release's full config, a minimal config with only required fields, and a new config with every field set. All three must start and behave as documented.
Related Terms
- schema default
- A schema default is a fallback declared in the Schemastery schema, applied when a config omits the field so older configs keep loading.— DeepSeek Harness docs
- breaking change
- A breaking change is a change that invalidates existing config or calling conventions, such as renaming a field, changing its meaning, or making it required.— DeepSeek Harness docs
- dual read
- Dual read is a transition technique that reads both the old and new field, preferring the new one, until the old field is removed in a major release.— DeepSeek Harness docs
- config layer
- A config layer is a patch overlay applied in order across bundles, profile, home, and command-line overrides, with later layers winning.— DeepSeek Harness CLI reference
Sources
- DeepSeek Harness docs: plugin config· deepseek-harness
- DeepSeek Harness CLI reference· deepseek-ai
- deepseek-harness repository· deepseek-ai