--- a/README	Sun May 21 13:55:09 2017 +0200
+++ b/README	Sun May 21 14:20:24 2017 +0200
@@ -117,6 +117,7 @@
 
  - prune: fix a crash related to color handling,
  - next: fix a crash related to color handling,
+ - discovery: document the 'obshashrange' experiment,
  - cache: reduce the warming load in case of reset,
  - cache: add a 'experimental.obshashcache.warm-cache' option to allow
    disabling post transaction cache warming.

--- a/hgext3rd/evolve/__init__.py	Sun May 21 13:55:09 2017 +0200
+++ b/hgext3rd/evolve/__init__.py	Sun May 21 14:20:24 2017 +0200
@@ -44,9 +44,34 @@
     # * abort: abort the push
     auto-publish = ignore
 
+Obsolescence Markers Discovery Experiment
+=========================================
+
+We are experimenting with a new protocol to discover common markers during the
+local and remote repository. This experiment is still at an early stage but is
+already raising better result than the previous version when usable.
+
+Large" repositories (hundreds of thousand) are currently unsupported. Some key
+algorithm has a naive implementation with too agressive caching, creating
+memory consumption issue (this will get fixed).
+
+Medium sized repositories works fine, but be prepared for a noticable initial
+cache filling. for the Mercurial repository, this is around 20 seconds
+
+The following config control the experiment::
+
+  [experimental]
+
+  # enable new discovery protocol
+  # (needed on both client and server)
+  obshashrange = yes
+
+  # avoid cache warming after transaction
+  # (recommended 'off' for developer repositories)
+  # (recommended 'yes' for server (default))
+  obshashrange.warm-cache = no
 """
 
-
 evolutionhelptext = """
 Obsolescence markers make it possible to mark changesets that have been
 deleted or superset in a new version of the changeset.