add docs about p2p --pair being broken in old versions

doc/assistant/share_with_a_friend_walkthrough.mdwn

@@ -6,6 +6,10 @@ install [Tor](https://torproject.org/) and
 [Magic Wormhole](https://github.com/warner/magic-wormhole), and then both
 follow these steps to connect your repositories.
 
+Important: You and your friend need git-annex version 6.20180705. Older
+versions of git-annex unfortunately had a bug that prevents this process
+from working correctly.
+
 Start by opening up your git annex webapp.
 
 [[!img local_pairing_walkthrough/addrepository.png alt="Add another repository button"]]

doc/bugs/apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocation.mdwn

@@ -70,3 +70,5 @@ Yes, but not `p2p --pair`.
 `p2p --link` works, including syncing, no problems with the remote daemon itself.
 
 ... and I wouldn't call it luck, i both trust and rely on git annex =)
+
+> [[fixed|done]]

doc/bugs/apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocation/comment_1_d403b087693d766b8f902c27964268e2._comment

@@ -0,0 +1,22 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 1"""
+ date="2018-07-05T15:28:15Z"
+ content="""
+Thanks much for reporting this bug. It turns out that shortly after I
+first implemented this, magic-wormhole switched to outputting that text on
+stderr, which defeated git-annex's attempt to extract the code phrase.
+
+[[!commit 3dd7f450c1968f8bc2b9cc73c701b1f12f7e326a]] fixes the bug.
+
+Really unfortunate this feature has been broken since almost the beginning.
+Especially because pairing with a friend will fail if they have an older
+version of git-annex. Added a note about this to the documentation.
+
+Clearly some better testing of this is needed. Testing network stuff like
+this is outside the bounds of git-annex's usual test suite, and perhaps it
+needs an additional test suite that is allowed to make network connections.
+(testremote is allowed to, but needs the remote to be manually set up,
+so this is also outside its scope). Opened [[todo/network_test_suite]]
+about this.
+"""]]

doc/git-annex-p2p.mdwn

@@ -32,6 +32,10 @@ services.
   the repositories, so you will need it installed on both computers that are
   being paired.
 
+  This feature was present in a broken form in git-annex versions
+  before version 6.20180705. Make sure that a new enough git-annex
+  is installed on both computers that are being paired.
+
 * `--gen-addresses`
 
   Generates addresses that can be used to access this git-annex repository

doc/tips/peer_to_peer_network_with_tor.mdwn

@@ -14,6 +14,9 @@ You also need to install [Magic Wormhole](https://github.com/warner/magic-wormho
 
 	sudo apt-get install magic-wormhole
 
+Important: You need git-annex version 6.20180705. Older versions of git-annex
+unfortunately had a bug that prevents this process from working correctly.
+
 ## pairing two repositories
 
 You have two git-annex repositories on different computers, and want to

doc/todo/network_test_suite.mdwn

@@ -0,0 +1,28 @@
+`git annex test` is not allowed to make network connections. (It does do some
+mocking to eg, test ssh special remotes without actually using ssh.)
+
+`git annex testremote` is allowed to use the network, but only when the
+user has set up a remote to test. Some parts of git-annex involve network
+connections, but not as part of accessing a remote, or are specific to a
+particular special remote. There outght to be a test suite for that stuff
+as well.
+
+A motivating example is `git annex p2p --pair`, which was 
+[[broken for years due to lack of testing|apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocaction]]. 
+Fully testing that would involve setting up tor hidden services which is far
+too extreme for a test suite (and needs root), but it should at least be
+possible to test the interface to magic-wormhole, allowing it to make a
+connection to the wormhole server.
+
+More examples: 
+
+* git-annex multicast (would need two hosts on a lan ideally but
+  could at least try to multicast back to the same host)
+* git-annex addurl and git-annex importfeed with http urls.
+  And testing the various security configs that affect them.
+
+This could be done as a new command or a flag to `git annex test`.
+In any case, the new test suite would need to be run somewhere;
+running it on at least some of the autobuilders might be a good way.
+
+--[[Joey]]