commit a6b4ede1304f42455fbffb5c2daf1c5965aa3876
parent 8e404c7104140d1c2814c920b21fe9721dc80b39
Author: Kaleb Luedtke <trenlymc@gmail.com>
Date: Fri, 16 Jul 2021 11:02:55 -0500
Update Settings Command Spec for Clarity (#1290)
Diffstat:
1 file changed, 29 insertions(+), 29 deletions(-)
diff --git a/doc/specs/#396 - Settings command.md b/doc/specs/#396 - Settings command.md
@@ -1,7 +1,7 @@
---
author: Ruben Guerrero @msftrubengu
created on: 2020-06-03
-last updated: 2020-06-03
+last updated: 2021-07-14
issue id: 396
---
@@ -11,7 +11,7 @@ For [#396](https://github.com/microsoft/winget-cli/issues/396)
## Abstract
-The winget.exe client must support having a feature that allows users to specify settings. This will be in the form of an editable file. The file must be in a location where a user can easily get it and modify it.
+The winget.exe client must support having a feature that allows users to specify settings. This will be in the form of an editable file. The file must be in a location where a user can easily access it and modify it.
## Inspiration
@@ -21,7 +21,7 @@ Add ability for user to set their own preferences.
### Format
-The WinGet settings file needs to be in a readable format for users. We consider using other options, like the registry, but having a fil makes it more accessible to users.
+The WinGet settings file needs to be in a readable format for users. We considered using other options, like the registry, but having a file makes it more accessible to users.
#### Option 1: YAML
@@ -29,10 +29,10 @@ WinGet already knows how to handle YAML files via yaml-cpp. To follow the manife
#### Option 2: JSON
-JSON is the popular formats that most applications tend to use. It is also possible to parse JSON with yaml-cpp as YAML is a superset of JSON, but a proper JSON parser might be needed depending on how well yaml-cpp handles it. Options are third party json parsers or Microsoft cpp winrt implementation `winrt::Windows::Data::Json::JsonObject`. Properties will be camelCased.
+JSON is a popular format that most applications tend to use. It is also possible to parse JSON with yaml-cpp as YAML is a superset of JSON, but a proper JSON parser might be needed depending on how well yaml-cpp handles it. Options are third party JSON parsers or Microsoft cpp winrt implementation `winrt::Windows::Data::Json::JsonObject`. Properties will be camelCased.
There is also the concern about comments because JSON doesn't support them. There are different approaches we could take.
-- Go with JSON standard and support properties named `__comments` which will be ignored parsing the file.
+- Go with JSON standard and support properties named `__comments` which will be ignored when parsing the file.
- Use jsoncpp and allow C type comments.
- Use yaml-cpp and allow YAML comments.
@@ -40,11 +40,11 @@ Based on this information we are going to use JSON and jsoncpp as a parser. For
### Location
-WinGet can either run in package context or not. That means the location of the settings file will be determine depending on the context.
+WinGet can either run in package context or not. That means the location of the settings file will be determined depending on the context.
-Package Context: %LOCALAPPDATA%\Packages\Microsoft.DesktopAppInstaller_8wekyb3d8bbwe\LocalState\settings.yaml. For more about UWP file system see [this](https://docs.microsoft.com/en-us/windows/uwp/get-started/fileio-learning-track#access-the-file-system)
+Package Context: %LOCALAPPDATA%\Packages\Microsoft.DesktopAppInstaller_8wekyb3d8bbwe\LocalState\settings.json. For more about UWP file system see [this](https://docs.microsoft.com/en-us/windows/uwp/get-started/fileio-learning-track#access-the-file-system)
-Non-package context: %LOCALAPPDATA%\Microsoft\Winget\settings.yaml
+Non-package context: %LOCALAPPDATA%\Microsoft\Winget\settings.json
### Command
@@ -57,31 +57,31 @@ Options:
A command is a better option than having an argument, for example `winget --settings`, because it let us add more commands into it in the future such as set and unset.
-Expectation is that when the user enters `winget settings` the settings file will be opened in the user's default text editor via ShellExecute. If the user doesn't have any file type association with `.json`, the default will be is opening with notepad.exe
+The expectation is that when the user enters `winget settings` the settings file will be opened in the user's default text editor via ShellExecute. If the user doesn't have any file type association with `.json`, the default will be to open it with notepad.exe
There will also be a telemetry point added into the command as the other commands have.
### Backup Settings File
-A user might make a mistake could make the settings file unparsable. To protect against this there must be a backup settings file with the latest known good settings file. The flow is the following:
+A user might make a mistake that could make the settings file unparsable. To protect against this there must be a backup settings file with the latest known good settings file. The flow is the following:
-1. winget settings
-2. If settings file can be parsed copy to settings.backup
+1. `winget settings`
+2. If settings file can be parsed copy to settings.json.backup
3. Open settings file
4. Wait for next command
-5. If settings file can be parsed use it otherwise use settings.backup and warn user.
+5. If settings file can be parsed use it; otherwise, use settings.json.backup and warn user.
-This mechanism allows to be resilient for mistakes done the settings file.
+This mechanism allows the settings file to be resilient against mistakes.
### Creating file
-A setting file will only be created if the user does `winget settings` and one of the following occurs:
+A settings file will only be created if the user runs `winget settings` and one of the following occurs:
1. First time use: Files settings.json or settings.json.backup don't exist. Winget will create both settings.json and settings.json.backup files using the default settings text. Winget will open settings.json in an editor.
-2. Settings.json deleted: If settings file doesn't exist but settings.json.backup exists. Settings file will be created after settings.json.backup. Winget starts settings.json in an editor. If the user intended to remove its settings the recommendation should be an empty json file, not deleting the file.
+2. settings.json deleted: If the settings file doesn't exist but settings.json.backup exists, the settings file will be created using settings.json.backup. Winget will open settings.json in an editor. If the user intended to remove their settings the recommendation should be an empty JSON file, not deleting the file.
-3. Settings.json and settings.json.backup deleted: Scenario is identical to 1.
+3. settings.json and settings.json.backup deleted: Scenario is identical to 1.
### Loading settings
@@ -103,24 +103,24 @@ else
use default settings
```
-Where valid means that syntax and semantic checks pass. For now, semantics checks will be part of the validation. If one settings is semantically incorrect and we fallback to backup proves to be annoying to users, checks can be relaxed into only syntax failures are fatal and semantic warnings. We could also in the future add a `winget settings validate` to improve the experience.
+Where valid means that syntax and semantic checks pass. For now, semantics checks will be part of the validation. If one setting is semantically incorrect and we fallback to backup proves to be annoying to users, checks can be relaxed so that only syntax failures are fatal and semantic errors are warnings. We could also in the future add a `winget settings validate` to improve the experience.
-We cannot force the user to upgrade, so it is possible for someone to add a setting for a future version that is not supported. There is not an easy way to detect it which mean loading the settings will warn of an unknown property. The user will need to verify the documentation and the version of winget that is running via `winget --info`.
+We cannot force the user to upgrade, so it is possible for someone to add a setting for a future version that is not supported. There is not an easy way to detect it which means that loading the settings will warn of an unknown property. The user will need to verify the documentation and the version of winget that is running via `winget --info`.
#### Errors and Warnings
-Loading settings will never fail, but warnings might happen. In addition about warning regarding syntax and semantic validation, a warning will be printed if backup is being used. If both settings and backup files failed to load and they exists another warning will be printed. There is no warning if the files don't exist. All these warnings must be localized as other text used in the project.
+Loading settings will never fail, but warnings might happen. In addition to warnings regarding syntax and semantic validation, a warning will be printed if settings.json.backup is being used. If both settings and backup files failed to load and they exist another warning will be printed. There is no warning if the files don't exist. All these warnings must be localized as other text used in the project.
- Settings Warning: Settings file failed loading. Using backup file.
-- Settings Warning: Settings backup failed loading. Using default settings.
+- Settings Backup Warning: Settings backup failed loading. Using default settings.
### Documentation
-All setting must be documented in the winget-cli repository in doc\Settings.md. The settings file will need to have a link to this file or some other Microsoft documentation site for reference.
+All settings must be documented in the winget-cli repository in doc\Settings.md. The settings file will need to have a link to this file or some other Microsoft documentation site for reference.
### Version property
-A version property can be added to the settings, such as the manifest has, to have a more structured validation. I am currently opposed at the idea because for future settings, we will need to always bump up the version and force the users to modify two pieces: the settings they want to use and the version property. I can also see settings growth more dynamic and bumping the version per addition/removal seems like an overkill.
+A version property can be added to the settings, such as the manifest has, to have a more structured validation. I am currently opposed to the idea because, for future settings, we will need to always bump up the version and force the users to modify two pieces: the settings they want to use and the version property. I can also see settings becoming more dynamic and bumping the version per addition/removal seems like an overkill.
### Settings
@@ -128,12 +128,12 @@ Two settings will be implemented for the sake of the discussion and to not provi
### Progress Bar Visual Style
-This setting will specify the color of the progress bar that WinGet displays. It will only support the current visual style that WinGet already support and no new ones will be added for now.
+This setting will specify the color of the progress bar that WinGet displays. It will only support the current visual style that WinGet already supports and no new ones will be added for now.
Possible values:
1. accent (default)
-1. rainbow
-1. plain
+2. retro
+3. rainbow
```
"Visual": {
@@ -201,9 +201,8 @@ If the file isn't intuitive users will experience difficulties setting what they
## Future considerations
-This feature allows the ability to expand the customization of winget for any user. It is also design to be expand with future settings commands that doesn't fit the scope of this future. For example, one could see `winget settings set SOME_SETTING on` to modify the settings without the need of editing a file.
+This feature allows the ability to expand the customization of winget for any user. It is also designed to be expanded with future settings commands that don't fit the scope of this feature. For example, one could use `winget settings set SOME_SETTING on` to modify the settings without the need of editing a file.
## References
-@JohnMcPMS for telling my what to type.
-
+@JohnMcPMS for telling me what to type.+
\ No newline at end of file
