[PATCH 2 of 3] changegroup: document the cases where reordering complicates linkrevs

[Martin von Zweigbergk]

# HG changeset patch
# User Martin von Zweigbergk <martinvonz at google.com>
# Date 1430339107 25200
#      Wed Apr 29 13:25:07 2015 -0700
# Node ID c57f0091d3e06d48d6a347ef982a8ebaab5d6352
# Parent  538c527d7cb7c929a107ffebf5d05bc413d4526a
changegroup: document the cases where reordering complicates linkrevs

diff -r 538c527d7cb7 -r c57f0091d3e0 mercurial/changegroup.py
--- a/mercurial/changegroup.py	Wed Apr 29 10:34:28 2015 -0700
+++ b/mercurial/changegroup.py	Wed Apr 29 13:25:07 2015 -0700
@@ -385,6 +385,21 @@
             yield chunk
         self._verbosenote(_('%8.i (changelog)\n') % size)
 
+        # We need to make sure that the linkrev in the changegroup refers to
+        # the first changeset that introduced the manifest or file revision.
+        # The fastpath is usually safer than the slowpath, because the filelogs
+        # are walked in revlog order.
+        #
+        # When taking the slowpath with reorder=None and the manifest revlog
+        # uses generaldelta, the manifest may be walked in the "wrong" order.
+        # Without 'clrevorder', we would get an incorrect linkrev (see fix in
+        # cc0ff93d0c0c).
+        #
+        # When taking the fastpath, we are only vulnerable to reordering
+        # of the changelog itself. The changelog never uses generaldelta, so
+        # it is only reordered when reorder=True. To handle this case, we
+        # simply take the slowpath, which already has the 'clrevorder' logic.
+        # This was also fixed in cc0ff93d0c0c.
         fastpathlinkrev = fastpathlinkrev and not self._reorder
         # Callback for the manifest, used to collect linkrevs for filelog
         # revisions.