diff --git a/hgext/share.py b/hgext/share.py
--- a/hgext/share.py
+++ b/hgext/share.py
@@ -63,6 +63,30 @@
 
     For resharing existing shares, make sure your working directory is clean
     and there are no untracked files, delete that share and create a new share.
+
+    Shares can be automatically upgraded and downgraded to use share-safe
+    mechanism. Following config options control the behavior:
+
+    ``experimental.sharesafe-warn-outdated-shares`` (default: True)
+        Shows a warning if the current share is outdated and can be upgraded to
+        use share-safe functionality.
+
+    ``experimental.sharesafe-auto-upgrade-shares`` (default: False)
+        Automatically upgrades shares if the share source supports share-safe
+        functionality.
+        If the upgrade fails, a warning is shown and the command which is
+        running is continued.
+
+    ``experimental.sharesafe-auto-upgrade-fail-error`` (default: False)
+        If auto upgrade of share fails, error out the process and don't continue
+        the command which is running.
+
+    ``experimental.sharesafe-auto-downgrade-shares`` (default: False)
+        Automatically downgrade shares if it was using share-safe functionality
+        but the share source stopped using it.
+        If the downgrade process fails, we error out because current share
+        does not have complete set of requirements and shared source no longer
+        supports share-safe mechanism.
 '''
 
 from __future__ import absolute_import