[PATCH] help: document requirements
Gregory Szorc
gregory.szorc at gmail.com
Sun Mar 13 16:08:20 EDT 2016
On Sun, Mar 13, 2016 at 7:56 AM, FUJIWARA Katsunori <foozy at lares.dti.ne.jp>
wrote:
> At Sat, 12 Mar 2016 19:16:03 -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
> >
> > We didn't have unified documentation of the various repository
> > requirements. This patch changes that.
>
> Does not adding new help file into "help/internals" require changing
> GUID "help.internals.guid" in guids.wxi ? (please ignore if I
> misunderstand about Windows installer)
>
I'm not sure. But the history of the wix files seems to indicate that it
does.
>
> BTW, a tool (as a part of check-commit ?) to detect leaking of
> required changes for wix files at adding/removing file is needed,
> isn't it ? I've seen "newly added help can't be displayed" issue
> sometime.
>
>
> > 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
>
> ----------------------------------------------------------------------
> [FUJIWARA Katsunori] foozy at lares.dti.ne.jp
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.mercurial-scm.org/pipermail/mercurial-devel/attachments/20160313/6451783f/attachment.html>
More information about the Mercurial-devel
mailing list