[PATCH] help: document requirements
Augie Fackler
raf at durin42.com
Mon Mar 14 14:26:46 EDT 2016
On Sat, Mar 12, 2016 at 07:16:03PM -0800, Gregory Szorc wrote:
> # 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
Queued this, please send any windows installer business as a follow-up. Thanks!
>
> 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>
>
>
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at mercurial-scm.org
> https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
More information about the Mercurial-devel
mailing list