From 50f0ec6a864a45bfa95e489d5a7ba3774b9ce796 Mon Sep 17 00:00:00 2001 From: Steve Lee Date: Wed, 31 Oct 2018 20:11:53 -0700 Subject: [PATCH 1/6] draft of experimental feature user experience rfc --- ...00-Experimental-Feature-User-Experience.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 1-Draft/RFC0000-Experimental-Feature-User-Experience.md diff --git a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md new file mode 100644 index 00000000..b0f57d4a --- /dev/null +++ b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md @@ -0,0 +1,87 @@ +--- +RFC: RFC0000 +Author: Steve Lee +Status: Draft +SupercededBy: N/A +Version: 1.0 +Area: Microsoft.PowerShell.Core +Comments Due: 12/1/2018 +Plan to implement: Yes +--- + +# Experimental Feature User Experience + +[Experimental Feature Flags](https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md) enable developers to expose experimental features to users to gather feedback before finalizing design. +That feature was focused on the developer and did not make it easy for users to discover and enable experimental features. +This RFC addresses the user experience. + +## Motivation + + As a PowerShell user, + I can discover and enable experimental features, + so that try new capabilities safely and provide feedback. + +## Specification + +### Get-ExperimentalFeature *Breaking Change* + +Currently, `Get-ExperimentalFeature` requires the `-ListAvailable` switch to enumerate available experimental features. +This was modeled after `Get-Module -ListAvailable`. +Without the switch, `Get-ExperimentalFeature` only shows the enabled experimental features, which by default is none. +Most users will try this cmdlet without the switch and assume there are no experimental features to try. + +Since there are likely not many experimental features available at any point in time and less enabled, +it would make sense to remove the `-ListAvailable` switch and simply display all experimental features. +The current output already has a column indicating if the experimental feature is enabled allowing for easy filtering. + +### User scope powershell.config.json + +Enabling experimental features require creating or updating a `powershell.config.json` file in `$PSHOME` which is read at startup. +In general, we should allow use of PowerShell Core without the need to be root or elevated. + +The change proposed is to support automatic loading of `powershell.config.json` from `$HOME\Documents\PowerShell\powershell.config.json` on Windows +and from `$HOME/.config/powershell/powershell.config.json` on Linux and macOS. + +If an admin has provided a `powershell.config.json` file in `$PSHOME` and the user has one in their scope, +then on `pwsh` startup, it will read the one in `$PSHOME` and clobber the properties that exist from the user configuration. + +Since this is configuration and not policy, the user configuration overrides the system configuration default settings. +The user can always prevent inheriting configuration from the system by explicitly starting `pwsh` with the +`-SettingsFile` parameter which will only read configuration from that specified file. + +### Enable and Disable cmdlets + +```none +Enable-ExperimentalFeature [[-Name] ] [-Scope ] [] + +Disable-ExperimentalFeature [[-Name] ] [-Scope ] [] +``` + +These cmdlets allow users to selectively enable and disable experimental features. + +The `-Name` parameter shall accept `ValueFromPipelineByPropertyName` and is the name of the experimental feature. + +The `-Scope` parameter is optional and defaults to `CurrentUser` and will create or update the +`powershell.config.json` in `$HOME\Documents\PowerShell\powershell.config.json` on Windows +and from `$HOME/.config/powershell/powershell.config.json` on Linux and macOS. +If `-Scope` is `System`, it will create or update `$PSHOME\powershell.config.json`. + +Experimental features are read and enabled at PowerShell startup, so a warning message will be provided informing the user: +> Experimental feature changes will only be applied after restarting PowerShell. + +## Alternate Proposals and Considerations + +### Configuration file + +In the case where there is both a system and current user configuration, +an alternate proposal is to not read the system configuration if the user configuration exists. +However, in the future, there may be useful configuration settings that make sense to have +as default values for a specific environment. + +### Enabled property + +Currently, an experimental feature has an `Enabled` property that is `true` or `false`. +In addition to the warning message that a restart is required after changing experimental feature status, +the `Enabled` property could be changed to an enum instead of a boolean: True, False, Pending. +However, since experimental features is expected to be used by more advanced users, +this seems unnecessary. From ea159a68778232856ef7fd5192596ba15f746059 Mon Sep 17 00:00:00 2001 From: Joel Bennett Date: Wed, 31 Oct 2018 20:59:52 -0700 Subject: [PATCH 2/6] Update 1-Draft/RFC0000-Experimental-Feature-User-Experience.md Co-Authored-By: SteveL-MSFT --- 1-Draft/RFC0000-Experimental-Feature-User-Experience.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md index b0f57d4a..da5ab971 100644 --- a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md +++ b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md @@ -19,7 +19,7 @@ This RFC addresses the user experience. As a PowerShell user, I can discover and enable experimental features, - so that try new capabilities safely and provide feedback. + so that I can try new capabilities safely and provide feedback. ## Specification From c86f6df0a2aa4fe21be056c53a9c25bd15b0d97d Mon Sep 17 00:00:00 2001 From: Steve Lee Date: Wed, 31 Oct 2018 21:02:51 -0700 Subject: [PATCH 3/6] address Joel's feedback --- 1-Draft/RFC0000-Experimental-Feature-User-Experience.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md index da5ab971..fcca6bce 100644 --- a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md +++ b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md @@ -52,9 +52,9 @@ The user can always prevent inheriting configuration from the system by explicit ### Enable and Disable cmdlets ```none -Enable-ExperimentalFeature [[-Name] ] [-Scope ] [] +Enable-ExperimentalFeature [[-Name] ] [-Scope { CurrentUser | AllUsers }] [] -Disable-ExperimentalFeature [[-Name] ] [-Scope ] [] +Disable-ExperimentalFeature [[-Name] ] [-Scope { CurrentUser | AllUsers }] [] ``` These cmdlets allow users to selectively enable and disable experimental features. @@ -64,7 +64,7 @@ The `-Name` parameter shall accept `ValueFromPipelineByPropertyName` and is the The `-Scope` parameter is optional and defaults to `CurrentUser` and will create or update the `powershell.config.json` in `$HOME\Documents\PowerShell\powershell.config.json` on Windows and from `$HOME/.config/powershell/powershell.config.json` on Linux and macOS. -If `-Scope` is `System`, it will create or update `$PSHOME\powershell.config.json`. +If `-Scope` is `AllUsers`, it will create or update `$PSHOME\powershell.config.json`. Experimental features are read and enabled at PowerShell startup, so a warning message will be provided informing the user: > Experimental feature changes will only be applied after restarting PowerShell. From 2360f5fc3868e738e04d39b461850da809dc71c9 Mon Sep 17 00:00:00 2001 From: Steve Lee Date: Fri, 2 Nov 2018 22:30:43 -0700 Subject: [PATCH 4/6] updated section on system and user scope of configuration which already exists today --- ...00-Experimental-Feature-User-Experience.md | 27 +++++-------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md index fcca6bce..50c81291 100644 --- a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md +++ b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md @@ -11,7 +11,8 @@ Plan to implement: Yes # Experimental Feature User Experience -[Experimental Feature Flags](https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md) enable developers to expose experimental features to users to gather feedback before finalizing design. +[Experimental Feature Flags](https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md) +enable developers to expose experimental features to users to gather feedback before finalizing design. That feature was focused on the developer and did not make it easy for users to discover and enable experimental features. This RFC addresses the user experience. @@ -34,20 +35,13 @@ Since there are likely not many experimental features available at any point in it would make sense to remove the `-ListAvailable` switch and simply display all experimental features. The current output already has a column indicating if the experimental feature is enabled allowing for easy filtering. -### User scope powershell.config.json +### System and User scope powershell.config.json -Enabling experimental features require creating or updating a `powershell.config.json` file in `$PSHOME` which is read at startup. -In general, we should allow use of PowerShell Core without the need to be root or elevated. +Enabling experimental features automatically requires creating or updating a `powershell.config.json` file in `$PSHOME` +which is read at startup which affects all users or from `$HOME\Documents\PowerShell\powershell.config.json` on Windows +and from `$HOME/.config/powershell/powershell.config.json` on Linux and macOS per user. -The change proposed is to support automatic loading of `powershell.config.json` from `$HOME\Documents\PowerShell\powershell.config.json` on Windows -and from `$HOME/.config/powershell/powershell.config.json` on Linux and macOS. - -If an admin has provided a `powershell.config.json` file in `$PSHOME` and the user has one in their scope, -then on `pwsh` startup, it will read the one in `$PSHOME` and clobber the properties that exist from the user configuration. - -Since this is configuration and not policy, the user configuration overrides the system configuration default settings. -The user can always prevent inheriting configuration from the system by explicitly starting `pwsh` with the -`-SettingsFile` parameter which will only read configuration from that specified file. +This is existing behavior and will not be changed as part of this RFC. ### Enable and Disable cmdlets @@ -71,13 +65,6 @@ Experimental features are read and enabled at PowerShell startup, so a warning m ## Alternate Proposals and Considerations -### Configuration file - -In the case where there is both a system and current user configuration, -an alternate proposal is to not read the system configuration if the user configuration exists. -However, in the future, there may be useful configuration settings that make sense to have -as default values for a specific environment. - ### Enabled property Currently, an experimental feature has an `Enabled` property that is `true` or `false`. From 3dff4ad4a69f69bd7700129dcedd6265600c41ea Mon Sep 17 00:00:00 2001 From: Steve Lee Date: Wed, 28 Nov 2018 12:34:56 -0800 Subject: [PATCH 5/6] address feedback from PS-Committee --- ...00-Experimental-Feature-User-Experience.md | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md index 50c81291..2090f294 100644 --- a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md +++ b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md @@ -41,7 +41,11 @@ Enabling experimental features automatically requires creating or updating a `po which is read at startup which affects all users or from `$HOME\Documents\PowerShell\powershell.config.json` on Windows and from `$HOME/.config/powershell/powershell.config.json` on Linux and macOS per user. -This is existing behavior and will not be changed as part of this RFC. +Experimental features are currently not being read from the user config and this RFC will enable reading +of the user config in addition to the system config. +In the case where the user config exists, it will take precedence over the system config for experimental features +in that the system config is not read for experimental features. +System config is not policy so this should be acceptable and expected. ### Enable and Disable cmdlets @@ -72,3 +76,25 @@ In addition to the warning message that a restart is required after changing exp the `Enabled` property could be changed to an enum instead of a boolean: True, False, Pending. However, since experimental features is expected to be used by more advanced users, this seems unnecessary. + +Alternatively, we can add a `RestartRequired` property to indicate an enabled feature is pending. + +### Features that were previously Experimental + +In the case where an Experimental Feature no longer experimental (whether accepted or rejected), +the config file may still have that feature listed. +We can add a `State` property that has enum values: Available, NotAvailable. +This `State` can also convey the `RestartRequired` state. +If this becomes a problem in the future, we can have cmdlets to help clean-up non-valid settings in the +configuration (which will be more than just experimental features). +Since this is additive, this is currently outside the scope of this RFC. + +### PowerShell instance specific configuration + +The system (AllUsers) configuration is in `$PSHOME` and specific to that instance of PowerShell. +The user config is global to all instances of PowerShell which can create problems. +For experimental features, this is not a big issue as experimental features listed to +be enabled in the config file that don't exist are silently ignored. +However, other configuration that one may want to apply to a preview release and not a +stable release cannot be applied except for AllUsers currently. +This should be addressed in a separate configuration RFC. From 37999c07b8915fee24b94f6fde64629152d57e23 Mon Sep 17 00:00:00 2001 From: Steve Lee Date: Tue, 4 Dec 2018 14:46:29 -0800 Subject: [PATCH 6/6] update output to nothing based on PR review --- 1-Draft/RFC0000-Experimental-Feature-User-Experience.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md index 2090f294..d71555c9 100644 --- a/1-Draft/RFC0000-Experimental-Feature-User-Experience.md +++ b/1-Draft/RFC0000-Experimental-Feature-User-Experience.md @@ -67,6 +67,8 @@ If `-Scope` is `AllUsers`, it will create or update `$PSHOME\powershell.config.j Experimental features are read and enabled at PowerShell startup, so a warning message will be provided informing the user: > Experimental feature changes will only be applied after restarting PowerShell. +Upon success, there is no output other than the warning message. + ## Alternate Proposals and Considerations ### Enabled property