From 9345e28f2ea19366a1538dc02df6b25d52299fb9 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Wed, 9 Sep 2020 17:04:06 -0400 Subject: [PATCH 01/28] Proto extensions spec (draft) --- doc/specs/Proto extensions-spec.md | 139 +++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 doc/specs/Proto extensions-spec.md diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md new file mode 100644 index 00000000000..2beefe6db0a --- /dev/null +++ b/doc/specs/Proto extensions-spec.md @@ -0,0 +1,139 @@ +--- +author: <@PankajBhojwani> +created on: <2020-9-9> +last updated: <2020-9-9> +--- + +# Proto extensions + +## Abstract + +This spec outlines adding support for proto extensions. This would allow other apps/programs +to add json snippets to our json files, and will be used when we generate settings for our various profiles. + +## Inspiration + +### Goal: Allow programs to have a say in the settings for their profiles + +Currently, Ubuntu/WSL/Powershell etc are unable to provide any specifications for how they want +their profiles in Terminal to look - only we and the users can modify the profiles. We want to provide +these installations with the functionality to have a say in this, allowing them to specify things like +their icon, their font and so on. However, we want to maintain that the user has final say over all of +these settings. + +## Solution Design + +Currently, when we load the settings we perform the following steps (this is a simplified description, +for the full version see the spec for cascading default + user settings): + +1. Generate profiles from the defaults file +2. Generate profiles from the dynamic profile generators +3. Layer the user settings on top of all the profiles created in steps 1 and 2 +4. Validate the settings + +To allow for installations to add in their snippets of json, I propose the addition of a new step +in between 2 and 3: + +1. Generate profiles from the defaults file +2. Generate profiles from the dynamic profile generators +3. **Incorporate the additional provided json stubs** - these stubs could be: + 1. modifications to existing profiles + 2. full profiles + 3. colour schemes/modifications to colour schemes +4. Layer the user settings on top of all the profiles created in steps 1 through 3 +5. Validate the settings + +### Specifications of the json stubs + +As written above, the json stubs could be modifications to existing profiles, full profiles, or colour schemes. + +#### Modifications to existing profiles + +For modifications to existing profiles, the json stub would need to indicate which profile it wishes to modify. +A straightforward way to do this would be by providing the name of the profile. Since this modification would +occur at the step _before_ any user changes to names are layered, the names of the profiles are consistent and +can be used for identification. For example, the name of a profile generated by the WSL profile generator is +simply the argument to "wsl.exe -d \", the name of a profile generated by the Powershell profile generator +would be "Powershell Core" or "Powershell (ARM)" etc depending on the version. + +We might run into the case where multiple json stubs modify the same profile and so they override each other. We +will need some sort of hierarchy to determine which stub to ultimately use. My initial thought is that we could +check the owner of the json file and see if it matches the profile they are trying to modify (so something like +only Powershell can modify the Powershell profiles and only Ubuntu can modify the Ubuntu profile etc). Independent +parties will need to create full profiles with the desired commandline argument instead. + +#### Full profile stubs + +Technically, full profile stubs do not need to contain anything (they could just be '\{\}'). However we should +have some qualifying minimum criteria before we accept a stub as a full profile. I suggest that we only create +new profile objects from stubs that contain at least the following + +* A name (and this name _should not_ match the names of existing profiles as described above, because that would cause us to interpret this profile as modifying an existing one) +* A commandline argument +* A unique GUID - this is so we avoid conflicts if several different creators name their profile the same thing + +As in the case of the dynamic profile generator, if we create a profile that did not exist before (i.e. does not +exist in the user settings), we need to add the profile to the user settings file and re-save that file. + +#### Colour schemes + +Once again, we could run into the problem of several json stubs wanting to modify the same colour scheme. We +will require a hierarchy here as well. Though since the 'owner' of a colour scheme is a lot more dubious, I wonder +if we should only allow creation of new colour schemes for now and ignore requests to modify existing colour +schemes. + +### Location(s) of the json files + +For apps that are installed 'traditionally', their installer could simply add a json file to a specific local folder +(specified by us) that we will look through every time we generate profiles. This is also where users can add +their own json files for Terminal to generate profiles from. + +For apps that are installed through something like the Microsoft Store, they should add their json stub(s) to +an app extension. We will then obtain them during profile generation. + +## UI/UX Design + +This feature will allow other installations a level of control over how their profiles look in Terminal. For example, +if Ubuntu gets a new icon or a new font they can have those changes be reflected in Terminal users' Ubuntu profiles. + +Furthermore, this allows users an easy way to share profiles they have created - instead of needing to modify their +settings file directly they could simply download a json file into a specific folder. + +## Capabilities + +### Accessibility + +This change should not affect accessibility. + +### Security + +Opening a profile causes its commandline argument to be automatically run. Thus, if malicious modifications are made +to existing profiles or new profiles with malicious commandline arguments are added, users could be tricked into running +things they do not want to. + +### Reliability + +This should not affect reliability - most of what its doing is simply layering json which we already do. + +### Compatibility + +Again, there should not be any issues here - the user settings can still be layered after this layering for the user +to have the final say. + +### Performance, Power, and Efficiency + +Looking through the additional json files could negatively impact startup time. + +## Potential Issues + +Cases which would likely be frustrating: + +* An installer dumps a _lot_ of json files into the folder which we need to look through + +## Future considerations + +How would this affect the Settings UI? + +## Resources + +N/A From 667ee27c0086b4a3c8b036f8887482f2eb49d895 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Wed, 9 Sep 2020 19:58:53 -0400 Subject: [PATCH 02/28] edits --- doc/specs/Proto extensions-spec.md | 33 ++++++++++++++++++------------ 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 2beefe6db0a..e937a54702a 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -24,7 +24,7 @@ these settings. ## Solution Design Currently, when we load the settings we perform the following steps (this is a simplified description, -for the full version see the spec for cascading default + user settings): +for the full version see the [spec for cascading default + user settings](https://github.com/microsoft/terminal/blob/master/doc/specs/%23754%20-%20Cascading%20Default%20Settings.md)): 1. Generate profiles from the defaults file 2. Generate profiles from the dynamic profile generators @@ -38,29 +38,36 @@ in between 2 and 3: 2. Generate profiles from the dynamic profile generators 3. **Incorporate the additional provided json stubs** - these stubs could be: 1. modifications to existing profiles - 2. full profiles - 3. colour schemes/modifications to colour schemes + 2. additions of full profiles + 3. additions of colour schemes + 4. modifications to colour schemes 4. Layer the user settings on top of all the profiles created in steps 1 through 3 5. Validate the settings ### Specifications of the json stubs -As written above, the json stubs could be modifications to existing profiles, full profiles, or colour schemes. +As written above, the json stubs could be modifications to existing profiles, additions to full profiles, modifications to +existing colour schemes or additions of colour schemes. #### Modifications to existing profiles +The main thing to note for modification of existing profiles is that this will only be used for modifying the +default profiles (cmd/powershell) or the dynamically generated profiles. + For modifications to existing profiles, the json stub would need to indicate which profile it wishes to modify. -A straightforward way to do this would be by providing the name of the profile. Since this modification would -occur at the step _before_ any user changes to names are layered, the names of the profiles are consistent and -can be used for identification. For example, the name of a profile generated by the WSL profile generator is -simply the argument to "wsl.exe -d \", the name of a profile generated by the Powershell profile generator -would be "Powershell Core" or "Powershell (ARM)" etc depending on the version. +Note that currently, we generate a GUID for dynamic profiles using the "initial" name of the profile (i.e. before +any user changes are applied). For example, the "initial" name of a WSL profile is the \ argument to +"wsl.exe -d \", and the "initial" name of a Powershell profile is something like "Powershell (ARM)" - depending +on the version. Thus, the stub creator could simply use the same uuidv5 GUID generator we do on that name to obtain the +GUID. Then, in the stub they provide the GUID can be used to identify which profile to modify. + +Since dynamic profiles also have a "source" field which we use as matching criteria, the stub would also need to +have that field if it wants to modify a dynamic profile. These are just static strings that we can easily provide. We might run into the case where multiple json stubs modify the same profile and so they override each other. We -will need some sort of hierarchy to determine which stub to ultimately use. My initial thought is that we could -check the owner of the json file and see if it matches the profile they are trying to modify (so something like -only Powershell can modify the Powershell profiles and only Ubuntu can modify the Ubuntu profile etc). Independent -parties will need to create full profiles with the desired commandline argument instead. +will need some sort of hierarchy to determine which stub to ultimately use. For the initial implementation, we +are simply going to apply _all_ the changes. Eventually, we will probably want some sort of hierarchy to determine +an order to which changes are applied. #### Full profile stubs From 969593edae2ba880c347d2707411d88333af26b8 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 10 Sep 2020 10:54:31 -0400 Subject: [PATCH 03/28] examples --- doc/specs/Proto extensions-spec.md | 48 +++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 10 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index e937a54702a..b506d53398b 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -64,10 +64,20 @@ GUID. Then, in the stub they provide the GUID can be used to identify which prof Since dynamic profiles also have a "source" field which we use as matching criteria, the stub would also need to have that field if it wants to modify a dynamic profile. These are just static strings that we can easily provide. -We might run into the case where multiple json stubs modify the same profile and so they override each other. We -will need some sort of hierarchy to determine which stub to ultimately use. For the initial implementation, we +We might run into the case where multiple json stubs modify the same profile and so they override each other. For the initial implementation, we are simply going to apply _all_ the changes. Eventually, we will probably want some sort of hierarchy to determine -an order to which changes are applied. +an order to which changes are applied. + +Here is an example of a json stub that modifies an existing profile (specifically the Azure cloud shell profile): + +```js +{ + "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", + "source": "Windows.Terminal.Azure", + "fontSize": 16, + "fontWeight": "thin" +} +``` #### Full profile stubs @@ -80,7 +90,20 @@ new profile objects from stubs that contain at least the following * A unique GUID - this is so we avoid conflicts if several different creators name their profile the same thing As in the case of the dynamic profile generator, if we create a profile that did not exist before (i.e. does not -exist in the user settings), we need to add the profile to the user settings file and re-save that file. +exist in the user settings), we need to add the profile to the user settings file and re-save that file. + +Here is an example of a json stub that contains a full profile: + +```js +{ + "guid": "{a821ae62-9d4a-3e34-b989-0a998ec283e6}", + "name": "Cool Profile", + "comandline": "powershell.exe", + "antialiasingMode": "aliased", + "fontWeight": "bold", + "scrollbarState": "hidden" +} +``` #### Colour schemes @@ -89,14 +112,19 @@ will require a hierarchy here as well. Though since the 'owner' of a colour sche if we should only allow creation of new colour schemes for now and ignore requests to modify existing colour schemes. -### Location(s) of the json files +### Creation and location(s) of the json files -For apps that are installed 'traditionally', their installer could simply add a json file to a specific local folder -(specified by us) that we will look through every time we generate profiles. This is also where users can add -their own json files for Terminal to generate profiles from. +#### For apps installed through Microsoft store (or similar) + +For apps that are installed through something like the Microsoft Store, they should add their json file(s) to +an app extension. During our profile generation, we will probe the OS for app extensions of this type that it +knows about and obtain the json files. -For apps that are installed through something like the Microsoft Store, they should add their json stub(s) to -an app extension. We will then obtain them during profile generation. +#### For apps installed 'traditionally' and third parties/independent users + +For apps that are installed 'traditionally', their installer could simply add a json file to a specific local folder +(specified by us) that we will look through every time we generate profiles. This is also where independent users will +add their own json files for Terminal to generate/modify profiles. ## UI/UX Design From 56d68929a2981619200f3036301da3cf53d59bfb Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 10 Sep 2020 11:01:04 -0400 Subject: [PATCH 04/28] good bot --- doc/specs/Proto extensions-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index b506d53398b..15e69c58ce9 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -98,7 +98,7 @@ Here is an example of a json stub that contains a full profile: { "guid": "{a821ae62-9d4a-3e34-b989-0a998ec283e6}", "name": "Cool Profile", - "comandline": "powershell.exe", + "commandline": "powershell.exe", "antialiasingMode": "aliased", "fontWeight": "bold", "scrollbarState": "hidden" From f56a0b0959c630cf244821a3da0eb4cf92fcebc4 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 10 Sep 2020 15:31:18 -0400 Subject: [PATCH 05/28] additional potential issue --- doc/specs/Proto extensions-spec.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 15e69c58ce9..8d261a9be67 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -164,6 +164,7 @@ Looking through the additional json files could negatively impact startup time. Cases which would likely be frustrating: * An installer dumps a _lot_ of json files into the folder which we need to look through +* An installer dumps some badly formatted settings that cause our validate settings check to fail, resulting in default settings being used everywhere ## Future considerations From 1c196db61c20c9b491f7d1f6674b037f88e8ed21 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Fri, 11 Sep 2020 15:30:07 -0400 Subject: [PATCH 06/28] more details and clarity --- doc/specs/Proto extensions-spec.md | 113 ++++++++++++++++++++++++----- 1 file changed, 94 insertions(+), 19 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 8d261a9be67..6daadac52e6 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -40,14 +40,12 @@ in between 2 and 3: 1. modifications to existing profiles 2. additions of full profiles 3. additions of colour schemes - 4. modifications to colour schemes 4. Layer the user settings on top of all the profiles created in steps 1 through 3 5. Validate the settings ### Specifications of the json stubs -As written above, the json stubs could be modifications to existing profiles, additions to full profiles, modifications to -existing colour schemes or additions of colour schemes. +As written above, the json stubs could be modifications to existing profiles, additions to full profiles, or additions of colour schemes. #### Modifications to existing profiles @@ -59,10 +57,10 @@ Note that currently, we generate a GUID for dynamic profiles using the "initial" any user changes are applied). For example, the "initial" name of a WSL profile is the \ argument to "wsl.exe -d \", and the "initial" name of a Powershell profile is something like "Powershell (ARM)" - depending on the version. Thus, the stub creator could simply use the same uuidv5 GUID generator we do on that name to obtain the -GUID. Then, in the stub they provide the GUID can be used to identify which profile to modify. +GUID. Then, in the stub they provide the GUID can be used to identify which profile to modify. -Since dynamic profiles also have a "source" field which we use as matching criteria, the stub would also need to -have that field if it wants to modify a dynamic profile. These are just static strings that we can easily provide. +Naturally, we will have to provide documentation on how they could generate the desired GUID themselves. In that documentation, +we will also provide examples showing how the current GUIDs are generated for clarity's sake. We might run into the case where multiple json stubs modify the same profile and so they override each other. For the initial implementation, we are simply going to apply _all_ the changes. Eventually, we will probably want some sort of hierarchy to determine @@ -73,12 +71,24 @@ Here is an example of a json stub that modifies an existing profile (specificall ```js { "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", - "source": "Windows.Terminal.Azure", "fontSize": 16, "fontWeight": "thin" } ``` +**NOTE**: This will *not* change the way the profile looks in the user's settings file. The Azure cloud shell profile +in their settings file (assuming they have made no changes) will still be as below. + +```js +{ + "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", + "hidden": false, + "name": "Azure Cloud Shell", + "source": "Windows.Terminal.Azure" +} +``` +However, the user is free to make changes to it as usual and those changes will have the 'final say'. + #### Full profile stubs Technically, full profile stubs do not need to contain anything (they could just be '\{\}'). However we should @@ -92,6 +102,10 @@ new profile objects from stubs that contain at least the following As in the case of the dynamic profile generator, if we create a profile that did not exist before (i.e. does not exist in the user settings), we need to add the profile to the user settings file and re-save that file. +Furthermore, we will add a source field to profiles created this way (again, similar to what we do for dynamic profiles). +The source field value is dependent on how we obtained this json file, and will be touched on in more detail later in the +spec (see "Creation and location(s) of the json files" - "The source field"). + Here is an example of a json stub that contains a full profile: ```js @@ -105,12 +119,42 @@ Here is an example of a json stub that contains a full profile: } ``` -#### Colour schemes +When this profile gets added back to the user's settings file, it will look similar to the way we currently add +new dynamic profiles to the user's settings file. Going along with the example above, the corresponding +json stub in the user's settings file will be: + +```js +{ + "guid": "{a821ae62-9d4a-3e34-b989-0a998ec283e6}", + "name": "Cool Profile", + "hidden": "false", + "source": "local" +} +``` +Again, the user will be able to make changes to it as they do for all other profiles. + +#### Creation of colour schemes + +As with full profiles, we will have some qualifying criteria for what we accept as full colour schemes: color schemes +must have +* A name +* A background +* A foreground + +This will cause the issue of colour schemes being overridden if there are many creations of a colour scheme with the +same name. Since for now all we have to uniquely identify colour schemes *is* the name, we will just let this be. -Once again, we could run into the problem of several json stubs wanting to modify the same colour scheme. We -will require a hierarchy here as well. Though since the 'owner' of a colour scheme is a lot more dubious, I wonder -if we should only allow creation of new colour schemes for now and ignore requests to modify existing colour -schemes. +Here is an example of a json stub that contains a colour scheme: + +```js +{ + "name": "Postmodern Tango Light", + "background": '#61D6D6', + "foreground": '#E74856' +} +``` + +This stub will *not* show up in the users settings file, similar to the way our default colour schemes do not show up. ### Creation and location(s) of the json files @@ -118,13 +162,45 @@ schemes. For apps that are installed through something like the Microsoft Store, they should add their json file(s) to an app extension. During our profile generation, we will probe the OS for app extensions of this type that it -knows about and obtain the json files. +knows about and obtain the json files or objects. These apps should should use msappx for us to know about +their extensions. #### For apps installed 'traditionally' and third parties/independent users -For apps that are installed 'traditionally', their installer could simply add a json file to a specific local folder -(specified by us) that we will look through every time we generate profiles. This is also where independent users will -add their own json files for Terminal to generate/modify profiles. +For apps that are installed 'traditionally', there are 2 cases. The first is that this installation is for all +the users of the system - in this case, the installer should add their json files to the global folder: + +``` +C:\ProgramData\Microsoft\Windows\Terminal +``` + +Note: `C:\ProgramData` is a [known folder](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/bb776911(v=vs.85)) +that apps should be able to access. It will be on us to create the folder `Terminal` in `C:\ProgramData\Microsoft\Windows` for this to happen. + +In the second case, the installation is only for the current user. For this case, the installer should add the +json files to the local folder: + +```C:\Users\\AppData\Local\Microsoft\Windows\Terminal``` + +This is also where independent users will add their own json files for Terminal to generate/modify profiles. + +We will look through both folders mentioned above during profile generation. + +#### The source field + +Currently, we allow users an easy way to disable/enable profiles that are generated from certain sources. For +example, a user can easily hide all dynamic profiles with the source `"Windows.Terminal.Wsl"` if they wish to. +To retain this functionality, we will add source fields to profiles we create through proto-extensions. + +For full profiles that came from the *global* folder `C:\ProgramData\Microsoft\Windows\Terminal`, +we will give the value `global` to the source field. + +For full profiles that came from the *local* folder `C:\Users\\AppData\Local\Microsoft\Windows\Terminal`, +we will give the value `local` to the source field. + +For full profiles that came from app extensions, we will the value `app` to the source field. + + ## UI/UX Design @@ -163,12 +239,11 @@ Looking through the additional json files could negatively impact startup time. Cases which would likely be frustrating: -* An installer dumps a _lot_ of json files into the folder which we need to look through -* An installer dumps some badly formatted settings that cause our validate settings check to fail, resulting in default settings being used everywhere +* An installer dumps a _lot_ of json files into the folder which we need to look through. ## Future considerations -How would this affect the Settings UI? +How will this affect the settings UI? ## Resources From 6024b440b7ad8bac7dfa03dcb03520476ae57fda Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Fri, 11 Sep 2020 15:37:21 -0400 Subject: [PATCH 07/28] spell --- .github/actions/spell-check/dictionary/apis.txt | 1 + .github/actions/spell-check/dictionary/dictionary.txt | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/actions/spell-check/dictionary/apis.txt b/.github/actions/spell-check/dictionary/apis.txt index 6e450ee12bb..79ac19cffaa 100644 --- a/.github/actions/spell-check/dictionary/apis.txt +++ b/.github/actions/spell-check/dictionary/apis.txt @@ -27,6 +27,7 @@ llabs LCID lround LSHIFT +msappx NCHITTEST NCLBUTTONDBLCLK NCRBUTTONDBLCLK diff --git a/.github/actions/spell-check/dictionary/dictionary.txt b/.github/actions/spell-check/dictionary/dictionary.txt index 7344a626ea2..ba75c0ca90d 100644 --- a/.github/actions/spell-check/dictionary/dictionary.txt +++ b/.github/actions/spell-check/dictionary/dictionary.txt @@ -313153,6 +313153,7 @@ post-Mishnical postmistress postmistresses postmistress-ship +postmodern postmortal post-mortem postmortem From e406c98b52bbf2662bb99828bf492dda7c65d71d Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Fri, 11 Sep 2020 15:42:38 -0400 Subject: [PATCH 08/28] small fix --- doc/specs/Proto extensions-spec.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 6daadac52e6..33f34ba12c4 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -198,7 +198,7 @@ we will give the value `global` to the source field. For full profiles that came from the *local* folder `C:\Users\\AppData\Local\Microsoft\Windows\Terminal`, we will give the value `local` to the source field. -For full profiles that came from app extensions, we will the value `app` to the source field. +For full profiles that came from app extensions, we will give the value `app` to the source field. @@ -208,7 +208,8 @@ This feature will allow other installations a level of control over how their pr if Ubuntu gets a new icon or a new font they can have those changes be reflected in Terminal users' Ubuntu profiles. Furthermore, this allows users an easy way to share profiles they have created - instead of needing to modify their -settings file directly they could simply download a json file into a specific folder. +settings file directly they could simply download a json file into the folder +`C:\Users\\AppData\Local\Microsoft\Windows\Terminal`. ## Capabilities From 56d351d6183f46e8fac352f8d91de541198758f2 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Fri, 11 Sep 2020 16:19:15 -0400 Subject: [PATCH 09/28] forgot to update this --- doc/specs/Proto extensions-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 33f34ba12c4..b82ba0c064d 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -95,7 +95,7 @@ Technically, full profile stubs do not need to contain anything (they could just have some qualifying minimum criteria before we accept a stub as a full profile. I suggest that we only create new profile objects from stubs that contain at least the following -* A name (and this name _should not_ match the names of existing profiles as described above, because that would cause us to interpret this profile as modifying an existing one) +* A name * A commandline argument * A unique GUID - this is so we avoid conflicts if several different creators name their profile the same thing From e388c07ab832d08c76cec16aabe287fd874ad6c3 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Mon, 14 Sep 2020 11:08:39 -0400 Subject: [PATCH 10/28] small clarification --- doc/specs/Proto extensions-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index b82ba0c064d..5b13a7cbaf8 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -40,7 +40,7 @@ in between 2 and 3: 1. modifications to existing profiles 2. additions of full profiles 3. additions of colour schemes -4. Layer the user settings on top of all the profiles created in steps 1 through 3 +4. Layer the user settings on top of all the profiles created in steps 1 through 3 (this includes the user-defined default settings which they wish to apply to all profiles) 5. Validate the settings ### Specifications of the json stubs From 7d3af2f9d8442acac4bf72039d4ccfb686221605 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Mon, 14 Sep 2020 18:18:05 -0400 Subject: [PATCH 11/28] don't need full profiles to provide a GUID --- doc/specs/Proto extensions-spec.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 5b13a7cbaf8..bc305d4dd2c 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -97,7 +97,6 @@ new profile objects from stubs that contain at least the following * A name * A commandline argument -* A unique GUID - this is so we avoid conflicts if several different creators name their profile the same thing As in the case of the dynamic profile generator, if we create a profile that did not exist before (i.e. does not exist in the user settings), we need to add the profile to the user settings file and re-save that file. From b86407455c2457984cbc2f7807273c725934b748 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Wed, 16 Sep 2020 13:57:04 -0400 Subject: [PATCH 12/28] stubs must be put into lists --- doc/specs/Proto extensions-spec.md | 50 +++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 14 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index bc305d4dd2c..3fc065f9e2b 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -47,6 +47,16 @@ in between 2 and 3: As written above, the json stubs could be modifications to existing profiles, additions to full profiles, or additions of colour schemes. +To allow modifications/additions of several profiles in one file and to allow the addition of several colour schemes in one json file, +these stubs should be put into lists in the json file: one list named ```profiles``` and the other list named ```schemes```. For example: + +```js +{ + "profiles": [ modifications and additions of profiles go here ], + "schemes": [ additions of colour schemes go here ] +} +``` + #### Modifications to existing profiles The main thing to note for modification of existing profiles is that this will only be used for modifying the @@ -66,13 +76,17 @@ We might run into the case where multiple json stubs modify the same profile and are simply going to apply _all_ the changes. Eventually, we will probably want some sort of hierarchy to determine an order to which changes are applied. -Here is an example of a json stub that modifies an existing profile (specifically the Azure cloud shell profile): +Here is an example of a json file that modifies an existing profile (specifically the Azure cloud shell profile): ```js { - "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", - "fontSize": 16, - "fontWeight": "thin" + "profiles": [ + { + "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", + "fontSize": 16, + "fontWeight": "thin" + } + ] } ``` @@ -105,16 +119,20 @@ Furthermore, we will add a source field to profiles created this way (again, sim The source field value is dependent on how we obtained this json file, and will be touched on in more detail later in the spec (see "Creation and location(s) of the json files" - "The source field"). -Here is an example of a json stub that contains a full profile: +Here is an example of a json file that contains a full profile: ```js { - "guid": "{a821ae62-9d4a-3e34-b989-0a998ec283e6}", - "name": "Cool Profile", - "commandline": "powershell.exe", - "antialiasingMode": "aliased", - "fontWeight": "bold", - "scrollbarState": "hidden" + "profiles": [ + { + "guid": "{a821ae62-9d4a-3e34-b989-0a998ec283e6}", + "name": "Cool Profile", + "commandline": "powershell.exe", + "antialiasingMode": "aliased", + "fontWeight": "bold", + "scrollbarState": "hidden" + } + ] } ``` @@ -147,9 +165,13 @@ Here is an example of a json stub that contains a colour scheme: ```js { - "name": "Postmodern Tango Light", - "background": '#61D6D6', - "foreground": '#E74856' + "schemes": [ + { + "name": "Postmodern Tango Light", + "background": '#61D6D6', + "foreground": '#E74856' + } + ] } ``` From 54981db70a193110b60f5f44a1d92e47b8661e1c Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Wed, 16 Sep 2020 14:43:47 -0400 Subject: [PATCH 13/28] example of a full file --- doc/specs/Proto extensions-spec.md | 33 ++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 3fc065f9e2b..05cee2f5a43 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -57,6 +57,8 @@ these stubs should be put into lists in the json file: one list named ```profile } ``` +An example of a full json file with these fields filled out is shown at the end of this section. + #### Modifications to existing profiles The main thing to note for modification of existing profiles is that this will only be used for modifying the @@ -177,6 +179,37 @@ Here is an example of a json stub that contains a colour scheme: This stub will *not* show up in the users settings file, similar to the way our default colour schemes do not show up. +#### Example of a full json file +This is an example of a json file that combines all the above examples. Thus, this json file modifies the Azure Cloud +Shell profile, creates a new profile called 'Cool Profile' and creates a new colour scheme called 'Postmodern Tango Light'. + +```js +{ + "profiles": [ + { + "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", + "fontSize": 16, + "fontWeight": "thin" + }, + { + "guid": "{a821ae62-9d4a-3e34-b989-0a998ec283e6}", + "name": "Cool Profile", + "commandline": "powershell.exe", + "antialiasingMode": "aliased", + "fontWeight": "bold", + "scrollbarState": "hidden" + } + ], + "schemes": [ + { + "name": "Postmodern Tango Light", + "background": "#61D6D6", + "foreground": "#E74856" + } + ] +} +``` + ### Creation and location(s) of the json files #### For apps installed through Microsoft store (or similar) From 08d7731082ece8e1208a1d3375af5b98ef9dd0d0 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Wed, 16 Sep 2020 15:01:57 -0400 Subject: [PATCH 14/28] formatting --- doc/specs/Proto extensions-spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 05cee2f5a43..efbe6f29d47 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -234,7 +234,9 @@ that apps should be able to access. It will be on us to create the folder `Termi In the second case, the installation is only for the current user. For this case, the installer should add the json files to the local folder: -```C:\Users\\AppData\Local\Microsoft\Windows\Terminal``` +``` +C:\Users\\AppData\Local\Microsoft\Windows\Terminal +``` This is also where independent users will add their own json files for Terminal to generate/modify profiles. From 4ccee5c24991ecf5f5beb5bfda5a68e64a91d058 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Wed, 16 Sep 2020 17:12:19 -0400 Subject: [PATCH 15/28] update folders --- doc/specs/Proto extensions-spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index efbe6f29d47..7b37fcfc6ff 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -225,7 +225,7 @@ For apps that are installed 'traditionally', there are 2 cases. The first is tha the users of the system - in this case, the installer should add their json files to the global folder: ``` -C:\ProgramData\Microsoft\Windows\Terminal +C:\ProgramData\Microsoft\Windows Terminal\Fragments ``` Note: `C:\ProgramData` is a [known folder](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/bb776911(v=vs.85)) @@ -235,7 +235,7 @@ In the second case, the installation is only for the current user. For this case json files to the local folder: ``` -C:\Users\\AppData\Local\Microsoft\Windows\Terminal +C:\Users\\AppData\Local\Microsoft\Windows Terminal\Fragments ``` This is also where independent users will add their own json files for Terminal to generate/modify profiles. From 32569c778cc15b520ce7e759ca80fbe9395c7475 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 17 Sep 2020 21:13:20 -0400 Subject: [PATCH 16/28] specifics for app extensions --- doc/specs/Proto extensions-spec.md | 57 +++++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 8 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 7b37fcfc6ff..9a5f090d759 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -214,10 +214,51 @@ Shell profile, creates a new profile called 'Cool Profile' and creates a new col #### For apps installed through Microsoft store (or similar) -For apps that are installed through something like the Microsoft Store, they should add their json file(s) to -an app extension. During our profile generation, we will probe the OS for app extensions of this type that it -knows about and obtain the json files or objects. These apps should should use msappx for us to know about -their extensions. +For apps that are installed through something like the Microsoft Store, they will need to declare themselves to +be an app extension or write a separate app extension. In the app extension, they will need to create a public +folder and insert their json files into it. The specifics of how they can do this are provided in the +[Microsoft Docs](https://docs.microsoft.com/en-us/windows/uwp/launch-resume/how-to-create-an-extension) for how +to create an app extension, and I will replicate the necessary section here. + +In the appxmanifest file of the package: + +``` + + ... + + + ... + + ... + + + + com.microsoft.powservice + + + + + + + ... + +``` + +Note that the name field **must** be `Microsoft.com.Terminal` for us to detect this extension. The `Id`, +`DisplayName` and `Description` fields can be filled out as the app wishes. The `PublicFolder` field +should have the name of the folder, relative to the package root, where the `json` files they wish to share +with us are stored (this folder is typically named `Public` but can be renamed as long as it matches the +relevant folder). + +During our profile generation, we will probe the OS for app extensions with the name `Microsoft.com.Terminal` +and obtain the json files stored in the public folders of those app extensions. #### For apps installed 'traditionally' and third parties/independent users @@ -229,7 +270,8 @@ C:\ProgramData\Microsoft\Windows Terminal\Fragments ``` Note: `C:\ProgramData` is a [known folder](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/bb776911(v=vs.85)) -that apps should be able to access. It will be on us to create the folder `Terminal` in `C:\ProgramData\Microsoft\Windows` for this to happen. +that apps should be able to access. It will be on us to create the folder `Windows Terminal` in `C:\ProgramData\Microsoft\Windows` +for this to happen. In the second case, the installation is only for the current user. For this case, the installer should add the json files to the local folder: @@ -238,7 +280,7 @@ json files to the local folder: C:\Users\\AppData\Local\Microsoft\Windows Terminal\Fragments ``` -This is also where independent users will add their own json files for Terminal to generate/modify profiles. +This is also where independent users should add their own json files for Terminal to generate/modify profiles. We will look through both folders mentioned above during profile generation. @@ -294,9 +336,8 @@ Looking through the additional json files could negatively impact startup time. ## Potential Issues -Cases which would likely be frustrating: - * An installer dumps a _lot_ of json files into the folder which we need to look through. +* When a `.json` files is deleted, any new profiles that were generated from it remain in the user's settings file (though they no longer appear in the tab dropdown). ## Future considerations From a34f7d02ecc7197f287e7fbfa8f1e040860d9d25 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 17 Sep 2020 21:25:56 -0400 Subject: [PATCH 17/28] no need for properties, change last updated date --- doc/specs/Proto extensions-spec.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 9a5f090d759..255ae690ada 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -1,7 +1,7 @@ --- author: <@PankajBhojwani> created on: <2020-9-9> -last updated: <2020-9-9> +last updated: <2020-9-17> --- # Proto extensions @@ -239,10 +239,7 @@ In the appxmanifest file of the package: DisplayName="" Description="" PublicFolder="Public"> - - com.microsoft.powservice - - + From 95f2dc70b6c4c6e770dbff458890e39f309dc9d6 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Fri, 18 Sep 2020 15:07:23 -0400 Subject: [PATCH 18/28] don't require displayname and description --- doc/specs/Proto extensions-spec.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 255ae690ada..e98592734ec 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -236,8 +236,6 @@ In the appxmanifest file of the package: @@ -248,11 +246,10 @@ In the appxmanifest file of the package: ``` -Note that the name field **must** be `Microsoft.com.Terminal` for us to detect this extension. The `Id`, -`DisplayName` and `Description` fields can be filled out as the app wishes. The `PublicFolder` field -should have the name of the folder, relative to the package root, where the `json` files they wish to share -with us are stored (this folder is typically named `Public` but can be renamed as long as it matches the -relevant folder). +Note that the name field **must** be `Microsoft.com.Terminal` for us to detect this extension. The `Id` field +can be filled out as the app wishes. The `PublicFolder` field should have the name of the folder, relative to +the package root, where the `json` files they wish to share with us are stored (this folder is typically named +`Public` but can be renamed as long as it matches the relevant folder). During our profile generation, we will probe the OS for app extensions with the name `Microsoft.com.Terminal` and obtain the json files stored in the public folders of those app extensions. From 202951f6a06ca9413a9e7c4c20f07374ec79180c Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Mon, 21 Sep 2020 17:55:30 -0400 Subject: [PATCH 19/28] updates from discussion --- doc/specs/Proto extensions-spec.md | 78 ++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 21 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index e98592734ec..7a5535cc36e 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -64,7 +64,9 @@ An example of a full json file with these fields filled out is shown at the end The main thing to note for modification of existing profiles is that this will only be used for modifying the default profiles (cmd/powershell) or the dynamically generated profiles. -For modifications to existing profiles, the json stub would need to indicate which profile it wishes to modify. +For modifications to existing profiles, the json stub would need to indicate which profile it wishes to modify. It will +do this by providing the corresponding guid in the `"updates"` field of the json stub. + Note that currently, we generate a GUID for dynamic profiles using the "initial" name of the profile (i.e. before any user changes are applied). For example, the "initial" name of a WSL profile is the \ argument to "wsl.exe -d \", and the "initial" name of a Powershell profile is something like "Powershell (ARM)" - depending @@ -84,7 +86,7 @@ Here is an example of a json file that modifies an existing profile (specificall { "profiles": [ { - "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", + "updates": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", "fontSize": 16, "fontWeight": "thin" } @@ -112,7 +114,6 @@ have some qualifying minimum criteria before we accept a stub as a full profile. new profile objects from stubs that contain at least the following * A name -* A commandline argument As in the case of the dynamic profile generator, if we create a profile that did not exist before (i.e. does not exist in the user settings), we need to add the profile to the user settings file and re-save that file. @@ -155,12 +156,11 @@ Again, the user will be able to make changes to it as they do for all other prof #### Creation of colour schemes As with full profiles, we will have some qualifying criteria for what we accept as full colour schemes: color schemes -must have -* A name -* A background -* A foreground +must have _all_ the fields that define a colour scheme - see the +[docs](https://docs.microsoft.com/en-us/windows/terminal/customize-settings/color-schemes) +on creating new colour schemes for what this means. -This will cause the issue of colour schemes being overridden if there are many creations of a colour scheme with the +This may cause the issue of colour schemes being overridden if there are many creations of a colour scheme with the same name. Since for now all we have to uniquely identify colour schemes *is* the name, we will just let this be. Here is an example of a json stub that contains a colour scheme: @@ -170,8 +170,29 @@ Here is an example of a json stub that contains a colour scheme: "schemes": [ { "name": "Postmodern Tango Light", + + "cursorColor": "#FFFFFF", + "selectionBackground": "#FFFFFF", + "background": '#61D6D6', - "foreground": '#E74856' + "foreground": '#E74856', + + "black" : "#0C0C0C", + "blue" : "#0037DA", + "cyan" : "#3A96DD", + "green" : "#13A10E", + "purple" : "#881798", + "red" : "#C50F1F", + "white" : "#CCCCCC", + "yellow" : "#C19C00", + "brightBlack" : "#767676", + "brightBlue" : "#3B78FF", + "brightCyan" : "#61D6D6", + "brightGreen" : "#16C60C", + "brightPurple" : "#B4009E", + "brightRed" : "#E74856", + "brightWhite" : "#F2F2F2", + "brightYellow" : "#F9F1A5" } ] } @@ -187,7 +208,7 @@ Shell profile, creates a new profile called 'Cool Profile' and creates a new col { "profiles": [ { - "guid": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", + "updates": "{b453ae62-4e3d-5e58-b989-0a998ec441b8}", "fontSize": 16, "fontWeight": "thin" }, @@ -202,9 +223,30 @@ Shell profile, creates a new profile called 'Cool Profile' and creates a new col ], "schemes": [ { - "name": "Postmodern Tango Light", - "background": "#61D6D6", - "foreground": "#E74856" + "name": "Postmodern Tango Light", + + "cursorColor": "#FFFFFF", + "selectionBackground": "#FFFFFF", + + "background": '#61D6D6', + "foreground": '#E74856', + + "black" : "#0C0C0C", + "blue" : "#0037DA", + "cyan" : "#3A96DD", + "green" : "#13A10E", + "purple" : "#881798", + "red" : "#C50F1F", + "white" : "#CCCCCC", + "yellow" : "#C19C00", + "brightBlack" : "#767676", + "brightBlue" : "#3B78FF", + "brightCyan" : "#61D6D6", + "brightGreen" : "#16C60C", + "brightPurple" : "#B4009E", + "brightRed" : "#E74856", + "brightWhite" : "#F2F2F2", + "brightYellow" : "#F9F1A5" } ] } @@ -254,7 +296,7 @@ the package root, where the `json` files they wish to share with us are stored ( During our profile generation, we will probe the OS for app extensions with the name `Microsoft.com.Terminal` and obtain the json files stored in the public folders of those app extensions. -#### For apps installed 'traditionally' and third parties/independent users +#### For apps installed 'traditionally' For apps that are installed 'traditionally', there are 2 cases. The first is that this installation is for all the users of the system - in this case, the installer should add their json files to the global folder: @@ -274,8 +316,6 @@ json files to the local folder: C:\Users\\AppData\Local\Microsoft\Windows Terminal\Fragments ``` -This is also where independent users should add their own json files for Terminal to generate/modify profiles. - We will look through both folders mentioned above during profile generation. #### The source field @@ -299,10 +339,6 @@ For full profiles that came from app extensions, we will give the value `app` to This feature will allow other installations a level of control over how their profiles look in Terminal. For example, if Ubuntu gets a new icon or a new font they can have those changes be reflected in Terminal users' Ubuntu profiles. -Furthermore, this allows users an easy way to share profiles they have created - instead of needing to modify their -settings file directly they could simply download a json file into the folder -`C:\Users\\AppData\Local\Microsoft\Windows\Terminal`. - ## Capabilities ### Accessibility @@ -335,7 +371,7 @@ Looking through the additional json files could negatively impact startup time. ## Future considerations -How will this affect the settings UI? +This will likely be a stepping stone for the theme marketplace. ## Resources From 4c28d9994c58433f6ea2249068b2ce0551ea8c39 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Fri, 2 Oct 2020 11:10:03 -0400 Subject: [PATCH 20/28] clarifications --- doc/specs/Proto extensions-spec.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 7a5535cc36e..0a6ddf1be9f 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -65,7 +65,9 @@ The main thing to note for modification of existing profiles is that this will o default profiles (cmd/powershell) or the dynamically generated profiles. For modifications to existing profiles, the json stub would need to indicate which profile it wishes to modify. It will -do this by providing the corresponding guid in the `"updates"` field of the json stub. +do this by providing the corresponding guid in the `"updates"` field of the json stub. The reason we use an `"updates"` +field rather than a `"guid"` field (like the way the user settings are eventually layered onto profiles) is because we +do not want to mistakenly create a new profile when the stub was meant to update a profile that did not exist. Note that currently, we generate a GUID for dynamic profiles using the "initial" name of the profile (i.e. before any user changes are applied). For example, the "initial" name of a WSL profile is the \ argument to @@ -119,8 +121,7 @@ As in the case of the dynamic profile generator, if we create a profile that did exist in the user settings), we need to add the profile to the user settings file and re-save that file. Furthermore, we will add a source field to profiles created this way (again, similar to what we do for dynamic profiles). -The source field value is dependent on how we obtained this json file, and will be touched on in more detail later in the -spec (see "Creation and location(s) of the json files" - "The source field"). +The source field value is dependent on how we obtained this json file, and will be touched on in more detail [later in the spec](#the-source-field). Here is an example of a json file that contains a full profile: @@ -254,6 +255,9 @@ Shell profile, creates a new profile called 'Cool Profile' and creates a new col ### Creation and location(s) of the json files +In this section, we cover where an app that wants to use this proto-extension functionality should put the json +files. Once we implement this feature, we will need to provide documentation on this for app developers. + #### For apps installed through Microsoft store (or similar) For apps that are installed through something like the Microsoft Store, they will need to declare themselves to From 4c81790ced8f420eff1306b3a4e65e6b904ca0cf Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Mon, 5 Oct 2020 14:11:45 -0400 Subject: [PATCH 21/28] fragments subdirectory for app extensions --- doc/specs/Proto extensions-spec.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 0a6ddf1be9f..113e0e838b5 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -262,9 +262,10 @@ files. Once we implement this feature, we will need to provide documentation on For apps that are installed through something like the Microsoft Store, they will need to declare themselves to be an app extension or write a separate app extension. In the app extension, they will need to create a public -folder and insert their json files into it. The specifics of how they can do this are provided in the -[Microsoft Docs](https://docs.microsoft.com/en-us/windows/uwp/launch-resume/how-to-create-an-extension) for how -to create an app extension, and I will replicate the necessary section here. +folder, and create a subdirectory within that folder called `Fragments`. The json files should be inserted into the +`Fragments` subdirectory. The specifics of how they can declare themselves as an app extension are provided in the +[Microsoft Docs](https://docs.microsoft.com/en-us/windows/uwp/launch-resume/how-to-create-an-extension), and I will +replicate the necessary section here. In the appxmanifest file of the package: @@ -298,7 +299,7 @@ the package root, where the `json` files they wish to share with us are stored ( `Public` but can be renamed as long as it matches the relevant folder). During our profile generation, we will probe the OS for app extensions with the name `Microsoft.com.Terminal` -and obtain the json files stored in the public folders of those app extensions. +and obtain the json files stored in the `Fragments` subdirectories of the public folders of those app extensions. #### For apps installed 'traditionally' From 5472357a0bdc4527c78a3d68e071daddca291664 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Mon, 5 Oct 2020 14:46:50 -0400 Subject: [PATCH 22/28] one more future consideration --- doc/specs/Proto extensions-spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 113e0e838b5..c0c5e8dceb9 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -376,7 +376,9 @@ Looking through the additional json files could negatively impact startup time. ## Future considerations -This will likely be a stepping stone for the theme marketplace. +This will likely be a stepping stone for the theme marketplace. + +This will also likely be a stepping stone to allowing users to specify other files to import settings from. ## Resources From 1a4f73969dc8272be25777644b16a6c8b289f952 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Wed, 7 Oct 2020 15:56:18 -0400 Subject: [PATCH 23/28] change extension host name --- doc/specs/Proto extensions-spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index c0c5e8dceb9..e83d3423dc1 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -281,7 +281,7 @@ In the appxmanifest file of the package: ... - @@ -293,12 +293,12 @@ In the appxmanifest file of the package: ``` -Note that the name field **must** be `Microsoft.com.Terminal` for us to detect this extension. The `Id` field +Note that the name field **must** be `com.Microsoft.Terminal` for us to detect this extension. The `Id` field can be filled out as the app wishes. The `PublicFolder` field should have the name of the folder, relative to the package root, where the `json` files they wish to share with us are stored (this folder is typically named `Public` but can be renamed as long as it matches the relevant folder). -During our profile generation, we will probe the OS for app extensions with the name `Microsoft.com.Terminal` +During our profile generation, we will probe the OS for app extensions with the name `com.Microsoft.Terminal` and obtain the json files stored in the `Fragments` subdirectories of the public folders of those app extensions. #### For apps installed 'traditionally' From 01c32634feb10a59056e3b6e4d4a1814a8cc75ed Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Fri, 9 Oct 2020 15:57:45 -0400 Subject: [PATCH 24/28] edits based on discussion --- doc/specs/Proto extensions-spec.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index e83d3423dc1..1f16abd400e 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -78,9 +78,9 @@ GUID. Then, in the stub they provide the GUID can be used to identify which prof Naturally, we will have to provide documentation on how they could generate the desired GUID themselves. In that documentation, we will also provide examples showing how the current GUIDs are generated for clarity's sake. -We might run into the case where multiple json stubs modify the same profile and so they override each other. For the initial implementation, we -are simply going to apply _all_ the changes. Eventually, we will probably want some sort of hierarchy to determine -an order to which changes are applied. +We need to inform developers that **we will not** prescribe any ordering to the way in which these modifications will be +applied - thus, they should not rely on their stub being the first/last to modify a particular profile (in the event that +there is more than one json stub modifying the same profile). Here is an example of a json file that modifies an existing profile (specifically the Azure cloud shell profile): @@ -307,18 +307,19 @@ For apps that are installed 'traditionally', there are 2 cases. The first is tha the users of the system - in this case, the installer should add their json files to the global folder: ``` -C:\ProgramData\Microsoft\Windows Terminal\Fragments +C:\ProgramData\Microsoft\Windows Terminal\Fragments\{app-name} ``` Note: `C:\ProgramData` is a [known folder](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/bb776911(v=vs.85)) -that apps should be able to access. It will be on us to create the folder `Windows Terminal` in `C:\ProgramData\Microsoft\Windows` -for this to happen. +that apps should be able to access. If the folder `Windows Terminal` in `C:\ProgramData\Microsoft\Windows` +does not already exist, the installer should create it. **Note:** the installer must create a subdirectory within +the `Fragments` folder with their app name, we will use that name for the [`source` field](#the-source-field). In the second case, the installation is only for the current user. For this case, the installer should add the json files to the local folder: ``` -C:\Users\\AppData\Local\Microsoft\Windows Terminal\Fragments +C:\Users\\AppData\Local\Microsoft\Windows Terminal\Fragments\{app-name} ``` We will look through both folders mentioned above during profile generation. @@ -329,13 +330,10 @@ Currently, we allow users an easy way to disable/enable profiles that are genera example, a user can easily hide all dynamic profiles with the source `"Windows.Terminal.Wsl"` if they wish to. To retain this functionality, we will add source fields to profiles we create through proto-extensions. -For full profiles that came from the *global* folder `C:\ProgramData\Microsoft\Windows\Terminal`, -we will give the value `global` to the source field. +For full profiles that came from apps installed 'traditionally', we will use the name of the subdirectory where +the json file was found to fill out the source field. -For full profiles that came from the *local* folder `C:\Users\\AppData\Local\Microsoft\Windows\Terminal`, -we will give the value `local` to the source field. - -For full profiles that came from app extensions, we will give the value `app` to the source field. +For full profiles that came from app extensions, we will use the app package name to fill out the source field. @@ -376,6 +374,8 @@ Looking through the additional json files could negatively impact startup time. ## Future considerations +We need to consider how an app extension provides the path to an image (for the icon source or background image of a profile for example) + This will likely be a stepping stone for the theme marketplace. This will also likely be a stepping stone to allowing users to specify other files to import settings from. From 985a63d309c8964e6c1de366d84ce7b50fefb075 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 15 Oct 2020 14:45:32 -0400 Subject: [PATCH 25/28] naming fix --- doc/specs/Proto extensions-spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 1f16abd400e..7562bac0a35 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -281,7 +281,7 @@ In the appxmanifest file of the package: ... - @@ -293,12 +293,12 @@ In the appxmanifest file of the package: ``` -Note that the name field **must** be `com.Microsoft.Terminal` for us to detect this extension. The `Id` field +Note that the name field **must** be `com.microsoft.windows.terminal.settingsext` for us to detect this extension. The `Id` field can be filled out as the app wishes. The `PublicFolder` field should have the name of the folder, relative to the package root, where the `json` files they wish to share with us are stored (this folder is typically named `Public` but can be renamed as long as it matches the relevant folder). -During our profile generation, we will probe the OS for app extensions with the name `com.Microsoft.Terminal` +During our profile generation, we will probe the OS for app extensions with the name `com.microsoft.windows.terminal.settingsext` and obtain the json files stored in the `Fragments` subdirectories of the public folders of those app extensions. #### For apps installed 'traditionally' From 13955390e7001a6a16900ac5e4d5e86d05c4e107 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 15 Oct 2020 15:01:38 -0400 Subject: [PATCH 26/28] dictionary, merge master --- .github/actions/spell-check/dictionary/dictionary.txt | 1 + doc/specs/Proto extensions-spec.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/actions/spell-check/dictionary/dictionary.txt b/.github/actions/spell-check/dictionary/dictionary.txt index 1faf357c362..816d356f3bd 100644 --- a/.github/actions/spell-check/dictionary/dictionary.txt +++ b/.github/actions/spell-check/dictionary/dictionary.txt @@ -369892,6 +369892,7 @@ setting setting-free setting-out settings +settingsext setting-to setting-up Settle diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 7562bac0a35..6b803c76012 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -1,7 +1,7 @@ --- author: <@PankajBhojwani> created on: <2020-9-9> -last updated: <2020-9-17> +last updated: <2020-10-15> --- # Proto extensions From 566087338eb6f3b9cf06f4cec3bd25f473a13b96 Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 15 Oct 2020 15:03:57 -0400 Subject: [PATCH 27/28] another naming fix --- .github/actions/spell-check/dictionary/dictionary.txt | 1 - doc/specs/Proto extensions-spec.md | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/actions/spell-check/dictionary/dictionary.txt b/.github/actions/spell-check/dictionary/dictionary.txt index 816d356f3bd..1faf357c362 100644 --- a/.github/actions/spell-check/dictionary/dictionary.txt +++ b/.github/actions/spell-check/dictionary/dictionary.txt @@ -369892,7 +369892,6 @@ setting setting-free setting-out settings -settingsext setting-to setting-up Settle diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index 6b803c76012..c18a044df5b 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -281,7 +281,7 @@ In the appxmanifest file of the package: ... - @@ -293,12 +293,12 @@ In the appxmanifest file of the package: ``` -Note that the name field **must** be `com.microsoft.windows.terminal.settingsext` for us to detect this extension. The `Id` field +Note that the name field **must** be `com.microsoft.windows.terminal.settings` for us to detect this extension. The `Id` field can be filled out as the app wishes. The `PublicFolder` field should have the name of the folder, relative to the package root, where the `json` files they wish to share with us are stored (this folder is typically named `Public` but can be renamed as long as it matches the relevant folder). -During our profile generation, we will probe the OS for app extensions with the name `com.microsoft.windows.terminal.settingsext` +During our profile generation, we will probe the OS for app extensions with the name `com.microsoft.windows.terminal.settings` and obtain the json files stored in the `Fragments` subdirectories of the public folders of those app extensions. #### For apps installed 'traditionally' From 64666b22fba7584158cd1029d47083d5b59a212b Mon Sep 17 00:00:00 2001 From: Pankaj Bhojwani Date: Thu, 15 Oct 2020 15:46:15 -0400 Subject: [PATCH 28/28] linter. --- doc/specs/Proto extensions-spec.md | 52 +++++++++++++++--------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/doc/specs/Proto extensions-spec.md b/doc/specs/Proto extensions-spec.md index c18a044df5b..039da21d532 100644 --- a/doc/specs/Proto extensions-spec.md +++ b/doc/specs/Proto extensions-spec.md @@ -9,7 +9,7 @@ last updated: <2020-10-15> ## Abstract This spec outlines adding support for proto extensions. This would allow other apps/programs -to add json snippets to our json files, and will be used when we generate settings for our various profiles. +to add json snippets to our json files, and will be used when we generate settings for our various profiles. ## Inspiration @@ -19,7 +19,7 @@ Currently, Ubuntu/WSL/Powershell etc are unable to provide any specifications fo their profiles in Terminal to look - only we and the users can modify the profiles. We want to provide these installations with the functionality to have a say in this, allowing them to specify things like their icon, their font and so on. However, we want to maintain that the user has final say over all of -these settings. +these settings. ## Solution Design @@ -57,17 +57,17 @@ these stubs should be put into lists in the json file: one list named ```profile } ``` -An example of a full json file with these fields filled out is shown at the end of this section. +An example of a full json file with these fields filled out is shown at the end of this section. #### Modifications to existing profiles The main thing to note for modification of existing profiles is that this will only be used for modifying the -default profiles (cmd/powershell) or the dynamically generated profiles. +default profiles (cmd/powershell) or the dynamically generated profiles. For modifications to existing profiles, the json stub would need to indicate which profile it wishes to modify. It will do this by providing the corresponding guid in the `"updates"` field of the json stub. The reason we use an `"updates"` field rather than a `"guid"` field (like the way the user settings are eventually layered onto profiles) is because we -do not want to mistakenly create a new profile when the stub was meant to update a profile that did not exist. +do not want to mistakenly create a new profile when the stub was meant to update a profile that did not exist. Note that currently, we generate a GUID for dynamic profiles using the "initial" name of the profile (i.e. before any user changes are applied). For example, the "initial" name of a WSL profile is the \ argument to @@ -76,7 +76,7 @@ on the version. Thus, the stub creator could simply use the same uuidv5 GUID gen GUID. Then, in the stub they provide the GUID can be used to identify which profile to modify. Naturally, we will have to provide documentation on how they could generate the desired GUID themselves. In that documentation, -we will also provide examples showing how the current GUIDs are generated for clarity's sake. +we will also provide examples showing how the current GUIDs are generated for clarity's sake. We need to inform developers that **we will not** prescribe any ordering to the way in which these modifications will be applied - thus, they should not rely on their stub being the first/last to modify a particular profile (in the event that @@ -97,7 +97,7 @@ Here is an example of a json file that modifies an existing profile (specificall ``` **NOTE**: This will *not* change the way the profile looks in the user's settings file. The Azure cloud shell profile -in their settings file (assuming they have made no changes) will still be as below. +in their settings file (assuming they have made no changes) will still be as below. ```js { @@ -107,7 +107,7 @@ in their settings file (assuming they have made no changes) will still be as bel "source": "Windows.Terminal.Azure" } ``` -However, the user is free to make changes to it as usual and those changes will have the 'final say'. +However, the user is free to make changes to it as usual and those changes will have the 'final say'. #### Full profile stubs @@ -121,7 +121,7 @@ As in the case of the dynamic profile generator, if we create a profile that did exist in the user settings), we need to add the profile to the user settings file and re-save that file. Furthermore, we will add a source field to profiles created this way (again, similar to what we do for dynamic profiles). -The source field value is dependent on how we obtained this json file, and will be touched on in more detail [later in the spec](#the-source-field). +The source field value is dependent on how we obtained this json file, and will be touched on in more detail [later in the spec](#the-source-field). Here is an example of a json file that contains a full profile: @@ -152,14 +152,14 @@ json stub in the user's settings file will be: "source": "local" } ``` -Again, the user will be able to make changes to it as they do for all other profiles. +Again, the user will be able to make changes to it as they do for all other profiles. #### Creation of colour schemes As with full profiles, we will have some qualifying criteria for what we accept as full colour schemes: color schemes must have _all_ the fields that define a colour scheme - see the [docs](https://docs.microsoft.com/en-us/windows/terminal/customize-settings/color-schemes) -on creating new colour schemes for what this means. +on creating new colour schemes for what this means. This may cause the issue of colour schemes being overridden if there are many creations of a colour scheme with the same name. Since for now all we have to uniquely identify colour schemes *is* the name, we will just let this be. @@ -256,7 +256,7 @@ Shell profile, creates a new profile called 'Cool Profile' and creates a new col ### Creation and location(s) of the json files In this section, we cover where an app that wants to use this proto-extension functionality should put the json -files. Once we implement this feature, we will need to provide documentation on this for app developers. +files. Once we implement this feature, we will need to provide documentation on this for app developers. #### For apps installed through Microsoft store (or similar) @@ -265,11 +265,11 @@ be an app extension or write a separate app extension. In the app extension, the folder, and create a subdirectory within that folder called `Fragments`. The json files should be inserted into the `Fragments` subdirectory. The specifics of how they can declare themselves as an app extension are provided in the [Microsoft Docs](https://docs.microsoft.com/en-us/windows/uwp/launch-resume/how-to-create-an-extension), and I will -replicate the necessary section here. +replicate the necessary section here. In the appxmanifest file of the package: -``` +```js \AppData\Local\Microsoft\Windows Terminal\Fragments\{app-name} ``` -We will look through both folders mentioned above during profile generation. +We will look through both folders mentioned above during profile generation. #### The source field Currently, we allow users an easy way to disable/enable profiles that are generated from certain sources. For example, a user can easily hide all dynamic profiles with the source `"Windows.Terminal.Wsl"` if they wish to. -To retain this functionality, we will add source fields to profiles we create through proto-extensions. +To retain this functionality, we will add source fields to profiles we create through proto-extensions. For full profiles that came from apps installed 'traditionally', we will use the name of the subdirectory where -the json file was found to fill out the source field. +the json file was found to fill out the source field. -For full profiles that came from app extensions, we will use the app package name to fill out the source field. +For full profiles that came from app extensions, we will use the app package name to fill out the source field. @@ -356,16 +356,16 @@ things they do not want to. ### Reliability -This should not affect reliability - most of what its doing is simply layering json which we already do. +This should not affect reliability - most of what its doing is simply layering json which we already do. ### Compatibility Again, there should not be any issues here - the user settings can still be layered after this layering for the user -to have the final say. +to have the final say. ### Performance, Power, and Efficiency -Looking through the additional json files could negatively impact startup time. +Looking through the additional json files could negatively impact startup time. ## Potential Issues @@ -378,7 +378,7 @@ We need to consider how an app extension provides the path to an image (for the This will likely be a stepping stone for the theme marketplace. -This will also likely be a stepping stone to allowing users to specify other files to import settings from. +This will also likely be a stepping stone to allowing users to specify other files to import settings from. ## Resources