add

doc/bugs/xmpp_needs_one_account_per_distinct_repository.mdwn

@@ -0,0 +1,83 @@
+The way [[XMPP pairing|design/assistant/XMPP]] currently works, each
+separate repository needs to use a different XMPP account. If two
+repositories use the same XMPP account, then they will be combined together
+than XMPP pairing takes place.
+
+There are two different UIs for XMPP pairing. While the same protocol
+is running behind the scenes, these UIs should be considered separately.
+
+## Share with your other devices
+
+Here, I think it makes sense to require the user to use the same XMPP
+account on all their devices (otherwise it's pairing with a friend), and
+automatically combine repositories of devices that use the same XMPP
+account.
+
+The UI is pretty clear about this:
+
+	If you have multiple devices, all running git-annex, and using #
+	your Jabber account #{account}, you can configure them to share #
+	your files between themselves.
+
+Doing it this way avoids needing to confirm pair requests coming from the same
+XMPP account. Which means that, for example, you can have a device at home,
+and one at work, and pair them by simply initiating a pair request from one
+to the other. You don't have to travel between home and work to confirm 
+the request.
+
+(Also, when you have a lot of devices, this avoids a combinatorial explosion
+of pair request confirmations.)
+
+The only problem with this is that users who want multiple repositories
+need to find multiple XMPP accounts. However, I'm inclined to think this is
+a reasonable requirement.
+
+## Share with a friend
+
+Suppose that Alice wants to share with Bob. Bob is using the same XMPP
+account for two separate repositories, that are not themselves paired.
+
+When Alice chooses to share with Bob, a XMPP pair request is sent.
+Both of Bob's repositories see it, and both ask him to confirm.
+Bob can choose to only confirm the request in one repository, and 
+not in the other. This should work ok.
+
+* The UI for this only says "Pair request received from #{name}",
+  it does not indicate which repository of Alice's is being paired
+  with. This could be improved. If Alice has two repositories as well,
+  she and Bob will want to coordinate pairing the right ones together.
+  Could be fixed by just displaying the description of Alice's repisitory
+  to Bob.
+
+-----
+
+Now, suppose that Alice makes a second, distinct repository, and chooses to
+share it with Bob (intending to share with his second repository). This
+sends an XMPP pair request to both of Bob's repositories.
+
+One of Bob's repositories has already paired with Alice, so it assumes this
+new pair request is from a different device belonging to Alice, and it
+automatically ACKs the pair request. 
+
+The result is that Alice's new repository combines with Bob's repository,
+which is already combined with Alice's old repository. Effectively
+combining both her repositories, unexpectedly. **This is a bug**.
+
+1. I think this could be fixed by simply not auto-accepting pair requests
+   from friends we're already paired with. Require another confirmation.
+2. Or, only auto-accept pair requests from friends we're already paired with
+   when they come from a repository whose UUID we already know. This
+   enhancment to fix #1 makes it easier to build more robust networks of
+   repositories.
+3. Alternatively, we could say that the problem is that Bob has two 
+   distinct repositories using the same XMPP account, and try to prevent
+   him from doing that in the first place. 
+   
+   One way to do this would be, when configuring the
+   XMPP account, scan for other repositories using the same account, and
+   don't let it be used unless the user confirms they want to pair them.
+   But, this doesn't seem viable because if the other repository is on
+   another device, which is turned off, this check wouldn't see it.
+
+   Or there could be a warning about account reuse. Doesn't seem likely to
+   be effective.

doc/design/assistant/xmpp.mdwn

@@ -9,11 +9,16 @@ who share a repository, that is stored in the [[cloud]].
 * Do git-annex clients sharing an account with regular clients cause confusing
   things to happen? 
   See <http://git-annex.branchable.com/design/assistant/blog/day_114__xmpp/#comment-aaba579f92cb452caf26ac53071a6788>
+
 * Support use of a single XMPP account with several separate and
   independant git-annex repos. This probably works for the simple
   push notification use of XMPP, since unknown UUIDs will just be ignored.
   But XMPP pairing and the pushes over XMPP assume that anyone you're
   paired with is intending to sync to your repository.
+  [[bugs/xmpp_needs_one_account_per_distinct_repository]]
+
+  There are really two cases here, "Share with your other devices",
+  and 
 
 ## design goals