groups: Pass old setting value for can_mention_group.

This commit adds support to pass object containing both old and new
values of the can_mention_group setting, as well as detailed API
documentation for this part of the API system.

Co-authored-by: Tim Abbott <tabbott@zulip.com>
Co-authored-by: Greg PRice <greg@zulip.com>

api_docs/changelog.md

@@ -20,6 +20,12 @@ format used by the Zulip server that they are interacting with.
 
 ## Changes in Zulip 9.0
 
+**Feature level 260**:
+
+* [`PATCH /user_groups/{user_group_id}`](/api/update-user-group):
+  Updating `can_mention_group` now uses a race-resistant format where
+  the client sends the expected `old` value and desired `new` value.
+
 **Feature level 259**:
 
 * [`POST /register`](/api/register-queue), [`GET /events`](/api/get-events):

api_docs/group-setting-values.md

@@ -0,0 +1,83 @@
+# Group-setting values
+
+Settings defining permissions in Zulip are increasingly represented
+using [user groups](/help/user-groups), which offer much more flexible
+configuration than the older [roles](/api/roles-and-permissions) system.
+
+In the API, these settings are represented using a **group-setting
+value**, which can take two forms:
+
+- An integer user group ID, which can be either a named user group
+  visible in the UI or a [role-based system group](#system-groups).
+- An object with fields `direct_member_ids` containing a list of
+  integer user IDs and `direct_subgroup_ids` containing a list of
+  integer group IDs. The setting's value is the union of the
+  identified collection of users and groups.
+
+Group-setting values in the object form function very much like a
+formal user group object, without requiring the naming and UI clutter
+overhead involved with creating a visible user group just to store the
+value of a single setting.
+
+The server will canonicalize an object with empty `direct_member_ids`
+and with `direct_subgroup_ids` containing just the given group ID to
+the integer format.
+
+## System groups
+
+The Zulip server maintains a collection of system groups that
+correspond to the users with a given role; this makes it convenient to
+store concepts like "all administrators" in a group-setting
+value. These use a special naming convention and can be recognized by
+the `is_system_group` property on their group object.
+
+The following system groups are maintained by the Zulip server:
+
+- `role:internet`: Everyone on the Internet has this permission; this
+  is used to configure the [public access
+  option](/help/public-access-option).
+- `role:everyone`: All users, including guests.
+- `role:members`: All users, excluding guests.
+- `role:fullmembers`: All [full
+  members](https://zulip.com/api/roles-and-permissions#determining-if-a-user-is-a-full-member)
+  of the organization.
+- `role:moderators`: All users with at least the moderator role.
+- `role:administrators`: All users with at least the administrator
+  role.
+- `role:owners`: All users with the owner role.
+- `role:nobody`: The formal empty group. Used in the API to represent
+  disabling a feature.
+
+Client UI for setting a permission is encouraged to display system
+groups using their description, rather than using their names, which
+are chosen to be unique and clear in the API.
+
+System groups should generally not be displayed in UI for
+administering an organization's user groups, since they are not
+directly mutable.
+
+## Updating group-setting values
+
+The Zulip API uses a special format for modifying an existing setting
+using a group-setting value.
+
+A **group-setting update** is an object with a `new` field and an
+optional `old` field, each containing a group-setting value. The
+setting's value will be set to the membership expressed by the `new`
+field.
+
+The `old` field expresses the client's understanding of the current
+value of the setting. If the `old` field is present and does not match
+the actual current value of the setting, then the request will fail
+with error code `EXPECTATION_MISMATCH` and no changes will be applied.
+
+When a user edits the setting in a UI, the resulting API request
+should generally always include the `old` field, giving the value
+the list had when the user started editing. This accurately expresses
+the user's intent, and if two users edit the same list around the
+same time, it prevents a situation where the second change
+accidentally reverts the first one without either user noticing.
+
+Omitting `old` is appropriate where the intent really is a new complete
+list rather than an edit, for example in an integration that syncs the
+list from an external source of truth.

api_docs/roles-and-permissions.md

@@ -102,6 +102,11 @@ and owners.
 Note that specific settings and policies in the Zulip API that use these
 permission levels will likely support a subset of those listed above.
 
+## Group-based permissions
+
+Some settings have been migrated to a more flexible system based on
+[user groups](/api/group-setting-values).
+
 ## Determining if a user is a full member
 
 When a Zulip organization has set up a [waiting period before new members

api_docs/sidebar_index.md

@@ -21,6 +21,7 @@
 * [HTTP headers](/api/http-headers)
 * [Error handling](/api/rest-error-handling)
 * [Roles and permissions](/api/roles-and-permissions)
+* [Group-setting values](/api/group-setting-values)
 * [Message formatting](/api/message-formatting)
 * [Client libraries](/api/client-libraries)
 * [API changelog](/api/changelog)