From 8eaaaa12205d00e400c13bf71b71899516d9ac97 Mon Sep 17 00:00:00 2001
From: Adam Bookatz <bookatz@google.com>
Date: Fri, 17 Jan 2025 10:36:35 -0800
Subject: Discourage MainUser

Puts a comment, warning people to avoid using the main user concept.
Features should preferably work for all users, or all admin users, or
some other intelligently selected user(s). The idea of having one fixed
special user is against the long-term goals of multiuser.

Bug: 390264303
Test: N/A - just documentation
Flag: EXEMPT documentation only
Change-Id: Iaf56cb7f4c9c1551578e257e950f021b7f6c7163
---
 core/java/android/content/pm/UserInfo.java                 |  6 ++++++
 core/java/android/os/UserManager.java                      | 14 ++++++++++++++
 .../java/com/android/server/pm/UserManagerInternal.java    |  6 ++++++
 3 files changed, 26 insertions(+)

diff --git a/core/java/android/content/pm/UserInfo.java b/core/java/android/content/pm/UserInfo.java
index 8a3a3ad56a7b..582a1a9442ce 100644
--- a/core/java/android/content/pm/UserInfo.java
+++ b/core/java/android/content/pm/UserInfo.java
@@ -183,6 +183,12 @@ public class UserInfo implements Parcelable {
      *
      * <p>This is not necessarily the system user. For example, it will not be the system user on
      * devices for which {@link UserManager#isHeadlessSystemUserMode()} returns true.
+     *
+     * <p>NB: Features should ideally not limit functionality to the main user. Ideally, they
+     * should either work for all users or for all admin users. If a feature should only work for
+     * select users, its determination of which user should be done intelligently or be
+     * customizable. Not all devices support a main user, and the idea of singling out one user as
+     * special is contrary to overall multiuser goals.
      */
     public static final int FLAG_MAIN = 0x00004000;
 
diff --git a/core/java/android/os/UserManager.java b/core/java/android/os/UserManager.java
index 5a53bc1552b8..cdaa36e08d66 100644
--- a/core/java/android/os/UserManager.java
+++ b/core/java/android/os/UserManager.java
@@ -2907,10 +2907,18 @@ public class UserManager {
      * <p>Currently, on most form factors the first human user on the device will be the main user;
      * in the future, the concept may be transferable, so a different user (or even no user at all)
      * may be designated the main user instead. On other form factors there might not be a main
+     * user. In the future, the concept may be removed, i.e. typical future devices may have no main
      * user.
      *
      * <p>Note that this will not be the system user on devices for which
      * {@link #isHeadlessSystemUserMode()} returns true.
+     *
+     * <p>NB: Features should ideally not limit functionality to the main user. Ideally, they
+     * should either work for all users or for all admin users. If a feature should only work for
+     * select users, its determination of which user should be done intelligently or be
+     * customizable. Not all devices support a main user, and the idea of singling out one user as
+     * special is contrary to overall multiuser goals.
+     *
      * @hide
      */
     @SystemApi
@@ -2927,6 +2935,12 @@ public class UserManager {
     /**
      * Returns the designated "main user" of the device, or {@code null} if there is no main user.
      *
+     * <p>NB: Features should ideally not limit functionality to the main user. Ideally, they
+     * should either work for all users or for all admin users. If a feature should only work for
+     * select users, its determination of which user should be done intelligently or be
+     * customizable. Not all devices support a main user, and the idea of singling out one user as
+     * special is contrary to overall multiuser goals.
+     *
      * @see #isMainUser()
      * @hide
      */
diff --git a/services/core/java/com/android/server/pm/UserManagerInternal.java b/services/core/java/com/android/server/pm/UserManagerInternal.java
index 14b0fc81fdd2..c62aaebf673b 100644
--- a/services/core/java/com/android/server/pm/UserManagerInternal.java
+++ b/services/core/java/com/android/server/pm/UserManagerInternal.java
@@ -584,6 +584,12 @@ public abstract class UserManagerInternal {
      * Returns the user id of the main user, or {@link android.os.UserHandle#USER_NULL} if there is
      * no main user.
      *
+     * <p>NB: Features should ideally not limit functionality to the main user. Ideally, they
+     * should either work for all users or for all admin users. If a feature should only work for
+     * select users, its determination of which user should be done intelligently or be
+     * customizable. Not all devices support a main user, and the idea of singling out one user as
+     * special is contrary to overall multiuser goals.
+     *
      * @see UserManager#isMainUser()
      */
     public abstract @UserIdInt int getMainUserId();
-- 
cgit v1.2.3-59-g8ed1b