From 4e0f107ef7207fde8bd9feafdd3bea88caad89b8 Mon Sep 17 00:00:00 2001
From: Valentin Deniaud <valentin.deniaud@inpt.fr>
Date: Thu, 19 Jul 2018 19:57:47 +0200
Subject: [PATCH] document changed field behavior in e2e sync extension

---
 .../modules/end_to_end_encryption.rst         | 31 ++++++++++++++++---
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst
index 1bc6a232..194d2567 100644
--- a/specification/modules/end_to_end_encryption.rst
+++ b/specification/modules/end_to_end_encryption.rst
@@ -176,9 +176,10 @@ process:
    flag.
 
 #. During its normal processing of responses to |/sync|_, Alice's client
-   inspects the |device_lists|_ field. If it is tracking the device lists of
-   any of the listed users, then it marks the device lists for those users
-   outdated, and initiates another request to |/keys/query|_ for them.
+   inspects the ``changed`` property of the |device_lists|_ field. If it is
+   tracking the device lists of any of the listed users, then it marks the
+   device lists for those users outdated, and initiates another request to
+   |/keys/query|_ for them.
 
 #. Periodically, Alice's client stores the ``next_batch`` field of the result
    from |/sync|_ in persistent storage. If Alice later restarts her client, it
@@ -214,6 +215,18 @@ process:
    that the first request's results are ignored (possibly by cancelling the
    request).
 
+.. Note::
+
+  When Bob and Alice share a room, with Bob tracking Alice's devices, she may leave
+  the room and then add a new device. Bob will not be notified of this change,
+  as he doesn't share a room anymore with Alice. When they start sharing a
+  room again, Bob has an out-of-date list of Alice's devices. In order to address
+  this issue, Bob's homeserver will add Alice's user ID to the ``changed`` property of
+  the ``device_lists`` field, thus Bob will update his list of Alice's devices as part
+  of his normal processing. Note that Bob can also be notified when he stops sharing
+  any room with Alice by inspecting the ``left`` property of the ``device_lists``
+  field, and as a result should remove her from its list of tracked users.
+
 .. |device_lists| replace:: ``device_lists``
 .. _`device_lists`: `device_lists_sync`_
 
@@ -500,12 +513,20 @@ device_lists DeviceLists Optional. Information on e2e device updates. Note:
 ========= ========= =============================================
 Parameter Type      Description
 ========= ========= =============================================
-changed   [string]  List of users who have updated their device identity keys
-                    since the previous sync response.
+changed   [string]  List of users who have updated their device identity keys,
+                    or who now share an encrypted room with the client since
+                    the previous sync response.
 left      [string]  List of users with whom we do not share any encrypted rooms
                     anymore since the previous sync response.
 ========= ========= =============================================
 
+.. NOTE::
+
+  For optimal performance, Alice should be added to ``changed`` in Bob's sync only
+  when she adds a new device, or when Alice and Bob now share a room but didn't
+  share any room previously. However, for the sake of simpler logic, a server
+  may add Alice to ``changed`` when Alice and Bob share a new room, even if they
+  previously already shared a room.
 
 Example response: