# HG changeset patch
# User Gregory Szorc <gregory.szorc@gmail.com>
# Date 1452840655 28800
# Node ID 0288e63ea3be299c866e37992361da45cdd76c8a
# Parent  2370c66110cbf22207bd3354ee2bfbecabfa6bdd
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.

diff --git a/hgext/clonebundles.py b/hgext/clonebundles.py
--- a/hgext/clonebundles.py
+++ b/hgext/clonebundles.py
@@ -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.