From b9c33ce5f13e0c5bae492e597312845a5c5d45f9 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Wed, 17 Jul 2024 04:57:40 +0200 Subject: [PATCH] api-docs: Add changes section in construct a narrow article. Adds a header to the section of changes notes about new and deprecated narrow filters, so that it's easier to directly link to the relevant content in the construct a narrow article from the main API changelog and endpoint documentation. --- api_docs/changelog.md | 16 +++++----- api_docs/construct-narrow.md | 61 +++++++++++++++++++----------------- zerver/openapi/zulip.yaml | 12 ++++--- 3 files changed, 48 insertions(+), 41 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 3cdf94ce14..9b40df66a9 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -43,7 +43,7 @@ format used by the Zulip server that they are interacting with. [`GET /messages/matches_narrow`](/api/check-messages-match-narrow), [`POST /messages/flags/narrow`](/api/update-message-flags-for-narrow), [`POST /register`](/api/register-queue): - Added support for a new [search/narrow filter](/api/construct-narrow), + Added support for a new [search/narrow filter](/api/construct-narrow#changes), `with`, which returns messages in the same channel and topic as that of the operand of filter, with the first unread message as anchor. @@ -105,7 +105,7 @@ format used by the Zulip server that they are interacting with. [`GET /messages/matches_narrow`](/api/check-messages-match-narrow), [`POST /messages/flags/narrow`](/api/update-message-flags-for-narrow), [`POST /register`](/api/register-queue): - Added a new [search/narrow filter](/api/construct-narrow), + Added a new [search/narrow filter](/api/construct-narrow#changes), `is:followed`, matching messages in topics that the current user is [following](/help/follow-a-topic). @@ -254,7 +254,7 @@ format used by the Zulip server that they are interacting with. [`GET /messages/matches_narrow`](/api/check-messages-match-narrow), [`POST /messages/flags/narrow`](/api/update-message-flags-for-narrow), [`POST /register`](/api/register-queue): - Added support for two [search/narrow filters](/api/construct-narrow) + Added support for two [search/narrow filters](/api/construct-narrow#changes) related to stream messages: `channel` and `channels`. The `channel` operator is an alias for the `stream` operator. The `channels` operator is an alias for the `streams` operator. @@ -265,7 +265,7 @@ format used by the Zulip server that they are interacting with. [`GET /messages/matches_narrow`](/api/check-messages-match-narrow), [`POST /messages/flags/narrow`](/api/update-message-flags-for-narrow), [`POST /register`](/api/register-queue): - Added support for a new [search/narrow filter](/api/construct-narrow), + Added support for a new [search/narrow filter](/api/construct-narrow#changes), `has:reaction`, which returns messages with at least one [emoji reaction](/help/emoji-reactions). @@ -781,8 +781,8 @@ No changes; feature level used for Zulip 8.0 release. [`GET /messages/matches_narrow`](/api/check-messages-match-narrow), [`POST /messages/flags/narrow`](/api/update-message-flags-for-narrow), [`POST /register`](/api/register-queue): - For [search/narrow filters](/api/construct-narrow) with the `id` - operator, added support for encoding the message ID operand as either + For [search/narrow filters](/api/construct-narrow#message-ids) with the + `id` operator, added support for encoding the message ID operand as either a string or an integer. Previously, only string encoding was supported. **Feature level 193** @@ -917,7 +917,7 @@ No changes; feature level used for Zulip 7.0 release. [`GET /messages/matches_narrow`](/api/check-messages-match-narrow), [`POST /messages/flags/narrow`](/api/update-message-flags-for-narrow), [`POST /register`](/api/register-queue): - Added support for three [search/narrow filters](/api/construct-narrow) + Added support for three [search/narrow filters](/api/construct-narrow#changes) related to direct messages: `is:dm`, `dm` and `dm-including`. The `dm` operator replaces and deprecates the `pm-with` operator. The `is:dm` filter replaces and deprecates the `is:private` filter. @@ -2389,7 +2389,7 @@ No changes; feature level used for Zulip 3.0 release. * [`POST /register`](/api/register-queue): Added `realm_default_external_accounts` to endpoint response. * [`GET /messages`](/api/get-messages): Added support for - [search/narrow options](/api/construct-narrow) that use stream/user + [search/narrow options](/api/construct-narrow#changes) that use stream/user IDs to specify a message's sender, its stream, and/or its recipient(s). * [`GET /users`](/api/get-users): Added `include_custom_profile_fields` to request custom profile field data. diff --git a/api_docs/construct-narrow.md b/api_docs/construct-narrow.md index fc03b0eaf2..ecc6887ae9 100644 --- a/api_docs/construct-narrow.md +++ b/api_docs/construct-narrow.md @@ -51,41 +51,44 @@ important optimization when fetching messages in certain cases (e.g., when [adding the `read` flag to a user's personal messages](/api/update-message-flags-for-narrow)). -**Changes**: In Zulip 9.0 (feature level 271), narrows gained support -for a new `with` operator for linking to topics. +## Changes -In Zulip 9.0 (feature level 265), support was added for a -new `is:followed` filter, matching messages in topics that the current -user is [following](/help/follow-a-topic). +* In Zulip 9.0 (feature level 271), narrows gained support + for a new `with` operator for linking to topics. -In Zulip 9.0 (feature level 250), support was added for -two filters related to stream messages: `channel` and `channels`. The -`channel` operator is an alias for the `stream` operator. The `channels` -operator is an alias for the `streams` operator. Both `channel` and -`channels` return the same exact results as `stream` and `streams` -respectively. +* In Zulip 9.0 (feature level 265), support was added for a new + `is:followed` filter, matching messages in topics that the current + user is [following](/help/follow-a-topic). -In Zulip 9.0 (feature level 249), support was added for a new filter, -`has:reaction`, which returns messages that have at least one [emoji -reaction](/help/emoji-reactions). +* In Zulip 9.0 (feature level 250), support was added for two filters + related to stream messages: `channel` and `channels`. The `channel` + operator is an alias for the `stream` operator. The `channels` + operator is an alias for the `streams` operator. Both `channel` and + `channels` return the same exact results as `stream` and `streams` + respectively. -In Zulip 7.0 (feature level 177), support was added -for three filters related to direct messages: `is:dm`, `dm` and -`dm-including`. The `dm` operator replaced and deprecated the -`pm-with` operator. The `is:dm` filter replaced and deprecated -the `is:private` filter. The `dm-including` operator replaced and -deprecated the `group-pm-with` operator. +* In Zulip 9.0 (feature level 249), support was added for a new filter, + `has:reaction`, which returns messages that have at least one [emoji + reaction](/help/emoji-reactions). -The `dm-including` and `group-pm-with` operators return slightly -different results. For example, `dm-including:1234` returns all -direct messages (1-on-1 and group) that include the current user -and the user with the unique user ID of `1234`. On the other hand, -`group-pm-with:1234` returned only group direct messages that included -the current user and the user with the unique user ID of `1234`. +* In Zulip 7.0 (feature level 177), support was added for three filters + related to direct messages: `is:dm`, `dm` and `dm-including`. The + `dm` operator replaced and deprecated the `pm-with` operator. The + `is:dm` filter replaced and deprecated the `is:private` filter. The + `dm-including` operator replaced and deprecated the `group-pm-with` + operator. -Both `dm` and `is:dm` are aliases of `pm-with` and `is:private` -respectively, and return the same exact results that the deprecated -filters did. + * The `dm-including` and `group-pm-with` operators return slightly + different results. For example, `dm-including:1234` returns all + direct messages (1-on-1 and group) that include the current user + and the user with the unique user ID of `1234`. On the other hand, + `group-pm-with:1234` returned only group direct messages that + included the current user and the user with the unique user ID of + `1234`. + + * Both `dm` and `is:dm` are aliases of `pm-with` and `is:private` + respectively, and return the same exact results that the + deprecated filters did. ## Narrows that use IDs diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 9522454bf8..467d62c8ff 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -6266,7 +6266,8 @@ paths: subscribed to appropriate channels or use a shared history search narrow with this endpoint. - **Changes**: See changelog at [Construct a narrow](/api/construct-narrow). + **Changes**: See [changes section](/api/construct-narrow#changes) + of search/narrow filter documentation. content: application/json: schema: @@ -7129,7 +7130,8 @@ paths: optimization. Including that filter takes advantage of the fact that the server has a database index for unread messages. - **Changes**: See changelog at [Construct a narrow](/api/construct-narrow). + **Changes**: See [changes section](/api/construct-narrow#changes) + of search/narrow filter documentation. type: array items: oneOf: @@ -7550,7 +7552,8 @@ paths: A structure defining the narrow to check against. See how to [construct a narrow](/api/construct-narrow). - **Changes**: See changelog at [Construct a narrow](/api/construct-narrow). + **Changes**: See [changes section](/api/construct-narrow#changes) + of search/narrow filter documentation. content: application/json: schema: @@ -22673,7 +22676,8 @@ components: See the `all_public_streams` parameter for how to process all public channel messages in an organization. - **Changes**: See changelog at [Construct a narrow](/api/construct-narrow). + **Changes**: See [changes section](/api/construct-narrow#changes) + of search/narrow filter documentation. type: array items: type: array