From 49cc94f61f64a8785cb8a3ed4899a17e5361ceb1 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Thu, 5 Jul 2018 11:52:52 -0400 Subject: [PATCH] add docs about p2p --pair being broken in old versions --- .../share_with_a_friend_walkthrough.mdwn | 4 +++ ...ir_usage_of_magic_wormhole_invocation.mdwn | 2 ++ ..._d403b087693d766b8f902c27964268e2._comment | 22 +++++++++++++++ doc/git-annex-p2p.mdwn | 4 +++ doc/tips/peer_to_peer_network_with_tor.mdwn | 3 ++ doc/todo/network_test_suite.mdwn | 28 +++++++++++++++++++ 6 files changed, 63 insertions(+) create mode 100644 doc/bugs/apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocation/comment_1_d403b087693d766b8f902c27964268e2._comment create mode 100644 doc/todo/network_test_suite.mdwn diff --git a/doc/assistant/share_with_a_friend_walkthrough.mdwn b/doc/assistant/share_with_a_friend_walkthrough.mdwn index 0766ffa3e1..a5a6d68170 100644 --- a/doc/assistant/share_with_a_friend_walkthrough.mdwn +++ b/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"]] diff --git a/doc/bugs/apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocation.mdwn b/doc/bugs/apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocation.mdwn index bb5dee5faa..7f5b2c9315 100644 --- a/doc/bugs/apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocation.mdwn +++ b/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]] diff --git a/doc/bugs/apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocation/comment_1_d403b087693d766b8f902c27964268e2._comment b/doc/bugs/apparent_regression_in_git_annex_p2p_--pair_usage_of_magic_wormhole_invocation/comment_1_d403b087693d766b8f902c27964268e2._comment new file mode 100644 index 0000000000..e4efcb5b53 --- /dev/null +++ b/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. +"""]] diff --git a/doc/git-annex-p2p.mdwn b/doc/git-annex-p2p.mdwn index 28fcea3960..060ce5da86 100644 --- a/doc/git-annex-p2p.mdwn +++ b/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 diff --git a/doc/tips/peer_to_peer_network_with_tor.mdwn b/doc/tips/peer_to_peer_network_with_tor.mdwn index 0832fa41df..606d067a1e 100644 --- a/doc/tips/peer_to_peer_network_with_tor.mdwn +++ b/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 diff --git a/doc/todo/network_test_suite.mdwn b/doc/todo/network_test_suite.mdwn new file mode 100644 index 0000000000..337dbaf11f --- /dev/null +++ b/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]]