[PATCH] help: document requirements

Sun Mar 13 03:16:03 UTC 2016

# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1457837467 28800
#      Sat Mar 12 18:51:07 2016 -0800
# Node ID e40a0987f6f96703a2c2ead417757a36e790780e
# Parent  70c2f8a982766b512e9d7f41f2d93fdb92f5481f
help: document requirements

We didn't have unified documentation of the various repository
requirements. This patch changes that.

diff --git a/contrib/wix/help.wxs b/contrib/wix/help.wxs
--- a/contrib/wix/help.wxs
+++ b/contrib/wix/help.wxs
@@ -35,16 +35,17 @@
           <File Name="templates.txt" />
           <File Name="urls.txt" />
         </Component>
 
         <Directory Id="help.internaldir" Name="internals">
           <Component Id="help.internals" Guid="$(var.help.internals.guid)" Win64='$(var.IsX64)'>
             <File Id="internals.bundles.txt"      Name="bundles.txt" KeyPath="yes" />
             <File Id="internals.changegroups.txt" Name="changegroups.txt" />
+            <File Id="internals.requirements.txt" Name="requirements.txt" />
             <File Id="internals.revlogs.txt"      Name="revlogs.txt" />
           </Component>
         </Directory>
 
       </Directory>
     </DirectoryRef>
   </Fragment>
 
diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -183,16 +183,18 @@ def loaddoc(topic, subdir=None):
 
     return loader
 
 internalstable = sorted([
     (['bundles'], _('container for exchange of repository data'),
      loaddoc('bundles', subdir='internals')),
     (['changegroups'], _('representation of revlog data'),
      loaddoc('changegroups', subdir='internals')),
+    (['requirements'], _('repository requirements'),
+     loaddoc('requirements', subdir='internals')),
     (['revlogs'], _('revision storage mechanism'),
      loaddoc('revlogs', subdir='internals')),
 ])
 
 def internalshelp(ui):
     """Generate the index for the "internals" topic."""
     lines = []
     for names, header, doc in internalstable:
diff --git a/mercurial/help/internals/requirements.txt b/mercurial/help/internals/requirements.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/help/internals/requirements.txt
@@ -0,0 +1,110 @@
+Requirements
+============
+
+Repositories contain a file (``.hg/requires``) containing a list of
+features/capabilities that are *required* for clients to interface
+with the repository. This file has been present in Mercurial since
+version 0.9.2 (released December 2006).
+
+One of the first things clients do when opening a repository is read
+``.hg/requires`` and verify that all listed requirements are supported,
+aborting if not. Requirements are therefore a strong mechanism to
+prevent incompatible clients from reading from unknown repository
+formats or even corrupting them by writing to them.
+
+Extensions may add requirements. When they do this, clients not running
+an extension will be unable to read from repositories.
+
+The following sections describe the requirements defined by the
+Mercurial core distribution.
+
+revlogv1
+--------
+
+When present, revlogs are version 1 (RevlogNG). RevlogNG was introduced
+in 2006. The ``revlogv1`` requirement has been enabled by default
+since the ``requires`` file was introduced in Mercurial 0.9.2.
+
+If this requirement is not present, version 0 revlogs are assumed.
+
+store
+-----
+
+The *store* repository layout should be used.
+
+This requirement has been enabled by default since the ``requires`` file
+was introduced in Mercurial 0.9.2.
+
+fncache
+-------
+
+The *fncache* repository layout should be used.
+
+The *fncache* layout hash encodes filenames with long paths and
+encodes reserved filenames.
+
+This requirement is enabled by default when the *store* requirement is
+enabled (which is the default behavior). It was introduced in Mercurial
+1.1 (released December 2008).
+
+shared
+------
+
+Denotes that the store for a repository is shared from another location
+(defined by the ``.hg/sharedpath`` file).
+
+This requirement is set when a repository is created via :hg:`share`.
+
+The requirement was added in Mercurial 1.3 (released July 2009).
+
+dotencode
+---------
+
+The *dotencode* repository layout should be used.
+
+The *dotencode* layout encodes the first period or space in filenames
+to prevent issues on OS X and Windows.
+
+This requirement is enabled by default when the *store* requirement
+is enabled (which is the default behavior). It was introduced in
+Mercurial 1.7 (released November 2010).
+
+parentdelta
+-----------
+
+Denotes a revlog delta encoding format that was experimental and
+replaced by *generaldelta*. It should not be seen in the wild because
+it was never enabled by default.
+
+This requirement was added in Mercurial 1.7 and removed in Mercurial
+1.9.
+
+generaldelta
+------------
+
+Revlogs should be created with the *generaldelta* flag enabled. The
+generaldelta flag will cause deltas to be encoded against a parent
+revision instead of the previous revision in the revlog.
+
+Support for this requirement was added in Mercurial 1.9 (released
+July 2011). The requirement was disabled on new repositories by
+default until Mercurial 3.7 (released February 2016).
+
+manifestv2
+----------
+
+Denotes that version 2 of manifests are being used.
+
+Support for this requirement was added in Mercurial 3.4 (released
+May 2015). The requirement is currently experimental and is disabled
+by default.
+
+treemanifest
+------------
+
+Denotes that tree manifests are being used. Tree manifests are
+one manifest per directory (as opposed to a single flat manifest).
+
+Support for this requirement was added in Mercurial 3.4 (released
+August 2015). The requirement is currently experimental and is
+disabled by default.
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -870,16 +870,17 @@ Test list of internal help commands
 internals topic renders index of available sub-topics
 
   $ hg help internals
   Technical implementation topics
   """""""""""""""""""""""""""""""
   
        bundles       container for exchange of repository data
        changegroups  representation of revlog data
+       requirements  repository requirements
        revlogs       revision storage mechanism
 
 sub-topics can be accessed
 
   $ hg help internals.changegroups
       Changegroups
       ============
   
@@ -2722,16 +2723,23 @@ Sub-topic indexes rendered properly
   <tr><td>
   <a href="/help/internals.changegroups">
   changegroups
   </a>
   </td><td>
   representation of revlog data
   </td></tr>
   <tr><td>
+  <a href="/help/internals.requirements">
+  requirements
+  </a>
+  </td><td>
+  repository requirements
+  </td></tr>
+  <tr><td>
   <a href="/help/internals.revlogs">
   revlogs
   </a>
   </td><td>
   revision storage mechanism
   </td></tr>
   
   
