[PATCH STABLE] internal-doc: document the config register mechanism

[Boris Feld]

# HG changeset patch
# User Boris Feld <boris.feld at octobus.net>
# Date 1509121147 -7200
#      Fri Oct 27 18:19:07 2017 +0200
# Branch stable
# Node ID 8d4d315b568e046140e717d7f0deb3a74a36e9f8
# Parent  f7e4d6c20095d67857c912bd44bb45073ced6f2f
# EXP-Topic doc-config
# Available At https://bitbucket.org/octobus/mercurial-devel/
#              hg pull https://bitbucket.org/octobus/mercurial-devel/ -r 8d4d315b568e
internal-doc: document the config register mechanism

This explains the various usage and feature of the config register introduced
in Mercurial 4.3 and 4.4.

diff --git a/contrib/wix/help.wxs b/contrib/wix/help.wxs
--- a/contrib/wix/help.wxs
+++ b/contrib/wix/help.wxs
@@ -42,6 +42,7 @@
             <File Id="internals.bundles.txt"      Name="bundles.txt" KeyPath="yes" />
             <File Id="internals.censor.txt"       Name="censor.txt" />
             <File Id="internals.changegroups.txt" Name="changegroups.txt" />
+            <File Id="internals.config.txt"       Name="config.txt" />
             <File Id="internals.requirements.txt" Name="requirements.txt" />
             <File Id="internals.revlogs.txt"      Name="revlogs.txt" />
             <File Id="internals.wireprotocol.txt" Name="wireprotocol.txt" />
diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -202,6 +202,8 @@ internalstable = sorted([
      loaddoc('censor', subdir='internals')),
     (['changegroups'], _('Changegroups'),
      loaddoc('changegroups', subdir='internals')),
+    (['config'], _('Config Register'),
+     loaddoc('config', subdir='internals')),
     (['requirements'], _('Repository Requirements'),
      loaddoc('requirements', subdir='internals')),
     (['revlogs'], _('Revision Logs'),
diff --git a/mercurial/help/internals/config.txt b/mercurial/help/internals/config.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/help/internals/config.txt
@@ -0,0 +1,107 @@
+All config options used within Mercurial should be registered.
+
+Config Option in Core
+=====================
+
+Config options used by Mercurial core are registered in the
+``mercurial.configitems`` module.
+
+Simple entry
+------------
+
+A registration entry typically looks like::
+
+    coreconfigitem('section', 'option',
+        default=MyDefaultValue,
+    )
+
+Once registered, Mercurial will know that ``section.option`` is a legitimate
+config option and that ``MyDefaultValue`` should be used if no other values are
+defined in configuration files.
+
+Complex default value
+---------------------
+
+If the default provided is a callable, it is called to retrieve the default
+value when accessing the config option. This is useful for default value that
+are mutable like the empty list::
+
+    coreconfigitem('pager', 'ignore',
+        default=list,
+    )
+
+In addition, there are cases where the default is not fixed, but computed from
+other properties. In this case, use the ``dynamicdefault`` object as value for
+the ``default`` parameters. A default value is then explicitly required when
+reading the option::
+
+    # registration
+    coreconfigitem('web', 'name',
+        default=dynamicdefault,
+    )
+
+    # usage
+    ui.config('web', 'name', dirnam)
+
+Free form options
+-----------------
+
+Some config sections use free form options (e.g. ``paths``). You can register
+them using the ``generic`` parameters::
+
+    coreconfigitem('paths', '.*',
+        default=None,
+        generic=True,
+    )
+
+When ``generic=True`` is set, the option name is matched as a regular expression
+(rooted to string start). It can be used to select specific sub parameters::
+
+    coreconfigitem('merge-tools', br'.*\.args$',
+        default="$local $base $other",
+        generic=True,
+        priority=-1,
+    )
+
+The ``priority`` parameter control the order used to match the generic pattern
+(lower first).
+
+Config Option in Extensions
+===========================
+
+General case
+------------
+
+Extensions should register config items through the ``registrar`` API (also used
+for commands and others)::
+
+    configtable = {}
+    configitem = registrar.configitem(configtable)
+
+    configitem('blackbox', 'dirty',
+        default=False,
+    )
+
+The ``dynamicdefault`` object is then available as ``configitem.dynamicdefault``.
+
+Supporting older version
+------------------------
+
+The register was introduced in Mercurial 4.3, the ``generic`` parameter was
+introduced in 4.4.  Starting with Mercurial 4.4 all core options were registered
+and developer warnings are emitted when accessing unregistered option.
+
+Extensions supporting version older than Mercurial-4.3 cannot rely on the
+default value registered. The simplest way to register option while still
+supporting older version is to use ``dynamicdefault`` for option requiring a
+default value. The existing code passing an explicit default can then stay in
+use until compatibility to Mercurial 4.2 is dropped.
+
+As reminder here are the default value for each config types:
+- config:      None
+- configbool:  False
+- configbytes: 0
+- configdate:  None
+- configint:   None
+- configlist:  []
+- configpatch: None
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -980,6 +980,7 @@ internals topic renders index of availab
        bundles       Bundles
        censor        Censor
        changegroups  Changegroups
+       config        Config Register
        requirements  Repository Requirements
        revlogs       Revision Logs
        wireprotocol  Wire Protocol
@@ -3054,6 +3055,13 @@ Sub-topic indexes rendered properly
   Changegroups
   </td></tr>
   <tr><td>
+  <a href="/help/internals.config">
+  config
+  </a>
+  </td><td>
+  Config Register
+  </td></tr>
+  <tr><td>
   <a href="/help/internals.requirements">
   requirements
   </a>