diff hgext3rd/pullbundle.py @ 4132:afc933d32085

pullbundle: add extension documentation

--- a/hgext3rd/pullbundle.py	Sun Sep 23 23:46:49 2018 +0200
+++ b/hgext3rd/pullbundle.py	Sun Sep 23 22:45:23 2018 +0200
@@ -4,7 +4,62 @@
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
+"""pullbundle: automatic server side bundle caching
 
+General principle
+=================
+
+This extension provides a means for server to use pre-computed bundle for
+serving arbitrary pulls. If missing, the necessary pre-computed bundle will be
+generated on demand.
+
+To maximize usage of existing cached bundle, each pull will be served through
+multiple bundles. The bundle will be created using "standard range" from the
+"stablerange" principle. The "stablerange" concept if already used for
+obsmarkers discovery in the evolve extensions.
+
+Using pull Bundle
+=================
+
+All configuration is only required server side.
+
+The "stablerange" code currently still live in the evolve extensions, so for
+now enabling that extensions is required:
+
+You need at minimum the following configuration:
+
+    [extensions]
+    evolve=yes
+    pullbundle=yes
+    [experimental]
+    obshashrange.warm-cache = yes
+
+If you do not want to use evolution server side, you should disable obsmarkers exchange:
+
+    [experimental]
+    evolution.exchange=no
+
+Implementation status
+=====================
+
+Both for stablerange and pullbundle use "simple" initial implementations.
+Theses implemenations focus on testing the algorithms and proving the features
+works. Yet they are already useful and used in production.
+
+Performances are expected to greatly improved in the final implementation,
+especially if some of it end up being compiled.
+
+This first implementation lacks the ability to server the cached bundle from a
+CDN. We'll want this limitation to be lifted quickly.
+
+Why is does this live in the same repository as evolve
+======================================================
+
+There is no fundamental reasons for live in the same repository. However, the
+stablerange data-structure lives in evolve, so it was simpler to put this new
+extensions next to it. As soon as stable range have been upstreamed, we won't
+need the dependency to the evolve extension anymore.
+"""
 import errno
 import os