ChatGPTClaudeGrok / X / CursorGemini

Evolving DSH plugin config: add fields, rename, migrate

Plugin DevelopmentPublished 2026-11-05Author: DeepSeek Plugin Market
DSH pluginconfig evolutioncompatibilityschemaversioning
Your plugin has users and the next release needs a new parameter or a rename. Treat additions, default changes, and renames differently, then test three shapes.

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:

ts
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.

ChangeWhat happens to old configRisk
New field with a defaultMissing value is filledLow
Changed defaultUnchanged if the user set itMedium
Rename, semantic change, or requiredOld key ignored or validation failsHigh

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.

  1. Add the field to the interface;
  2. Declare .default(...) in the schema rather than config.x ?? value inside apply;
  3. Use config.x directly, keeping the type non-optional;
  4. Start with a minimal config and confirm the default is filled;
  5. 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:

ts
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:

  1. When a user writes one field, the rest fall back to your schema defaults rather than inheriting a lower layer's values;
  2. 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:

  1. Old config: copy a typical previous-release config with no new fields;
  2. Minimal config: only required fields, everything else omitted;
  3. 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Will adding a config field break existing users of my DSH plugin?

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.

Why is renaming a DSH plugin config field more dangerous than deleting one?

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.

Can't deep merging of user config protect old DSH plugin field names?

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.

Which DSH plugin config combinations must I test before releasing?

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