remote-to-local-sync.rst: Conflict Detection and Resolution WIP

Signed-off-by: Daira Hopwood <daira@jacaranda.org>

diff --git a/docs/proposed/magic-folder/remote-to-local-sync.rst b/docs/proposed/magic-folder/remote-to-local-sync.rst
index 63ece7f59cf2c8b78a59e7ce9e9ab769cc9ac73e..eeabc15c12215acdae9bcf6f73aa47593182ae6e 100644 (file)
--- a/docs/proposed/magic-folder/remote-to-local-sync.rst
+++ b/docs/proposed/magic-folder/remote-to-local-sync.rst
@@ -244,17 +244,37 @@ each file encodes the full subpath of that file relative to the Magic
 Folder.
 
 
-*Conflict detection*
+Conflict Detection and Resolution
+---------------------------------
 
-there are several kinds of dragon [*]
+In our discussion of design issues for conflict detection and resolution,
+we classified various problems as "dragons", which as a convenient
+mnemonic we have named after the five classical Greek elements
+(Earth, Air, Water, Fire and Aether).
 
-earth dragons: write/download and read/download collisions
+*Glossary*
+
+Write:    a modification to a local filesystem object by a client
+Read:     a read from a local filesystem object by a client
+Upload:   an upload of a local object to the Tahoe-LAFS file store
+Download: a download from the Tahoe-LAFS file store to a local object
+Pending notification: a local filesystem change that has been detected
+but not yet processed.
+
+*Earth Dragons: write/download and read/download collisions*
+
+Suppose that Alice changes the file ``foo`` locally, concurrently
+with Alice's Magic Folder client writing a version of ``foo`` that
+it has downloaded in response to a remote change.
+
+An important constraint on the design is that on Windows, it is
+not possible to rename a file to the same name as an existing
+file in that directory.
 
-alice changes 'foo' locally while alice's gateway is writing 'foo'
-locally (in response to a remote change)
+Without this constraint, it would be possible to use the following
+common technique for implementing "atomic" writes on Unix:
 
-alice's gateway
-* writes a temporary file foo.tmp
+* Alice's Magic Folder client writes a temporary file ``foo.tmp``
 * if 'foo' is clean, i.e. there are no pending notifications, it moves
 foo.tmp over foo [FIXME: if we want to preserve old versions then it
 should rename the old version first; see below]