From 9880fcb936c33e38decc2823d4444c50494eb4e0 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Thu, 20 Apr 2023 15:03:07 +0200 Subject: [PATCH] narrow: Document new filters `is:dm`, `dm` and `dm-including`. Documents narrows now have support for new filters for direct messages: `is:dm`, `dm`, and `dm-including`. Also documents that `is:private`, `pm-with` and `group-pm-with` are now legacy aliases for these three new filters respectively. Note that API documentation references the help center documentation for search/narrow filters. Fixes #24806. --- api_docs/changelog.md | 14 ++++++++++++ api_docs/construct-narrow.md | 28 +++++++++++++++++++----- help/search-for-messages.md | 10 ++++----- version.py | 2 +- web/templates/search_operators.hbs | 8 +++---- zerver/openapi/zulip.yaml | 34 ++++++++++++++++++++++++------ 6 files changed, 74 insertions(+), 22 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index e01fb61135..3b6ef8146f 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -20,6 +20,20 @@ format used by the Zulip server that they are interacting with. ## Changes in Zulip 7.0 +**Feature level 177** + +* [`GET /messages`](/api/get-messages), + [`GET /messages/matches_narrow`](/api/check-messages-match-narrow), + [`POST /message/flags/narrow`](/api/update-message-flags-for-narrow), + [`POST /register`](/api/register-queue): + Added support for three [search/narrow filters](/api/construct-narrow) + 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. + The `dm-including` operator replaces and deprecates the `group-pm-with` + operator. Because existing Zulip messages may have links with these + legacy filters, they are still supported for backwards-compatibility. + **Feature level 176** * [`POST /realm/filters`](/api/add-linkifier), [`realm/filters/`](/api/update-linkifier): diff --git a/api_docs/construct-narrow.md b/api_docs/construct-narrow.md index e820d17251..5e7c440afb 100644 --- a/api_docs/construct-narrow.md +++ b/api_docs/construct-narrow.md @@ -45,6 +45,24 @@ operator, search the current user's personal message history. See [searching shared history](/help/search-for-messages#searching-shared-history) for details. +**Changes**: 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. + +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 The `near` and `id` operators, documented in the help center, use message @@ -59,12 +77,12 @@ help center because they are primarily useful to API clients: * `stream:1234`: Search messages sent to the stream with ID `1234`. * `sender:1234`: Search messages sent by user ID `1234`. -* `pm-with:1234`: Search the private message conversation between +* `dm:1234`: Search the direct message conversation between you and user ID `1234`. -* `pm-with:1234,5678`: Search the private message conversation between +* `dm:1234,5678`: Search the direct message conversation between you, user ID `1234`, and user ID `5678`. -* `group-pm-with:1234`: Search all group private messages that - include you and user ID `1234`. +* `dm-including:1234`: Search all direct messages (1-on-1 and group) + that include you and user ID `1234`. The operands for these search options must be encoded either as an integer ID or a JSON list of integer IDs. For example, to query @@ -74,7 +92,7 @@ and user 5678, the correct JSON-encoded query is: ```json [ { - "operator": "pm-with", + "operator": "dm", "operand": [1234, 5678] }, { diff --git a/help/search-for-messages.md b/help/search-for-messages.md index 84b6869856..a0090bedc0 100644 --- a/help/search-for-messages.md +++ b/help/search-for-messages.md @@ -51,12 +51,12 @@ Zulip offers the following filters based on the location of the message. * `stream:design`: Search within the stream **#design**. * `stream:design topic:new+logo`: Search within the topic "new logo" in **#design**. -* `is:private`: Search all your direct messages. -* `pm-with:Bo Lin`: Search 1-on-1 direct messages between you and Bo. -* `pm-with:Bo Lin, Elena García`: Search group direct messages +* `is:dm`: Search all your direct messages. +* `dm:Bo Lin`: Search 1-on-1 direct messages between you and Bo. +* `dm:Bo Lin, Elena García`: Search group direct messages between you, Bo, and Elena. -* `group-pm-with:Bo Lin`: Search all group direct message - conversations that include you and Bo, as well as any other users. +* `dm-including:Bo Lin`: Search all direct message conversations + (1-on-1 and group) that include you and Bo, as well as any other users. * `streams:public`: Search the history of all [public streams](/help/change-the-privacy-of-a-stream) in the organization, including streams you are not subscribed to; see details diff --git a/version.py b/version.py index 2775eab86a..0941fb3374 100644 --- a/version.py +++ b/version.py @@ -33,7 +33,7 @@ DESKTOP_WARNING_VERSION = "5.4.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 = 176 +API_FEATURE_LEVEL = 177 # 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/web/templates/search_operators.hbs b/web/templates/search_operators.hbs index 5a91098117..b4bf2687f7 100644 --- a/web/templates/search_operators.hbs +++ b/web/templates/search_operators.hbs @@ -37,13 +37,13 @@ - is:private + is:dm {{t 'Narrow to direct messages.'}} - pm-with:user + dm:user {{#tr}} Narrow to direct messages with . @@ -52,10 +52,10 @@ - group-pm-with:user + dm-including:user {{#tr}} - Narrow to group direct messages with . + Narrow to direct messages that include . {{#*inline "z-value"}}user{{/inline}} {{/tr}} diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 58ad08f2c7..66ca95f977 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -5278,8 +5278,13 @@ paths: subscribed to appropriate streams or use a shared history search narrow with this endpoint. - **Changes**: In Zulip 2.1.0, added support for using user/stream IDs - when constructing narrows for a message's sender, its stream and/or + **Changes**: In Zulip 7.0 (feature level 177), narrows gained support + for three new filters related to direct messages: `is:dm`, `dm` and + `dm-including`; replacing and deprecating `is:private`, `pm-with` and + `group-pm-with` respectively. + + In Zulip 2.1.0, added support for using user/stream IDs when + constructing narrows for a message's sender, its stream and/or its recipient(s). content: application/json: @@ -6023,6 +6028,11 @@ paths: description: | The narrow you want update flags within. See how to [construct a narrow](/api/construct-narrow). + + **Changes**: In Zulip 7.0 (feature level 177), narrows gained support + for three new filters related to direct messages: `is:dm`, `dm` and + `dm-including`; replacing and deprecating `is:private`, `pm-with` and + `group-pm-with` respectively. content: application/json: schema: @@ -6389,9 +6399,14 @@ paths: required: true - name: narrow in: query - description: + description: | A structure defining the narrow to check against. See how to [construct a narrow](/api/construct-narrow). + + **Changes**: In Zulip 7.0 (feature level 177), narrows gained support + for three new filters related to direct messages: `is:dm`, `dm` and + `dm-including`; replacing and deprecating `is:private`, `pm-with` and + `group-pm-with` respectively. content: application/json: schema: @@ -17983,14 +17998,14 @@ components: [narrow filter(s)](/api/construct-narrow) for which you'd like to receive events for. - For example, to receive events for private messages (including - group private messages) received by the user, one can use - `narrow=[["is", "private"]]`. + For example, to receive events for direct messages (including + group direct messages) received by the user, one can use + `narrow=[["is", "dm"]]`. Unlike the API for [fetching messages](/api/get-messages), this narrow parameter is simply a filter on messages that the user receives through their stream subscriptions (or because - they are a recipient of a private message). + they are a recipient of a direct message). This means that a client that requests a `narrow` filter of `[["stream", "Denmark"]]` will receive events for new messages @@ -18007,6 +18022,11 @@ components: public stream messages in an organization. Defaults to `[]`. + + **Changes**: In Zulip 7.0 (feature level 177), narrows gained support + for three new filters related to direct messages: `is:dm`, `dm` and + `dm-including`; replacing and deprecating `is:private`, `pm-with` and + `group-pm-with` respectively. content: application/json: schema: