api docs: Clarify text about deactivated users and groups.

This should make it easier for client developers to understand
how to correctly implement the updated protocol.

api_docs/changelog.md

@@ -22,24 +22,32 @@ format used by the Zulip server that they are interacting with.
 
 **Feature level 303**
 
-* [`GET /events`](/api/get-events): User reactivation event is not sent
-  to users who cannot access the reactivated user anymore.
-* [`GET /events`](/api/get-events): `add_members` and `remove_members`
-  events with `user_group` type can now also be sent when reactivating
-  and deactivating a user respectively.
 * [`POST /register`](/api/register-queue), [`GET /user_groups`](/api/get-user-groups),
   [`GET /user_groups/{user_group_id}/members/{user_id}`](/api/get-is-user-group-member),
   [`GET /user_groups/{user_group_id}/members`](/api/get-user-group-members):
-  Deactivated users are not considered as members of a user group anymore.
+  Deactivated users are no longer returned as members of the user groups
-* [`GET /events`](/api/get-events): `realm/update_dict` and `user_group/update`
+  that they were members of prior to deactivation.
-  events are now also sent when deactivating or reactivating a user, for
-  settings which are set to anonymous groups having the user being deactivated
-  or reactivated as direct member.
 * [`POST /register`](/api/register-queue): Settings, represented as
-  [group-setting value](/api/group-setting-values), do not include deactivated
+  [group-setting value](/api/group-setting-values), will never include
-  users in the `direct_members` list for settings set to anonymous groups.
+  deactivated users in the `direct_members` list for settings whose
+  value is an anonymous group.
 * [`PATCH /user_groups/{user_group_id}/members`](/api/update-user-group-members):
-  Deactivated users cannot be added or removed from a user group.
+  Deactivated users cannot be added or removed from a user group; they
+  are now implicitly not members of any groups while deactivated.
+* [`GET /events`](/api/get-events): User reactivation event is not sent
+  to users who cannot access the reactivated user anymore due to a
+  `can_access_all_users_group` policy.
+* [`GET /events`](/api/get-events): The server will now send
+  `user_group` events with the `add_members`/`remove_members`
+  operations as appropriate when deactivating or reactivating a user,
+  to ensure client state correctly reflects groups never containing
+  deactivated users.
+* [`GET /events`](/api/get-events): To ensure that [group-setting
+  values](/api/group-setting-values) are correct, `realm/update_dict`
+  and `user_group/update` events may now be by sent by the server when
+  processing a deactivation/reactivation of a user, to ensure client
+  state correctly reflects the state, given that deactivated users
+  cannot have permissions in an organization.
 
 **Feature level 302**
 

zerver/openapi/zulip.yaml

@@ -610,13 +610,22 @@ paths:
                                     - type: object
                                       additionalProperties: false
                                       description: |
-                                        When a user is deactivated or reactivated. Only users
+                                        When a user is deactivated or reactivated. Only
-                                        who can access the deactivated or reactivated user
+                                        users who can access the modified user under the
-                                        receive this event.
+                                        organization's `can_access_all_users_group` policy
+                                        will receive this event.
 
-                                        **Changes**: Prior to Zulip 10.0 (feature level 303),
+                                        Clients receiving a deactivation event should
-                                        event for reactivation was also sent to users who
+                                        remove the user from all user groups in their data
-                                        cannot access the reactivated user.
+                                        structures, because deactivated users cannot be
+                                        members of groups.
+
+                                        **Changes**: Prior to Zulip 10.0 (feature level
+                                        303), reactivation events were sent to users who
+                                        could not access the reactivated user due to a
+                                        `can_access_all_users_group` policy. Also,
+                                        previously, Clients were not required to update
+                                        group membership records during user deactivation.
 
                                         New in Zulip 8.0 (feature level 222). Previously the server
                                         sent a `realm_user` event with `op` field set to `remove`
@@ -20287,10 +20296,11 @@ paths:
       summary: Update user group members
       tags: ["users"]
       description: |
-        Update the members of a [user group](/help/user-groups).
+        Update the members of a [user group](/help/user-groups). The
+        user IDs must correspond to non-deactivated users.
 
-        **Changes**: Prior to Zulip 10.0 (feature level 303), deactivated
+        **Changes**: Prior to Zulip 10.0 (feature level 303), group memberships of
-        users could also be added or removed from a user group.
+        deactivated users were visible to the API and could be edited via this endpoint.
       x-curl-examples-parameters:
         oneOf:
           - type: exclude
@@ -20626,7 +20636,8 @@ paths:
                             members:
                               type: array
                               description: |
-                                The integer user IDs of the user group members.
+                                The integer user IDs of the user group's members, which
+                                are guaranteed to be non-deactivated users in the organization.
 
                                 **Changes**: Prior to Zulip 10.0 (feature level 303), this
                                 list also included deactivated users who were members of
@@ -20854,8 +20865,8 @@ paths:
         Check whether a user is member of user group.
 
         **Changes**: Prior to Zulip 10.0 (feature level 303),
-        this returned true when the user was deactivated but
+        this would return true when passed a deactivated user
-        was member of the user group before being deactivated.
+        who was a member of the user group before being deactivated.
 
         New in Zulip 6.0 (feature level 127).
       parameters:
@@ -22072,8 +22083,8 @@ components:
               description: |
                 The list of IDs of individual users in the collection of users with this permission.
 
-                **Changes**: Prior to Zulip 10.0 (feature level 303), this list also included
+                **Changes**: Prior to Zulip 10.0 (feature level 303), this list would include
-                deactivated users.
+                deactivated users who had the permission before being deactivated.
               type: array
               items:
                 type: integer