wslc cli settings design spec#14367
Conversation
|
|
||
| --- | ||
|
|
||
| ## 2. Recommended Format: YAML (JSON as fallback) |
There was a problem hiding this comment.
Agree with this on all points, very nicely laid out tradeoffs and discussion!
|
|
||
| ``` | ||
| wslc settings Open settings file in default editor (or Notepad) | ||
| wslc settings --reset Restore settings to built-in defaults (prompts for confirmation) |
There was a problem hiding this comment.
I would prefer "reset" being a subcommand instead of an option on the settings root command. This seems more consistent with the command pattern established in wslc.
| wslc settings --reset Restore settings to built-in defaults (prompts for confirmation) | ||
| ``` | ||
|
|
||
| The primary usage (`wslc settings` with no flags) opens the file for editing. This is the most common workflow: a user wants to change something, they open it, edit, save, and the next invocation picks up the change. |
There was a problem hiding this comment.
This is good and familiar with WinGet and is nice to use. We could also leave the door open for additional setting subcommands like "wslc settings add " and similar delete, and settings list. For users who dont want to jump between console and an editor. For some settings this might be simpler and faster than the editor option and they wouldn't have to know the format.
Not important for p0 of course but those would be nice value-adds later on. This design does not prohibit this so could be incremental if we decide there is value.
|
|
||
| Example: if `UserSettings.yaml` contains `memorySizeMb: 8192` and the user runs `wslc session --memory 4096`, the effective memory size is `4096`. If `--memory` is not given, it is `8192`. If the key is not in settings, it falls back to the built-in default. | ||
|
|
||
| This means commands must check whether an argument was explicitly provided by the user versus not present at all (not yet set in `ArgMap`), rather than checking for a default value. The existing `ArgMap::Contains()` method already provides this distinction cleanly. |
There was a problem hiding this comment.
We could also have a nice wrapper here for getting the default value based on ArgType which would follow the settings -> default value to encapsulate all of the settings vs default lookup and handle any errors in the settings by falling back to the default (and printing a warning).
Something different from WinGet is the ArgMap is an enum map like Data. It is also a multmap (different from WinGet), so setting multiple arg values via settings should be possible.
I'm just speculating a moment, but perhaps we can process arguments for a command, and then have a step which checks the settings for default argument values. If there is a default set, we can add the setting to the ArgMap if the argument isn't already there, or if it allows multiple, add new ones if they are different. Then the command execution could be completely agnostic of settings and defaults, it would just process the command as it did before with all of the magic happening in a settings step that is modifying the ArgMap for applicable settings.
|
|
||
| ### Setting Value Validation | ||
|
|
||
| After parsing, each known key is validated against its expected type and allowed values: |
There was a problem hiding this comment.
We do have some argument validation framework setup already for these things, assuming string input. We should ideally reuse that for settings if possible. I'm not sure how applicable since the arg validation is based on the ArgType enum, but for any settings that are arguments it should work and we would be running the same validation against it if we convert the input to a string. For argument settings this would be effectively free as long as they had an associated argtype for validating.
|
|
||
| ### Settings Loading | ||
|
|
||
| Settings are loaded once at startup in `CoreMain`, before command dispatch, and stored in `CLIExecutionContext`. Settings will be implemented as a singleton and globally read accessible. |
There was a problem hiding this comment.
Makes sense. If settings are stored as another type of EnumVariantMap we can get additional value from that and store them as a SettingsMap, and Settings off the context with the same access patterns as Args and Data use.
|
|
||
| ### Settings File Write (for `--reset`) | ||
|
|
||
| `--reset` overwrites `UserSettings.yaml` with the commented-out defaults template (the same content generated on first run) after prompting: |
There was a problem hiding this comment.
As above I would expect this to be a command, and then we could add --force Argument to it to skip the confirmation.
|
|
||
| ## 8. Out of Scope for Initial Implementation | ||
|
|
||
| - **`wslc settings set <key> <value>`** — programmatic key setting without opening an editor. Useful for scripting. Deferred to v2; manual editing covers the primary use case. |
There was a problem hiding this comment.
I got ahead of myself in earlier comments, but I like this as a future goal.
There was a problem hiding this comment.
Agreed, editing configuration files via the command line is tricky, so let's table this for now
| - **System-wide settings** — a machine-level settings file (e.g., `%ProgramData%\Microsoft\WSL\wslc\UserSettings.yaml`) that applies to all users. Deferred; per-user is sufficient for v1. | ||
| - **Settings profiles** — named profiles for different environments. Deferred. | ||
| - **Schema export** — `wslc settings --schema` to print a JSON Schema or TOML template. Useful for editor autocompletion; deferred. | ||
| - **Environment variable overrides** — `WSLC_DEFAULTS_FORMAT=json` style overrides. Useful for CI pipelines; deferred. |
There was a problem hiding this comment.
May want a comment about GroupPolicy here and system administrator enforced settings. Probably out of scope for v1.
|
|
||
| ``` | ||
| wslc settings Open settings file in default editor (or Notepad) | ||
| wslc settings --reset Restore settings to built-in defaults (prompts for confirmation) |
There was a problem hiding this comment.
Do we feel that there's a strong usecase for a --reset here ? This would pretty much be the equivalent of deleting the file, which can already be scripted easily if needed
|
|
||
| ## 8. Out of Scope for Initial Implementation | ||
|
|
||
| - **`wslc settings set <key> <value>`** — programmatic key setting without opening an editor. Useful for scripting. Deferred to v2; manual editing covers the primary use case. |
There was a problem hiding this comment.
Agreed, editing configuration files via the command line is tricky, so let's table this for now
3 participants
For spec comments. Do not merge.