Add section for "Conflict/overwrite decision algorithm" and label substeps so that...

[tahoe-lafs/tahoe-lafs.git] / docs / proposed / magic-folder / remote-to-local-sync.rst

diff --git a/docs/proposed/magic-folder/remote-to-local-sync.rst b/docs/proposed/magic-folder/remote-to-local-sync.rst
index 26f1825d4c56a68fc5efaf07b37e76b2340e617a..b41de7bfedaa7b70c785110e510eeda473ca4b53 100644 (file)
--- a/docs/proposed/magic-folder/remote-to-local-sync.rst
+++ b/docs/proposed/magic-folder/remote-to-local-sync.rst
@@ -690,9 +690,9 @@ Fire Dragons: Distinguishing conflicts from overwrites
 
 When synchronizing a file that has changed remotely, the Magic Folder
 client needs to distinguish between overwrites, in which the remote
-side was aware of your most recent version and overwrote it with a
-new version, and conflicts, in which the remote side was unaware of
-your most recent version when it published its new version. Those two
+side was aware of your most recent version (if any) and overwrote it
+with a new version, and conflicts, in which the remote side was unaware
+of your most recent version when it published its new version. Those two
 cases have to be handled differently — the latter needs to be raised
 to the user as an issue the user will have to resolve and the former
 must not bother the user.
@@ -768,6 +768,9 @@ metadata. This will have the effect of making other clients treat
 this change as a conflict whenever they already have a copy of the
 file.
 
+Conflict/overwrite decision algorithm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Now we are ready to describe the algorithm for determining whether a
 download for the file ``foo`` is an overwrite or a conflict (refining
 step 2 of the procedure from the `Earth Dragons`_ section).
@@ -776,12 +779,11 @@ Let ``last_downloaded_uri`` be the field of that name obtained from
 the directory entry metadata for ``foo`` in Bob's DMD (this field
 may be absent). Then the algorithm is:
 
-* 2a. If Alice has no local copy of ``foo``, classify as an overwrite.
-
-* 2b. Otherwise, "stat" ``foo`` to get its *current statinfo* (size
-  in bytes, ``mtime``, and ``ctime``).
+* 2a. Attempt to "stat" ``foo`` to get its *current statinfo* (size
+  in bytes, ``mtime``, and ``ctime``). If Alice has no local copy
+  of ``foo``, classify as an overwrite.
 
-* 2c. Read the following information for the path ``foo`` from the
+* 2b. Read the following information for the path ``foo`` from the
   local magic folder db:
 
   * the *last-uploaded statinfo*, if any (this is the size in
@@ -791,12 +793,13 @@ may be absent). Then the algorithm is:
     for this file, which is the URI under which the file was last
     uploaded.
 
-* 2d. If any of the following are true, then classify as a conflict:
+* 2c. If any of the following are true, then classify as a conflict:
 
-  * there are pending notifications of changes to ``foo``;
-  * the last-uploaded statinfo is either absent, or different
-    from the current statinfo;
-  * either ``last_downloaded_uri`` or ``last_uploaded_uri``
+  * i. there are pending notifications of changes to ``foo``;
+  * ii. the last-uploaded statinfo is either absent (i.e. there is
+    no entry in the database for this path), or different from the
+    current statinfo;
+  * iii. either ``last_downloaded_uri`` or ``last_uploaded_uri``
     (or both) are absent, or they are different.
 
   Otherwise, classify as an overwrite.