A setting ID is permanent: users write it into settings.json, settings sync, dotfiles, docs, and policies. Name it for what it controls, never for how mature it is.
Maturity goes in tags, not in the ID
Don't put experimental, preview, beta, or similar into a setting ID (foo.experimental.bar, foo.experimentalBar). Use tags instead:
'chat.foo.enabled': {
type: 'boolean',
default: false,
tags: ['experimental'],
description: localize('chat.foo.enabled', "Controls whether foo is enabled."),
},
experimental: the feature might change a lot or be removed.preview: we intend to keep the feature, but it is not finished yet. Since it will stay, the ID must already be the final one.advanced: hidden from the Settings editor unless the user filters by@tag:advancedor searches for the setting ID. This is independent of maturity.
The Settings editor shows an "Experimental" or "Preview" badge for these tags, sorts them after stable settings, and lets users filter them with @tag:experimental, @tag:preview, and @tag:stable. When the feature graduates, remove the tag (and maybe change the default); the ID stays the same and nobody's settings break.
An experimental tag doesn't put a setting under A/B experiment control. That needs experiment: { mode } (see the experiments skill). The treatment name defaults to config.<setting ID>, so when you rename an experiment-controlled setting, keep the old treatment with experiment: { mode, name: 'config.<old ID>' }; ExP needs updating only if the resolved treatment name changes.
The only exception is a setting that will be deleted rather than promoted, for example a temporary toggle for an alternative implementation. A name that says so is acceptable there, but the tag is still preferred.
Renaming a setting
Avoid renames. If one is unavoidable (for example to drop an existing experimental segment), register a migration in IConfigurationMigrationRegistry (configuration.ts) that moves existing values to the new ID without overwriting a value the user already set there:
Registry.as<IConfigurationMigrationRegistry>(WorkbenchExtensions.ConfigurationMigration)
.registerConfigurationMigrations([{
key: 'foo.experimental.bar',
migrateFn: (value: unknown, valueAccessor) => {
const result: ConfigurationKeyValuePairs = [['foo.experimental.bar', { value: undefined }]];
if (value !== undefined && valueAccessor('foo.bar') === undefined) {
result.push(['foo.bar', { value }]);
}
return result;
}
}]);
Also update docs, tests, and other code that reads the old ID.