Add policy design documentation

The doc describes how to design a policy. It covers many common
questions that people have when design policies.

* Make add_new_policy and policy_design link with each other.

Bug: None
Change-Id: I8afde5c976fd061cd71717b94b7530c3760e39d6
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/4762804
Commit-Queue: Owen Min <zmin@chromium.org>
Reviewed-by: Julian Pastarmov <pastarmovj@chromium.org>
Reviewed-by: Jana Grill <janagrill@google.com>
Cr-Commit-Position: refs/heads/main@{#1185188}

docs/enterprise/add_new_policy.md

@@ -19,8 +19,11 @@ Usually you need a policy when
 -   Deprecating an old feature. Create a policy to give enterprise users more
     time to migrate away from the feature.
 
-**To read more about best practices for shipping enterprise friendly features
-read [this article](https://www.chromium.org/developers/enterprise-changes/).**
+**To read more about best practices for shipping enterprise friendly features,
+please read [this article](https://www.chromium.org/developers/enterprise-changes/).**
+
+**This article covers lots of technical details. More information about policy
+design can be found at [policy_design.md](./policy_design.md).**
 
 ## Adding a new policy
 
@@ -125,6 +128,7 @@ read [this article](https://www.chromium.org/developers/enterprise-changes/).**
         -   The setting needs an
             [indicator](https://cs.chromium.org/chromium/src/ui/webui/resources/images/business.svg)
             to tell users that the setting is enforced by the administrator.
+        -   There are more information and util functions can be found [here](https://source.chromium.org/chromium/chromium/src/+/main:ui/webui/resources/cr_elements/policy/).
 8.  Support `dynamic_refresh` if possible.
     -   We strongly encourage developers to make their policies support this
         attribute. It means the admin can change the policy value and Chrome

docs/enterprise/policy_design.md

@@ -0,0 +1,341 @@
+# How to design an enterprise policy
+
+## Summary
+
+Chrome exposes a different set of configurations to administrators. These
+configurations are called policies and they give administrators more advanced
+controls than the standard users. With different device management tools, an
+administrator can deliver these policies to many users. Here is the [help center article](https://support.google.com/chrome/a/?p=policy_order)
+that talks about Chrome policy and its deployment.
+
+
+## Do I need a policy
+
+Not every single Chrome update needs to be guarded with a policy. In some cases,
+enterprise users can accept new features just like consumer users. However,
+consider adding new policy if
+
+* Your feature will break an existing CUJ (Critical User Journey).
+* Your feature will introduce changes in some critical areas like security,
+  networking.
+* Your feature can be configured by end users.
+* Your feature has compliance requirements, e.g. upload data to Google owned
+  servers.
+* You are removing an existing feature from Chrome.
+
+**To read more about best practices for shipping enterprise friendly features
+read [this article](https://www.chromium.org/developers/enterprise-changes/).**
+
+**To learn more about policy implementation details, please read [add_new_policy.md](./add_new_policy.md)**.
+
+And if you are not sure, don’t hesitate to contact the [Chrome enterprise team](mailto:chromium-enterprise@chromium.org)).
+
+
+## Design a new policy
+
+### Before Starting
+
+Similar to the switches on the chrome://settings page, enterprise policies are
+designed to provide options to our users to customize Chrome’s behaviors.
+
+In some cases, a simple kill switch is a good starting point. It allows admins
+to force a feature they really need or block one that they can’t have due to
+privacy or security concerns. However, a boolean won’t always provide enough
+flexibility and may turn enterprise users away. In other words, providing
+granular control would be a better approach here. It allows enterprise users
+access to a feature while administrators can still meet all compatibility
+requirements. Sometimes, a policy can even be used to provide an enhanced
+version of the feature to enterprise users.
+
+For example, [ExtensionSettings](https://chromeenterprise.google/policies/#ExtensionSettings)
+allows admins to block extensions based on their permissions or update URLs
+while still giving users the ability to install extensions that they like and
+admins are comfortable with.
+
+Another example is [BrowserSignin](https://chromeenterprise.google/policies/#BrowserSignin)
+policy which provides an additional force-sign-in feature which is not available
+for consumer users.
+
+Think about CUJ(Critical User Journey), collect information to understand how
+administrators and enterprise users will use this feature. They can help you to
+design a policy.
+
+
+### Define a policy
+
+Each Chrome policy must be defined in the [Chromium code base](https://cs.chromium.org/chromium/src/components/policy/resources/templates/policy_definitions/)
+which contains all metadata of a policy.
+
+
+#### Name
+
+Policy name is a short phrase that briefly describes what the policy does.
+
+
+* Do **NOT** use negative words like _Disabled_ or _Disallowed_. It will lead to
+  double negatives and confuse people. Instead, prefer a policy name like
+  FooEnabled (which can be set to false in cases where a feature should be
+  disabled).
+* Avoid long policy names. Policy names don't have to cover everything. There is
+  a documentation section for all the details.
+* Avoid internal codewords. Policy names are public information. Make sure
+  keywords can be searched and understood by external people.
+
+Searching for a similar pattern from existing [policies list](https://chromeenterprise.google/policies/)
+is always a good strategy to find a good name. However, be careful about some
+ancient policies that were added a long time ago. We may already abandon those
+naming patterns, but keep the policies only because of backward compatibility.
+For example, [SyncDisabled](https://chromeenterprise.google/policies/#SyncDisabled)
+was added in Chrome 8, but we keep its name even though _Disabled_ is banned.
+
+
+#### Type
+
+There are 6 major types of policies, listed below.
+
+
+##### Boolean
+
+This is the simplest policy type that defines 3 states: enabled, disabled and
+not set. Not-set should have the same behavior as consumer users.
+
+Example: [CloudReportingEnabled](https://chromeenterprise.google/policies/#CloudReportingEnabled)
+
+
+##### Enum
+
+A policy type provides more than 3 states for the admin to choose from.
+
+Example: [BrowserSignin](https://chromeenterprise.google/policies/#BrowserSignin)
+
+If multiple options can be chosen at the same time, use string-enum-list type.
+
+Example: [ExtensionAllowedTypes](https://chromeenterprise.google/policies/#ExtensionAllowedTypes)
+
+
+##### Integer
+
+A policy that accepts any integer as input. It can be used to define a period of
+time or size of a folder. The integer can't be negative and must be less than
+2^32.
+
+In most cases, there are two things to consider.
+
+* Choose a proper interval.
+* Choose a proper unit.
+
+Unit:
+
+The enterprise team used to use the minimum unit for policy to give enterprise
+more flexibility. However, that may require admin to put an unnecessary large
+number for certain policies which is error-prone.
+
+Now we ask people to choose more proper units. For example, instead of
+milliseconds, hours may be a better choice, if most people won’t care about the
+differences between 1 hour and 59 minutes.
+
+Example: [CloudReportingUploadFrequency](https://chromeenterprise.google/policies/#CloudReportingUploadFrequency)
+and [DiskCacheSize](https://chromeenterprise.google/policies/#DiskCacheSize)
+
+
+##### String
+
+A policy that accepts any string as input.
+
+Starting from this type, admin can put anything as policy input and error
+handling become more important.
+
+* If a policy input is partially invalid, can we still process the good part?
+* Presenting good error messages to help admins fix the issues.
+
+Note that setting an empty string *must* be treated as not setting the policy
+due to the limitation of policy delivery mechanisms on some platforms.
+
+Example [HomepageLocation](https://chromeenterprise.google/policies/#HomepageLocation)
+
+
+##### List
+
+A policy that accepts a list of strings as input.
+
+Similar to string policy
+
+* Empty list *must* be treated as not set.
+* User input validation needs to be handled properly.
+
+In addition to that, depending on the policy implementation, setting a
+limitation is necessary when having too many list entries could cause
+performance issues. As an example, [URLBlocklist](https://chromeenterprise.google/policies/#URLBlocklist)
+policy only accepts 1000 URLs because we need to scan the list for every navigation request.
+
+However, sometimes admins may want to set values more than what we can afford.
+In those cases, we will need to redesign the input format. For example,
+supporting wildcard characters is a common solution.
+
+Example: [URLBlocklist](https://chromeenterprise.google/policies/#URLBlocklist),
+[ExtensionInstallAllowlist](https://chromeenterprise.google/policies/#ExtensionInstallAllowlist)
+
+
+###### URL list
+
+URL list is a common format of list policy. It allows admins to apply policy
+only to certain websites or URLs.
+
+Other than normal list policy, a few more considerations:
+
+* In many cases, URL matching is not necessary. Domain or hostname matching may
+  be good enough and much easier to maintain.
+* Choose URL matching algorithm:
+  * Exact match
+  * [Content settings](https://chromeenterprise.google/policies/url-patterns/)
+    for content settings
+  * [URLBlocklist](https://support.google.com/chrome/a?p=url_blocklist_filter_format)
+    style with basic wildcard support.
+  * Define your own. Avoid this option if possible. If you have to, make sure
+    all edge cases are addressed.
+
+
+
+###### Allowlist vs Blocklist
+
+Another common format of list policies. It allows the admin to set exceptions
+for certain situations. Usually, we can create them as:
+
+* A standalone allowlist/blocklist policy.
+* An on/off boolean policy as default option with another allowlist/blocklist
+  policy as exception.
+* Allowlist and blocklist policies pair.
+
+If more than one policy is defined for the same feature, please find a proper
+solution to resolve the conflict cases.
+
+
+##### Dictionary
+
+A policy that accepts a complex structure as input. Depending on the
+platforms, it could be a JSON string or XML files.
+
+This is the most powerful and complicated policy format. A complicated
+dictionary policy may be hard for admins to understand and maintain. In many
+cases, splitting a dictionary configuration into multiple simple policies is a
+better approach.
+
+Same as String and List policy, an empty dictionary *must* be treated as
+not setting the policy.
+
+Also, a complicated dictionary policy may also contain conflict configurations.
+Make sure those cases are handled properly.
+
+Example: [ExtensionSettings](https://chromeenterprise.google/policies/#ExtensionSettings)
+
+
+#### Default Value
+
+The default value defines Chrome’s behavior when policy is not set.
+
+
+#### Supported Platforms
+
+Always support as many platforms as possible. And unless there are good reasons,
+please launch a policy on all platforms at the same time.
+
+
+#### Feature
+
+
+* **_Dynamic refresh_** - When set to true, modifying the policy does not
+  require relaunching the browser. Support this feature whenever possible.
+* **_Per profile_** - When set to true, policy value can be applied to only one
+  particular profile. Support this feature whenever possible.
+* **_Hidden policies_** - In some cases, you would like to hide the policies
+  from most admins. There is no perfect solution as admins can always check the
+  source code of Chromium. But we still can hide a policy as much as we can.
+  Talk with the Enterprise team for more details.
+* **_Recommended vs mandatory_** - Recommended policies mean the admin only sets
+  the initial value of the policy, but allows users to modify them later. Most
+  policies are mandatory only, but having a recommended support is encouraged.
+  However, make sure the user can actually modify that settings. (e.g. Having a
+  UI or an extension API)
+* **_Device policy_** - A special policy that controls ChromeOS hardware or sign
+  in page. If a policy needs to control both browser and ChromeOS device,
+  split it into two policies. For example, [MetricsReportingEnabled](https://chromeenterprise.google/policies/#MetricsReportingEnabled)
+  vs [DeviceMetricsReportingEnabled](https://chromeenterprise.google/policies/#DeviceMetricsReportingEnabled).
+  Device policies’ name always begin with the “Device” prefix.
+
+
+### More Policy Details
+
+#### Chrome UI
+
+If a setting is controlled by policy and UI at the same time, please make sure
+the UI is disabled when the policy is set with a proper message or UI element
+which tells end users that the option is controlled by their administrator.
+
+Alert: There might be multiple UI entries, make sure all of them are covered.
+
+
+#### Admin Console UI
+
+Most of the time, there is no need to worry about the admin console UI. However,
+cover this section if your policy is complicated. Talk with
+[the server team](https://docs.google.com/document/d/1QgDTWISgOE8DVwQSSz8x5oKrI3O_qAvOmPryE5DQPcw/edit#heading=h.py10m8dh4kvv)
+for more details. (Internal link, Googlers only)
+
+
+#### A group of policies
+
+If multiple policies are added at the same time or there are existing policies
+for the same feature, make sure all those policies won’t break each other.
+
+* One policy may provide conflicting settings with another one.
+* One policy may have different behavior depending on another one.
+
+Also, if multiple policies are created for the same topic, creating a new
+[policy group](https://source.chromium.org/chromium/chromium/src/+/main:components/policy/resources/new_policy_templates/.group.details.yaml)
+can help admins find all related policies.
+
+
+#### Migrating existing policies
+
+In some cases, we would like to replace one policy with a more powerful one. The
+old policy will be deprecated in this case. However, for the sake of backward
+compatibility, we still need to support the old one.
+
+On the other hand, it’s always nice to think about future expansion when
+designing a policy. For example, if there is a chance we want to add more
+options to a policy, then enum type will be better than boolean.
+
+
+#### Privacy & Security
+
+Policy is a very powerful configuration tool that may bring additional security
+and privacy concerns. Talk with the Chrome privacy and Chrome security ahead of
+time if there is any concern.
+
+
+##### Security
+
+Will bad actors be interested in your policy? The Enterprise team can provide
+additional management checks for the policy by marking it sensitive. But it may
+block admins from small companies which didn’t pay for expensive management
+systems. In other cases, limiting the ability of policy may also help.
+
+
+##### Privacy
+
+We would like to protect end users’ privacy as much as we can while fulfilling
+admins’ requests. Another area that may need careful balance.
+
+
+### Launch Policy
+
+One major difference between policy launching and other features is that rollout
+control via experimental is not always an option. Majority of admins want their
+policies settings to apply to all devices they control.
+
+Usually, policy must be ready and launched before the feature it controls rolls
+out.
+
+In other cases, we can use trusted testers to test the policies for a small
+number of enterprise customers first. Talk with the Enterprise team for more
+details.