Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Lauryn Menard 2023-04-20 15:03:07 +02:00 committed by Tim Abbott
parent ae41e61520
commit 9880fcb936
6 changed files with 74 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
api_docs/changelog.md
View File

@ -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/<int:filter_id>`](/api/update-linkifier):

28
api_docs/construct-narrow.md
View File

@ -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]
},
{

10
help/search-for-messages.md
View File

@ -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

2
version.py
View File

@ -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

8
web/templates/search_operators.hbs
View File

@ -37,13 +37,13 @@
</td>
</tr>
<tr>
<td class="operator">is:private</td>
<td class="operator">is:dm</td>
<td class="definition">
{{t 'Narrow to direct messages.'}}
</td>
</tr>
<tr>
<td class="operator">pm-with:<span class="operator_value">user</span></td>
<td class="operator">dm:<span class="operator_value">user</span></td>
<td class="definition">
{{#tr}}
Narrow to direct messages with <z-value></z-value>.
@ -52,10 +52,10 @@
</td>
</tr>
<tr>
<td class="operator">group-pm-with:<span class="operator_value">user</span></td>
<td class="operator">dm-including:<span class="operator_value">user</span></td>
<td class="definition">
{{#tr}}
Narrow to group direct messages with <z-value></z-value>.
Narrow to direct messages that include <z-value></z-value>.
{{#*inline "z-value"}}<span class="operator_value">user</span>{{/inline}}
{{/tr}}
</td>

34
zerver/openapi/zulip.yaml
View File

@ -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: