CDD: Require the restrictive behavior of hidden APIs to be consistent.
- Ensure that the defined limitations for private API list is kept
to keep the same expectations across devices.
- Clarifying what can be allowed for adding / removing APIs in API
list.
bug: 74128885
Test: m
Change-Id: I9a20ad2db814969e19dfc1f8cf8de1b930a310e5
diff --git a/3_software/3_1_managed-api-compatibility.md b/3_software/3_1_managed-api-compatibility.md
index e4d5fd4..92eb603 100644
--- a/3_software/3_1_managed-api-compatibility.md
+++ b/3_software/3_1_managed-api-compatibility.md
@@ -7,28 +7,41 @@
Device implementations:
-* [C-0-1] MUST provide complete implementations,
-including all documented behaviors, of any documented API exposed by the
-[Android SDK](http://developer.android.com/reference/packages.html)
-or any API decorated with the “@SystemApi” marker in the upstream Android
-source code.
+* [C-0-1] MUST provide complete implementations, including all documented
+ behaviors, of any documented API exposed by the [Android SDK](
+ http://developer.android.com/reference/packages.html)
+ or any API decorated with the “@SystemApi” marker in the upstream Android
+ source code.
-* [C-0-2] MUST support/preserve all classes,
-methods, and associated elements marked by the TestApi annotation (@TestApi).
+* [C-0-2] MUST support/preserve all classes, methods, and associated elements
+ marked by the TestApi annotation (@TestApi).
-* [C-0-3] MUST NOT omit any managed APIs, alter
-API interfaces or signatures, deviate from the documented behavior, or include
-no-ops, except where specifically allowed by this Compatibility Definition.
+* [C-0-3] MUST NOT omit any managed APIs, alter API interfaces or signatures,
+ deviate from the documented behavior, or include no-ops, except where
+ specifically allowed by this Compatibility Definition.
* [C-0-4] MUST still keep the APIs present and behave
in a reasonable way, even when some hardware features for which Android
includes APIs are omitted. See [section 7](#7_hardware_compatibility)
for specific requirements for this scenario.
-* [C-0-5] MUST display a warning to the user that an app was built for an
- older version of Android when the app targeting API level 16 or lower is
- first launched.
+* [C-0-5] MUST restrict the use of 3rd-party app usage of hidden APIs,
+ defined as APIs in the android namespace decorated with the `@hidden`
+ annotation but not with a `@SystemAPI` or `@TestApi`, as described in the
+ [SDK documents](https://developer.android.com/preview/restrictions-non-sdk-interfaces)
+ and ship with each and every hidden API on the the same restricted lists as
+ provided via the light-greylist, dark-greylist, and blacklist files in the
+ `prebuilts/runtime/appcompat/` path for the appropriate API level branch
+ in the AOSP. However they:
+ * MAY, if a hidden API is absent or implemented differently on the device
+ implementation, move the hidden API into the blacklist or omit it from
+ all restricted lists (i.e. light-grey, dark-grey, black).
+ * MAY, if a hidden API does not already exist in the AOSP, add the hidden
+ API to any of the restricted lists (i.e. light-grey, dark-grey, black).
+ * MAY implement a dynamic update mechanism that moves a hidden API from a
+ restricted list into a less restrictive list, except for the whitelist.
+
## 3.1.1\. Android Extensions
Android includes the support of extending the managed APIs while keeping the
