paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-17 04:12:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

groups: Rework documentation of permitted values.

Browse Source 
Ths hardcoded documentation of which values are possible was destined
to end up inaccurate and out-of-date; and meanwhile, we do have a part
of the API that already has these data in machine-readable format.
This commit is contained in:
Tim Abbott
2024-10-07 16:24:35 -07:00
parent 777f6be88f
commit c39e86504a
2 changed files with 37 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
api_docs/group-setting-values.md
View File

@@ -88,3 +88,29 @@ accidentally reverts the first one without either user noticing.
Omitting `old` is appropriate where the intent really is a new complete 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 rather than an edit, for example in an integration that syncs the
list from an external source of truth. list from an external source of truth.
## Permitted values
Not every possible group-setting value is a valid configuration for a
given group-based setting. For example, as a security hardening
measure, some administrative permissions should never be exercised by
guest users, and the system group for all users, including guests,
should not be offered to users as an option for those settings.
Others have restrictions to only permit system groups due to UI
components not yet having been migrated to support a broader set of
values. In order to avoid this configuration ending up hardcoded in
clients, every permission setting using this framework has an entry in
the `server_supported_permission_settings` section of the [`POST
/register`](/api/register-queue) response.
Clients that support mutating group-settings values must parse that
part of the `register` payload in order to compute the set of
permitted values to offer to the user and avoid server-side errors
when trying to save a value.
Note specifically that the `allow_everyone_group` field, which
determines whether the setting can have the value of "all user
accounts, including guests" also controls whether guests users can
exercise the permission regardless of their membership in the
group-setting value.

46
zerver/openapi/zulip.yaml
View File

@@ -4304,9 +4304,6 @@ paths:
the set of users who have permission to create user the set of users who have permission to create user
groups in this organization. groups in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
and `"role:nobody"` system groups.
**Changes**: New in Zulip 10.0 (feature level 299). Previously **Changes**: New in Zulip 10.0 (feature level 299). Previously
`user_group_edit_policy` field used to control the permission `user_group_edit_policy` field used to control the permission
to create user groups. to create user groups.
@@ -4318,9 +4315,6 @@ paths:
defining the set of users who have permission to defining the set of users who have permission to
administer all existing groups in this organization. administer all existing groups in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
and `"role:nobody"` system groups.
**Changes**: Semantics to change in Zulip 10.0 (feature **Changes**: Semantics to change in Zulip 10.0 (feature
level TBD). The original implementation of this setting level TBD). The original implementation of this setting
had different semantics, where only users who were a had different semantics, where only users who were a
@@ -4348,9 +4342,6 @@ paths:
the set of users who have permission to create public the set of users who have permission to create public
channels in this organization. channels in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
`"role:owners"` and `"role:nobody"` system groups.
**Changes**: New in Zulip 9.0 (feature level 264). Previously **Changes**: New in Zulip 9.0 (feature level 264). Previously
`realm_create_public_stream_policy` field used to control the `realm_create_public_stream_policy` field used to control the
permission to create public channels. permission to create public channels.
@@ -4362,9 +4353,6 @@ paths:
the set of users who have permission to create private the set of users who have permission to create private
channels in this organization. channels in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
`"role:owners"` and `"role:nobody"` system groups.
**Changes**: New in Zulip 9.0 (feature level 266). Previously **Changes**: New in Zulip 9.0 (feature level 266). Previously
`realm_create_private_stream_policy` field used to control the `realm_create_private_stream_policy` field used to control the
permission to create private channels. permission to create private channels.
@@ -4376,10 +4364,6 @@ paths:
the set of users who have permission to create web-public the set of users who have permission to create web-public
channels in this organization. channels in this organization.
This setting can only be set to `"role:moderators"`,
`"role:administrators"`, `"role:owners"` and
`"role:nobody"` system groups.
**Changes**: New in Zulip 10.0 (feature level 280). Previously **Changes**: New in Zulip 10.0 (feature level 280). Previously
`realm_create_web_public_stream_policy` field used to control `realm_create_web_public_stream_policy` field used to control
the permission to create web-public channels. the permission to create web-public channels.
@@ -16121,9 +16105,6 @@ paths:
the set of users who have permission to create user the set of users who have permission to create user
groups in this organization. groups in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
and `"role:nobody"` system groups.
**Changes**: New in Zulip 10.0 (feature level 299). Previously **Changes**: New in Zulip 10.0 (feature level 299). Previously
`realm_user_group_edit_policy` field used to control the `realm_user_group_edit_policy` field used to control the
permission to create user groups. permission to create user groups.
@@ -16135,9 +16116,6 @@ paths:
defining the set of users who have permission to defining the set of users who have permission to
administer all existing groups in this organization. administer all existing groups in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
and `"role:nobody"` system groups.
**Changes**: Semantics to change in Zulip 10.0 (feature **Changes**: Semantics to change in Zulip 10.0 (feature
level TBD). The original implementation of this setting level TBD). The original implementation of this setting
had different semantics, where only users who were a had different semantics, where only users who were a
@@ -16165,9 +16143,6 @@ paths:
the set of users who have permission to create public the set of users who have permission to create public
channels in this organization. channels in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
`"role:owners"` and `"role:nobody"` system groups.
**Changes**: New in Zulip 9.0 (feature level 264). Previously **Changes**: New in Zulip 9.0 (feature level 264). Previously
`realm_create_public_stream_policy` field used to control the `realm_create_public_stream_policy` field used to control the
permission to create public channels. permission to create public channels.
@@ -16179,9 +16154,6 @@ paths:
the set of users who have permission to create private the set of users who have permission to create private
channels in this organization. channels in this organization.
This setting cannot be set to `"role:internet"`, `"role:everyone"`,
`"role:owners"` and `"role:nobody"` system groups.
**Changes**: New in Zulip 9.0 (feature level 266). Previously **Changes**: New in Zulip 9.0 (feature level 266). Previously
`realm_create_private_stream_policy` field used to control the `realm_create_private_stream_policy` field used to control the
permission to create private channels. permission to create private channels.
@@ -16193,10 +16165,6 @@ paths:
the set of users who have permission to create web-public the set of users who have permission to create web-public
channels in this organization. channels in this organization.
This setting can only be set to `"role:moderators"`,
`"role:administrators"`, `"role:owners"` and
`"role:nobody"` system groups.
Has no effect and should not be displayed in settings UI Has no effect and should not be displayed in settings UI
unless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED` unless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED`
server-level setting enabled and the organization has enabled server-level setting enabled and the organization has enabled
@@ -18073,10 +18041,15 @@ paths:
description: | description: |
Present if `realm` is present in `fetch_event_types`. Present if `realm` is present in `fetch_event_types`.
Configuration for various group permission settings. Metadata detailing the valid values for permission settings that
use [group-setting values](/api/group-setting-values). Clients
should use these data as explained in the
[main documentation](/api/group-setting-values#permitted-values)
to determine what values to present as possible values for these
settings in UI components.
We consider this part of the Zulip API to be unstable This part of the Zulip API is unstable and may change
and may change significantly in future versions. significantly in future versions.
**Changes**: New in Zulip 8.0 (feature level 221). **Changes**: New in Zulip 8.0 (feature level 221).
type: object type: object
@@ -23049,6 +23022,9 @@ components:
type: boolean type: boolean
description: | description: |
Whether the setting can be set to `role:everyone` system group. Whether the setting can be set to `role:everyone` system group.
If false, guest users cannot exercise this permission even if they are part of
the [group-setting value](/api/group-setting-values) for this setting.
default_group_name: default_group_name:
type: string type: string
description: | description: |