clonebundles: improve BUNDLESPEC documentation
authorGregory Szorc <gregory.szorc@gmail.com>
Thu, 14 Jan 2016 22:50:55 -0800
changeset 27886 0288e63ea3be
parent 27885 2370c66110cb
child 27887 a30b582b8be4
clonebundles: improve BUNDLESPEC documentation Before the existence of `hg debugbundle --spec`, the process for defining the BUNDLESPEC value in manifests was not very clear and not trivial to automate, especially in the case of stream clone bundles. This patch adds documentation to note the existence of `hg debugbundle --spec`. We drop the reference to stream clone requirements handling because it is now redundant with `hg debugbundle --spec`. While we are here, we further reinforce the importance of defining BUNDLESPEC.
hgext/clonebundles.py
--- a/hgext/clonebundles.py	Thu Jan 14 22:57:55 2016 -0800
+++ b/hgext/clonebundles.py	Thu Jan 14 22:50:55 2016 -0800
@@ -70,11 +70,6 @@
 operators need to be aware that newer versions of Mercurial may produce
 streaming clone bundles incompatible with older Mercurial versions.**
 
-The list of requirements printed by :hg:`debugcreatestreamclonebundle` should
-be specified in the ``requirements`` parameter of the *bundle specification
-string* for the ``BUNDLESPEC`` manifest property described below. e.g.
-``BUNDLESPEC=none-packed1;requirements%3Drevlogv1``.
-
 A server operator is responsible for creating a ``.hg/clonebundles.manifest``
 file containing the list of available bundle files suitable for seeding
 clones. If this file does not exist, the repository will not advertise the
@@ -108,6 +103,10 @@
    "<compression>-<type>" form. See
    mercurial.exchange.parsebundlespec() for more details.
 
+   :hg:`debugbundle --spec` can be used to print the bundle specification
+   string for a bundle file. The output of this command can be used verbatim
+   for the value of ``BUNDLESPEC`` (it is already escaped).
+
    Clients will automatically filter out specifications that are unknown or
    unsupported so they won't attempt to download something that likely won't
    apply.
@@ -117,7 +116,8 @@
    files.
 
    **Use of this key is highly recommended**, as it allows clients to
-   easily skip unsupported bundles.
+   easily skip unsupported bundles. If this key is not defined, an old
+   client may attempt to apply a bundle that it is incapable of reading.
 
 REQUIRESNI
    Whether Server Name Indication (SNI) is required to connect to the URL.