Switch to yaml for policy templates
Bug: 1294298
Change-Id: I9e05b43964aa78c96c883e4388689c5d87f895c3
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3909773
Commit-Queue: Steven Holte <[email protected]>
Reviewed-by: Owen Min <[email protected]>
Commit-Queue: Yann Dago <[email protected]>
Auto-Submit: Yann Dago <[email protected]>
Reviewed-by: Steven Holte <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1061228}
diff --git a/docs/enterprise/add_new_policy.md b/docs/enterprise/add_new_policy.md
index 7d44973..cda22a04 100644
--- a/docs/enterprise/add_new_policy.md
+++ b/docs/enterprise/add_new_policy.md
@@ -32,8 +32,18 @@
future extensions or use cases.
- Negative policies (*Disable*, *Disallow*) are verboten because setting
something to "true" to disable it confuses people.
-2. Declare the policy in the
- [policy_templates.json](https://cs.chromium.org/chromium/src/components/policy/resources/policy_templates.json)
+2. Declare the policy in the [policies.yaml] file.
+ - This file contains the policy names and their ids.
+3. If you need to add a new policy group, create a directory with the name of
+ that group under [policy group].
+ - Inside the newly created directory, create a `.group.details.yaml` file
+ with the caption and description of the group. This group is used for
+ documentation and policy template generation, so it is recommended to
+ group policies in meaningful groups.
+ - Use [.group.details.yaml](https:/cs.chromium.org/chromium/components/policy/resources/new_policy_templates/.group.details.yaml)
+ as a templates for group definition.
+4. Create a file named `PolicyName.yaml` under the appropriate [policy group].
+ You may use [policy.yaml] to start off your policy.
- This file contains meta-level descriptions of all policies and is used
to generate code, policy templates (ADM/ADMX for Windows and the
application manifest for Mac), as well as documentation. Please make
@@ -59,8 +69,7 @@
policy as recommended and allow the user to override it in the UI,
using a command line switch or an extension.
- The complete list of attributes and their expected values can be found in
- the
- [policy_templates.json](https://cs.chromium.org/chromium/src/components/policy/resources/policy_templates.json).
+ the [policy.yaml] file.
- The textual policy description should include the following:
- What features of Chrome are affected.
- Which behavior and/or UI/UX changes the policy triggers.
@@ -73,13 +82,26 @@
- See [description_guidelines.md](description_guidelines.md)
for additional guidelines when creating a description, including how
various products should be referenced.
-3. Create a preference and map the policy value to it.
+4. Create a policy atomic group.
+ - If you are adding multiple policies that are closely related and interact
+ with each other, you should put them in policy atomic group. An atomic
+ policy group is used in the Chromium code and affects how policies are
+ applied. When enabled by the admin, this ensures that policies from an
+ atomic group get their values from the same source and are not a mix of
+ policies from multiple sources. This [feature](https://chromeenterprise.google/intl/en_ca/policies/atomic-groups/)
+ is controlled by the policy [PolicyAtomicGroupsEnabled](https://chromeenterprise.google/intl/en_ca/policies/#PolicyAtomicGroupsEnabled).
+
+ - Declare the atomic group in the [policies.yaml] file.
+ - Create a `policy_atomic_groups.yaml` file in the group where you added the
+ policies if it does not already exist.
+ You may use [policy.yaml] as reference.
+5. Create a preference and map the policy value to it.
- All policy values need to be mapped into a prefs value before being used
unless the policy is needed before PrefService initialization.
- To map the policy:
1. Create a prefs and register the prefs in **Local State** or
**Profile Prefs**. Please note that, this must match the
- `per_profile` attribute in the `policy_templates.json`. We also
+ `per_profile` attribute in the `YourPolicyName.yaml`. We also
strongly encourage developers to register the prefs with **Profile
Prefs** if possible, because this gives admin more flexibility of
policy setup.
@@ -94,7 +116,7 @@
and
[policy_test_cases.json](https://source.chromium.org/chromium/chromium/src/+/main:ios/chrome/test/data/policy/policy_test_cases.json)
file.
-4. Disable the user setting UI when the policy is applied.
+6. Disable the user setting UI when the policy is applied.
- If your feature can be controlled by GUI in `chrome://settings`, the
associated option should be disabled when the policy controlling it is
managed.
@@ -103,7 +125,7 @@
- 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.
-5. Support `dynamic_refresh` if possible.
+7. 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
will honor the change at run-time without requiring a restart of the
@@ -114,7 +136,7 @@
[PrefChangeRegistrar](https://cs.chromium.org/chromium/src/components/prefs/pref_change_registrar.h)
to listen to the preference change notification and update UI or
browser behavior right away.
-6. Adding a device policy for ChromeOS.
+8. Adding a device policy for ChromeOS.
- Most policies that are used by the browser can be shared between desktop
and ChromeOS. However, you need a few additional steps for a device
policy on ChromeOS.
@@ -124,14 +146,14 @@
- Update
`chrome/browser/ash/policy/core/device_policy_decoder.{h,cc}`
for the new policy.
-7. Test the policy.
+9. Test the policy.
- Add a test to verify the policy. You can add a test in
`chrome/browser/policy/<area>_policy_browsertest.cc` or with the policy
implementation. For example, a network policy test can be put into
`chrome/browser/net`. Ideally, your test would set the policy, fire up
the browser, and interact with the browser just as a user would do to
check whether the policy takes effect.
-8. Manually testing your policy.
+10. Manually testing your policy.
- Windows: The simplest way to test is to write the registry keys manually
to `Software\Policies\Chromium` (for Chromium builds) or
`Software\Policies\Google\Chrome` (for Google Chrome branded builds). If
@@ -152,11 +174,11 @@
If you'd just like to do a quick test for ChromeOS, the Linux code is
also functional on CrOS, see
[Linux Quick Start](https://www.chromium.org/administrators/linux-quick-start).
-9. If you are adding a new policy that supersedes an older one, verify that the
+11. If you are adding a new policy that supersedes an older one, verify that the
new policy works as expected even if the old policy is set (allowing us to
set both during the transition time when Chrome versions honoring the old
and the new policies coexist).
-10. If your policy has interactions with other policies, make sure to document,
+12. If your policy has interactions with other policies, make sure to document,
test and cover these by automated tests.
## Launch a policy
@@ -196,7 +218,7 @@
supported_on field. See "Removing support for a policy" below for more details.
### Steps
-1. Update policy_templates.json, marking the policy as deprecated and updating
+1. Update `YourPolicyName.yaml`, marking the policy as deprecated and updating
the description to describe when and why the policy as deprecated and what
admins should be doing instead.
1. Update the policy handling code. This is generally ensuring that if the old
@@ -216,12 +238,11 @@
such as an escape hatch policy.
1. The feature this policy impacts was removed from Chrome.
-If the policy was never launched, it can also be deleted from
-policy_templates.json instead of just being marked as no longer supported.
-In this case, please remember to add the deleted id to deleted_policy_ids.
+If the policy was never launched, `YourPolicyName.yaml` can be deleted and you may
+replace the policy name in `policies.yaml` by an empty string.
If you want to remove support for another reason, please reach out to someone in
-[ENTERPRISE_POLICY_OWNERS](https://cs.chromium.org/chromium/src/components/policyENTERPRISE_POLICY_OWNERS)
+[ENTERPRISE_POLICY_OWNERS](https://cs.chromium.org/chromium/src/components/policy/ENTERPRISE_POLICY_OWNERS)
to ensure this is okay. The general preference is to leave policies as
deprecated, but still supported.
@@ -230,7 +251,7 @@
if the policy skipped past the deprecation state.
### Steps
-1. Update policy_templates.json, marking the policy as no longer supported.
+1. Update `YourPolicyName.yaml`, marking the policy as no longer supported.
Also marking as deprecated if not previously done.
1. Update the related test in the `policy_test_cases.json`.
- If the policy is going to be removed in the current milestone, remove the
@@ -288,7 +309,7 @@
To enforce the above rules concerning policy modification and ensure no
backwards incompatible changes are introduced, presubmit checks
will be performed on every change to
-[policy_templates.json](https://cs.chromium.org/chromium/src/components/policy/resources/policy_templates.json).
+[templates](https:/cs.chromium.org/chromium/components/policy/resources/templates/policy_definitions/).
The presubmit checks perform the following verifications:
@@ -391,7 +412,9 @@
### Additional Notes
-1. policy_templates.json is actually a Python dictionary even though the file
- name contains *json*.
-2. The `future_on` flag can disable policy on Beta of Stable channel only if the
+1. The `future_on` flag can disable policy on Beta of Stable channel only if the
policy value is copied to `PrefService` in Step 3 of **Adding a new policy**.
+
+[policies.yaml]: https:/cs.chromium.org/chromium/components/policy/resources/templates/policies.yaml
+[policy.yaml]: https:/cs.chromium.org/chromium/components/policy/resources/new_policy_templates/policy.yaml
+[policy group]: https:/cs.chromium.org/chromium/components/policy/resources/templates/policy_definitions/
