Merge pull request #2096 from matrix-org/travis/1.0/read-notifs

Clarify how notification counts are calculated in /sync

api/client-server/sync.yaml

@@ -167,11 +167,13 @@ paths:
                             this room.
                           allOf:
                           - $ref: "definitions/event_batch.yaml"
-                        "unread_notifications":
+                        unread_notifications:
                           title: Unread Notification Counts
                           type: object
                           description: |-
-                            Counts of unread notifications for this room
+                            Counts of unread notifications for this room. See the
+                            `Receiving notifications section <#receiving-notifications>`_
+                            for more information on how these are calculated.
                           properties:
                             highlight_count:
                                 title: Highlighted notification count

changelogs/client_server/newsfragments/2097.clarification

@@ -0,0 +1 @@
+Clarify how ``unread_notifications`` is calculated.

specification/modules/push.rst

@@ -1,4 +1,5 @@
 .. Copyright 2016 OpenMarket Ltd
+.. Copyright 2019 The Matrix.org Foundation C.I.C.
 ..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
@@ -116,6 +117,16 @@ have received.
 
 {{notifications_cs_http_api}}
 
+Receiving notifications
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Servers MUST include the number of unread notifications in a client's ``/sync``
+stream, and MUST update it as it changes. Notifications are determined by the
+push rules which apply to an event.
+
+When the user updates their read receipt (either by using the API or by sending an
+event), notifications prior to and including that event MUST be marked as read.
+
 Push Rules
 ~~~~~~~~~~
 A push rule is a single rule that states under what *conditions* an event should

specification/modules/receipts.rst

@@ -26,7 +26,8 @@ to a homeserver. To prevent this from becoming a problem, receipts are implement
 using "up to" markers. This marker indicates that the acknowledgement applies
 to all events "up to and including" the event specified. For example, marking
 an event as "read" would indicate that the user had read all events *up to* the
-referenced event.
+referenced event. See the `Receiving notifications <#receiving-notifications>`_
+section for more information on how read receipts affect notification counts.
 
 Events
 ------