Proposal "Allow to change permissions behavior on extension updates"

proposals/suppress_permissions_warning_on_update.md → proposals/permissions_behavior_on_update.md

@@ -1,14 +1,16 @@
-# Proposal: Suppress permissions warning on update
+# Proposal: Allow to change permissions behavior on extension's update
 
 ** Proposal Summary**
 
-Add a new boolean property to the manifest that changes the default behavior of added "permissions" during the extension's update. Instead of showing a "warning," permissions shouldn't be granted; they should behave like they are optional until an extension is requested. It doesn't change behavior during install time or for permission that doesn't trigger a warning.
+Add a new property, "permissions_behavior_on_update," to the manifest to alter the newly added "permissions" behavior during the extension's update. When set to "defer," newly added permissions on update won't be granted by default; they will behave like optional permissions and must be explicitly requested by the extension. Also, the default browser behavior will NOT be applied (warning, turn off, stop further updates, etc.).
+
+The new behavior isn't applicable during install time or for permission that doesn't trigger a warning.
 
 Extension manifest file example:
 
 ```json
 {
-  "suppress_permissions_warning_on_update": true
+  "permissions_behavior_on_update": "defer"
 }
 ```
 
@@ -29,6 +31,10 @@ Extension manifest file example:
 
 ## Motivation
 
+### Glossary
+
+The phrase "permissions that trigger warnings" refers to permissions that require additional action from the user after the extension's update. The actual UX varies across browsers; some may silently turn off the extension, while others display an extra warning or pause further extension updates until the user explicitly permits the added permission.
+
 ### Objective
 
 Today, developers have two options for adding [new permissions that trigger warnings](https://developer.chrome.com/docs/extensions/develop/concepts/permission-warnings):
@@ -41,29 +47,29 @@ On the manifest-files level, it's a "permissions" property that represents a lis
 
 On the manifest-files level, it's an "optional_permissions" property that represents a list of permissions that the extension may request at any point, and the user agrees or declines them.
 
-**The proposal is to introduce a way to suppress permission's warning during the extension's update and, instead of turning off the extension or stopping further updates for existing users, make it behave optional where the extension has to request permission explicitly.**
+**The proposal is to introduce a way to avoid permission's warning during the extension's update and, instead of turning off the extension or stopping further updates for existing users, make it behave optional where the extension has to request permission explicitly.**
 
 **For New Installations**: The existing behavior remains, and all permissions listed in the "permissions" key will be granted. 
 
 **For Current users**: The new permissions that trigger the warning won't be granted, and the permissions warning won't be shown. Instead, the extension has to explicitly request permission within the user gesture.
 
-Important note: such behavior only applies to permissions that trigger warnings during extension updates. In the case of a new installation, all "permissions" are granted as part of existing installation flows, and no additional requests should be made.
+Important note: such behavior only applies to permissions that trigger "warnings" during extension updates. In the case of a new installation, all "permissions" are granted as part of existing installation flows, and no additional requests should be made.
 
 a) Why fallback to "optional" behavior during the update?
 
 It's hard to imagine a case when the developer wants their extension to be silently turned off. Instead, falling back to behavior similar to "optional" permission gives way to introduce permission to new installs and way to onboard existing users as well. 
 
 b) Why not a new field proposed in ["Hybrid permissions" proposal](https://github.com/w3c/webextensions/pull/788)
 
-The intent is to avoid easting permissions keys as this may lead to ambiguity and make everyone simply avoid "permissions."
+The intent is to avoid adding new kinds of permissions as this may lead to ambiguity and make everyone simply avoid existing "permissions" key.
 
 #### User Benefits
 
-By adding "suppress_permissions_warning_on_update", we can offer the best user experience by being open and upfront about the permissions our application will require to function optimally as well as reducing user confusion with a single prompt as opposed to multiple.
+By adding "permissions_behavior_on_update", extension developers can offer the best user experience by being open and upfront about the permissions extension will require to function optimally as well as reducing user confusion with a single prompt as opposed to multiple.
 
 Also, by suppressing warnings we will reduce the fear of accidentally "turn off" extensions for the existing user and enable extension developers to actively evolve extensions by adopting new permissions as soon as they make sense.
 
-Here is an official showcase from the "Chrome for Developers” documentation that illustrates the user experience when permissions trigger a warning. Such behavior that we would like to avoid with the support for hybrid permissions
+Here is an official showcase from the "Chrome for Developers” documentation that illustrates the user experience when permissions trigger a warning. Such behavior that we would like to avoid with the proposed changes in this proposal.
 
 ![image](https://developer.chrome.com/static/docs/extensions/develop/concepts/permission-warnings/image/example-an-extension-is-6772580db51de.gif)
 
@@ -79,19 +85,19 @@ If the extension is already live, there is no good way to add a new mandatory pe
 
 ### Known Consumers
 
-Support for "Suppressing permissions warning on update" will enable well-established extensions (including Grammarly) to introduce new features to users that require additional permissions without the risk of accidentally disabling the extension, but at the same time, it will help avoid confusing new users with a suboptimal permission request flow immediately after installation.
+Changes listed in this proposal will enable well-established extensions to introduce new features to users that require additional permissions without the risk of accidentally disabling the extension, but at the same time, it will help avoid confusing new users with a suboptimal permission request flow immediately after installation.
 
 ## Specification
 
 ### Schema
 
-The permissions' granting behavior only changes when "suppress_permissions_warning_on_update" is set to "true" and only from new permissions that may trigger a warning during the update. It doesn't change the behavior of permissions that don't trigger a warning or all permissions during install time.
+The permissions' granting behavior only changes when "permissions_behavior_on_update" is set to "defer" and only for new permissions that may trigger a warning during the update. It doesn't change the behavior of permissions that don't trigger a warning or all permissions during install time.
 
-When the "suppress_permissions_warning_on_update" is absent from the manifest or explicitly set to "false," the behavior remains the same as it is right now, and new permissions with a warning will turn off the extension during the update or stop updates until the user explicitly approves it (behavior varies across browsers).
+When the "permissions_behavior_on_update" is absent from the manifest, the behavior remains the same as it is right now, and new permissions with a warning will turn off the extension during the update or stop updates until the user explicitly approves it (behavior varies across browsers).
 
 ### Suppress permissions warning on update
 
-In case "suppress_permissions_warning_on_update" is set to true, then any new permission that triggers a warning isn't granted but instead should be explicitly requested within a user gesture using "permissions.request"(https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/request). Expect that user may decline permission.
+In case "permissions_behavior_on_update" is set to "defer", then any new permission that triggers a "warning" isn't granted but instead should be explicitly requested within a user gesture using "permissions.request"(https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/request). Expect that user may decline permission.
 
 ```
 document.querySelector('#my-button').addEventListener('click', (event) => {
@@ -126,13 +132,13 @@ Overall the regular [permissions' API](https://developer.mozilla.org/en-US/docs/
 
 [Existing web “permissions” behavior](https://developer.chrome.com/docs/extensions/reference/api/permissions#step_3_request_optional_permissions) is not changes. 
 
-### What if new version changes "suppress_permissions_warning_on_update" from "true" to "false"
+### What if new version changes removes "permissions_behavior_on_update" after it was set to "defer"
 
-In this case, the new behavior will be only applicable for any new permissions that will be added in this or further versions. Any "suppressed" permissions with a warning will remain suppressed.
+In this case, the new behavior will be only applicable for any new permissions that will be added in this or further versions. Any "deferred" permissions with a warning will remain deferred.
 
 Example:
 
-1. Assuming that user is already on 0.0.1 and extension was just updated to 0.0.2 that adds a new "<permission_that_triggers_a_warning>" with "suppress_permissions_warning_on_update" is set to `true`. In this case, the extension will be successfully updated; however, "permission_that_triggers_a_warning" won't be granted, and the user hasn't interacted with the extension, so permission was never requested.
+1. Assuming that user is already on 0.0.1 and extension was just updated to 0.0.2 that adds a new "<permission_that_triggers_a_warning>" with `permissions_behavior_on_update` is set to `defer`. In this case, the extension will be successfully updated; however, "permission_that_triggers_a_warning" won't be granted. Also, assuming that the user hasn't interacted with the extension, so permission was never requested.
 
 ```js
 {
@@ -141,11 +147,11 @@ Example:
   permissions: [
     "<permission_that_triggers_a_warning>"
   ],
-  suppress_permissions_warning_on_update:true
+  permissions_behavior_on_update: "defer"
 }
 ```
 
-2. The new version 0.0.3 removes "suppress_permissions_warning_on_update", but adds a new "permission_without_warning". In this case, the extension will be successfully updated, and permission_without_warning will be granted, however, "permission_that_triggers_a_warning" remains suppressed and needs an explicit request to be used. 
+2. The new version 0.0.3 removes `permissions_behavior_on_update`, but adds a new "permission_without_warning". In this case, the extension will be successfully updated, and "permission_without_warning" will be granted, however, "permission_that_triggers_a_warning" remains suppressed and needs an explicit request to be used.
 
 ```js
 {
@@ -158,27 +164,29 @@ Example:
 }
 ```
 
-### What if extension was already turned off due to the permission "warning", but updates to a new version with "suppress_permissions_warning_on_update" set to "true"
+### What if extension was already turned off due to the permission "warning", but updates to a new version with "permissions_behavior_on_update" set to "defer"
 
 <TODO>
 
 ### Behavior
 
-When "suppress_permissions_warning_on_update" is set to true, then for existing installs (extension update flow), nothing should be requested. However, the extension should be able check and request new permission on runtime. Otherwise, permissions granting behavior remains the same.
+When "permissions_behavior_on_update" is set to "defer", then for existing installs (extension update flow), nothing should be requested. However, the extension should be able check and request new permission on runtime. Otherwise, permissions granting behavior remains the same.
 
 ### New Permissions
 
 The proposal does not introduce any new permissions. However, it does introduce a new behavior for requesting existing permissions. 
 
 ### Manifest File Changes
 
-Add a new boolean property to the manifest that changes the default behavior of added "permissions" during the extension's update. Instead of showing a "warning," permissions shouldn't be granted; they should behave like they are optional until an extension is requested.
+Add a new property, "permissions_behavior_on_update," to the manifest to alter the newly added "permissions" behavior during the extension's update. When set to "defer," newly added permissions on update won't be granted by default; they will behave like optional permissions and must be explicitly requested by the extension. Also, the default browser behavior will NOT be applied (warning, turn off, stop further updates, etc.).
+
+The new behavior isn't applicable during install time or for permission that doesn't trigger a warning.
 
 Extension manifest file example:
 
 ```json
 {
-  "suppress_permissions_warning_on_update": true
+  "permissions_behavior_on_update": "defer"
 }
 ```
 
@@ -190,7 +198,7 @@ This proposal doesn't change the existing browser API or expose PII data.
 
 ### Abuse Mitigations
 
-The proposal doesn't introduce any additional possibilities for abuse. For already installed extensions, "hybrid" permissions behave like optional ones that should be explicitly requested. Permissions are shown as "permanent" for new installations and are explicitly reviewed by the user upon installation.
+The proposal doesn't introduce any additional possibilities for abuse. For already installed extensions, newly added permissions behave like optional ones that should be explicitly requested.
 
 ### Additional Security Considerations