用途
该技能用于指导 VS Code 设置项(setting ID)的命名与维护,适用于以下场景:新增设置项、重命名设置项、审查设置项 ID,或将设置项标记为 experimental、preview、advanced。
主要原则
设置项 ID 是永久性的。用户会把它写入 settings.json、设置同步、dotfiles、文档和策略中。因此,命名应依据它控制的功能,而不是依据它的成熟度。
成熟度放在标签里,不放在 ID 里
不要把 experimental、preview、beta 或类似字样放进设置项 ID(如 foo.experimental.bar、foo.experimentalBar),而应使用 tags。
示例(代码内容保持原样):
'chat.foo.enabled': { type: 'boolean', default: false, tags: ['experimental'], description: localize('chat.foo.enabled', "Controls whether foo is enabled."), },
各标签含义:
- experimental:功能可能大幅变动或被移除。
- preview:打算保留该功能,但尚未完成。由于它会保留,ID 必须已经是最终形式。
- advanced:除非用户按 @tag:advanced 过滤或搜索设置项 ID,否则在设置编辑器中隐藏。它与成熟度无关。
设置编辑器会为这些标签显示“Experiment”或“Preview”徽章,将这类设置排在稳定设置之后,并允许用户用 @tag:experimental、@tag:preview 和 @tag:stable 过滤。功能毕业时,移除标签(可能还要改默认值),ID 保持不变,不会破坏任何人的设置。
experimental 标签并不把设置置于 A/B 实验控制之下;那需要 experiment: { mode }。处理名默认是 config.<setting ID>,因此重命名受实验控制的设置时,要保留旧处理名:experiment: { mode, name: 'config.<old ID>' };只有当解析后的处理名变化时才需要更新 ExP。
唯一例外是将被删除而非转正的设置,例如某个替代实现的临时开关。这种情况下,名字里体现这一点可以接受,但仍优先使用标签。
重命名设置项
应避免重命名。如果无法避免(例如去掉已有的 experimental 片段),请在 IConfigurationMigrationRegistry(configuration.ts)中注册迁移,将现有值迁移到新 ID,且不覆盖用户已在新 ID 设置的值:
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; } }]);
同时更新文档、测试以及其他读取旧 ID 的代码。
适用场景
适用于 VS Code 代码库中涉及设置项定义、命名审查和成熟度标记的改动,帮助保持设置项 ID 的长期稳定性与用户配置兼容性。