From ab0fc402e0b54f0e43f5744ae322a252ae41f239 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Wed, 15 May 2024 15:26:51 +0200 Subject: [PATCH] api-docs: Update feature level 261 documentation. The original changes for this feature level are in commits a6be1d101 and 7b42c802b. --- api_docs/changelog.md | 21 +++++------ version.py | 2 +- zerver/openapi/zulip.yaml | 76 ++++++++++++++++++++++++--------------- 3 files changed, 59 insertions(+), 40 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 5b334a141b..b6271fc314 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -22,16 +22,17 @@ format used by the Zulip server that they are interacting with. **Feature level 261** -* [`POST /invites`](/api/send-invites), [`POST - /invites/multiuse`](/api/create-invite-link): Newly created user is - now subscribed to the default streams in the organization even when - the user sending the invite is not allowed to subscribe others. -* [`POST /invites`](/api/send-invites), [`POST - /invites/multiuse`](/api/create-invite-link): Added - `include_realm_default_subscriptions` parameter to indicate whether to - subscribe the invited user to default streams when creating the new - user account instead of passing the stream IDs of default streams - in `stream_ids` parameter. +* [`POST /invites`](/api/send-invites), + [`POST /invites/multiuse`](/api/create-invite-link): Added + `include_realm_default_subscriptions` parameter to indicate whether + the newly created user will be automatically subscribed to [default + channels](/help/set-default-channels-for-new-users) in the + organization. Previously, the default channel IDs needed to be included + in the `stream_ids` parameter. This also allows a newly created user + to be automatically subscribed to the default channels in an + organization when the user creating the invitation does not generally + have permission to [subscribe other users to + channels](/help/configure-who-can-invite-to-channels). **Feature level 260**: diff --git a/version.py b/version.py index d7bd767809..a7ad81d647 100644 --- a/version.py +++ b/version.py @@ -33,7 +33,7 @@ DESKTOP_WARNING_VERSION = "5.9.3" # Changes should be accompanied by documentation explaining what the # new level means in api_docs/changelog.md, as well as "**Changes**" # entries in the endpoint's documentation in `zulip.yaml`. -API_FEATURE_LEVEL = 260 +API_FEATURE_LEVEL = 261 # Bump the minor PROVISION_VERSION to indicate that folks should provision # only when going from an old version of the code to a newer version. Bump diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 8621c56830..2eced101f1 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -12160,34 +12160,43 @@ paths: $ref: "#/components/schemas/InviteRoleParameter" stream_ids: description: | - A list containing the [IDs of the streams](/api/get-stream-id) that - the newly created user will be automatically subscribed to if the - invitation is accepted, in addition to default streams configured via - the `include_realm_default_subscriptions` setting. + A list containing the [IDs of the channels](/api/get-stream-id) that the + newly created user will be automatically subscribed to if the invitation + is accepted, in addition to any default channels that the new user may + be subscribed to based on the `include_realm_default_subscriptions` + parameter. - This parameter must be the empty list if the current user has the - unlikely configuration of being able to generate invitations while - lacking permission to subscribe other users to streams. - - **Changes**: Prior to Zulip 9.0 (feature level 261), if the user was not - allowed to subscribe others to stream, the newly created user was not - subscribed to any streams. + This list must be empty if the current user has the unlikely + configuration of being able to send invitations while lacking + permission to [subscribe other users to channels][can-subscribe-others]. **Changes**: Before Zulip 7.0 (feature level 180), specifying `stream_ids` as an empty list resulted in an error. + + [can-subscribe-others]: /help/configure-who-can-invite-to-channels type: array items: type: integer example: [1, 10] include_realm_default_subscriptions: description: | - Boolean indicating that the newly created user should be subscribed - to the [default streams][default-streams] for the organization. + Boolean indicating whether the newly created user should be subscribed + to the [default channels][default-channels] for the organization. - **Changes**: New in Zulip 9.0 (feature level 261). + Note that this parameter can be `true` even if the user creating the + invitation does not generally have permission to [subscribe other + users to channels][can-subscribe-others]. - [default-streams]: /help/set-default-streams-for-new-users + **Changes**: New in Zulip 9.0 (feature level 261). Previous versions + of Zulip behaved as though this parameter was always `false`; clients + needed to include the organization's default streams in the + `stream_ids` parameter for a newly created user to be automatically + subscribed to them. + + [default-channels]: /help/set-default-channels-for-new-users + [can-subscribe-others]: /help/configure-who-can-invite-to-channels type: boolean + default: false example: false required: - invitee_emails @@ -12318,19 +12327,18 @@ paths: $ref: "#/components/schemas/InviteRoleParameter" stream_ids: description: | - A list containing the [IDs of the streams](/api/get-stream-id) that the + A list containing the [IDs of the channels](/api/get-stream-id) that the newly created user will be automatically subscribed to if the invitation - is accepted. If unspecified, it will be set to empty list. If the list is - empty, then the new user will not be subscribed to any streams. + is accepted, in addition to any default channels that the new user may + be subscribed to based on the `include_realm_default_subscriptions` + parameter. - If the user is not allowed to subscribe others, then this list should - be empty but the newly created user will still be subscribed to default - streams in the organization depending on the `include_realm_default_subscriptions` - value. + This list must be empty if the current user has the unlikely + configuration of being able to create reusable invitation links while + lacking permission to [subscribe other users to + channels][can-subscribe-others]. - **Changes**: Prior to Zulip 9.0 (feature level 261), if the user was not - allowed to subscribe others to stream, the newly created user was not - subscribed to any streams. + [can-subscribe-others]: /help/configure-who-can-invite-to-channels type: array items: type: integer @@ -12338,13 +12346,23 @@ paths: example: [1, 10] include_realm_default_subscriptions: description: | - Boolean indicating that the newly created user should be subscribed - to the [default streams][default-streams] for the organization. + Boolean indicating whether the newly created user should be subscribed + to the [default channels][default-channels] for the organization. - **Changes**: New in Zulip 9.0 (feature level 261). + Note that this parameter can be `true` even if the current user does + not generally have permission to [subscribe other users to + channels][can-subscribe-others]. - [default-streams]: /help/set-default-streams-for-new-users + **Changes**: New in Zulip 9.0 (feature level 261). Previous versions + of Zulip behaved as though this parameter was always `false`; clients + needed to include the organization's default streams in the + `stream_ids` parameter for a newly created user to be automatically + subscribed to them. + + [default-channels]: /help/set-default-channels-for-new-users + [can-subscribe-others]: /help/configure-who-can-invite-to-channels type: boolean + default: false example: false encoding: invite_expires_in_minutes: