[PATCH 5 of 5] clonebundles: improve BUNDLESPEC documentation

[Gregory Szorc]

# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1452840655 28800
#      Thu Jan 14 22:50:55 2016 -0800
# Node ID dbc369ba3ac8b681a24d654420902442e399c71f
# Parent  7a8ffc23529223ac2de256a66e1b1eb14b7491f1
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
@@ -65,21 +65,16 @@ Bundle files can be generated with the :
 to produce and consume (read: fast). However, they are larger than
 traditional bundle formats and require that clients support the exact set
 of repository data store formats in use by the repository that created them.
 Typically, a newer server can serve data that is compatible with older clients.
 However, *streaming clone bundles* don't have this guarantee. **Server
 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
 existence of clone bundles when clients connect.
 
 The manifest file contains a newline (\n) delimited list of entries.
 
 Each line in this file defines an available bundle. Lines have the format:
@@ -103,26 +98,31 @@ BUNDLESPEC
 
    These are string values that are accepted by the "--type" argument of
    :hg:`bundle`.
 
    The values are parsed in strict mode, which means they must be of the
    "<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.
 
    The actual value doesn't impact client behavior beyond filtering:
    clients will still sniff the bundle type from the header of downloaded
    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.
    SNI allows servers to use multiple certificates on the same IP. It is
    somewhat common in CDNs and other hosting providers. Older Python
    versions do not support SNI. Defining this attribute enables clients
    with older Python versions to filter this entry without experiencing
    an opaque SSL failure at connection time.