Rev 42: More design ideas. in file:///home/vila/src/bzr/devnotes/

Wed Mar 30 13:12:58 UTC 2011

At file:///home/vila/src/bzr/devnotes/

------------------------------------------------------------
revno: 42
revision-id: v.ladeuil+lp at free.fr-20110330131258-pxjbgpw2g1o4057s
parent: v.ladeuil+lp at free.fr-20110330130919-f0kyj114u34wpnam
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: devnotes
timestamp: Wed 2011-03-30 15:12:58 +0200
message:
  More design ideas.
-------------- next part --------------
=== modified file 'configuration.txt'

--- a/configuration.txt	2011-03-30 13:09:19 +0000
+++ b/configuration.txt	2011-03-30 13:12:58 +0000
@@ -54,14 +54,16 @@
   inconsistent.
 
 * Access to the 'active' configuration option value from the command line
-  doesn't give access to specific section.
+  doesn't give access to the specific section.
 
 * Rules for configuration options are not clearly defined for remote
-  branches (they may differ between dumb and smart servers).
+  branches (they may differ between dumb and smart servers the former will
+  use the local ``bazaar.conf`` and ``locations.conf`` files while the later
+  will use the remote ones).
 
 * The features offered by the Bazaar configuration files should be easily
   accessible to plugin authors either by supporting plugin configuration
-  options in the configuration files or allowing plugin to define their
+  options in the configuration files or allowing the plugins to define their
   own configuration files.
 
 * While the actual configuration files support sections, they are used in
@@ -90,18 +92,19 @@
   subtree.
 
 * Since sections allow different definitions for the same option, a total
-  order should be defined between sections to select the right definition
-  for a given path. Allowing globs for section names is harmful in this
-  respect since the order is currently defined as being the lexicographical
-  one. The caveat here is that if the order is always defined for a given
-  set of sections it can change when one or several globs are modified and
-  the user may get surprising and unwanted results in these cases. The
-  lexicographical order is otherwise fine to define what section is more
-  specific than another. (This may not be a problem in real life since
-  longer globs are generally more specific than shorter ones and explicit
-  paths should also be longer than matching globs. That may leave a glob and
-  a path of equal length in a gray area but in practice using ``bzr config``
-  should give enough feedback to address them).
+  order should be defined between sections to select the right definition for
+  a given context (paths or globs for ``locations.conf`` but other schemes can
+  be used, window names for qbzr for exmaple). Allowing globs for section
+  names is harmful in this respect since the order is currently defined as
+  being the lexicographical one. The caveat here is that if the order is
+  always defined for a given set of sections it can change when one or several
+  globs are modified and the user may get surprising and unwanted results in
+  these cases. The lexicographical order is otherwise fine to define what
+  section is more specific than another. (This may not be a problem in real
+  life since longer globs are generally more specific than shorter ones and
+  explicit paths should also be longer than matching globs. That may leave a
+  glob and a path of equal length in a gray area but in practice using ``bzr
+  config`` should give enough feedback to address them).
 
 * Internally, configuration files (and their fallbacks, ``bazaar.conf`` and
   ``locations.conf`` for ``branch.conf``) are read every time *one* option is
@@ -176,7 +179,7 @@
 be ready to handle *invalid* values by warning the user and fallback to a
 default value. Likely, if an option is not defined in any configuration
 file, the code should fallback to a default value (helpers should be
-provided by the API to handle common cases, warning the user, getting a
+provided by the API to handle common cases: warning the user, getting a
 particular type of value, returning a default value).
 
 This also ensures compatibility with values provided via environment
@@ -217,7 +220,7 @@
 Another implementation could be envisioned though: when a loop is
 encountered, we can fall back to the less specific configurations. This
 allows list values to refer to the definition in the less specific
-configurations allowing::
+configurations::
 
   bazaar.conf:
     debug_flags = hpss
@@ -431,3 +434,118 @@
 
   * The ``appendpath`` policy should be implemented via interpolation and a
     ``relpath`` option provided by the configuration framework.
+
+Notes
+=====
+
+User facing concepts
+--------------------
+
+An option can be:
+* read (from a stack of 
+* created
+* modified
+* deleted
+
+A config file can define:
+
+* one or several sections. A unique section identifier is required if more
+  than one section is defined.
+* each section can contain one or several option definitions
+
+
+Developer facing concepts
+-------------------------
+
+Option
+~~~~~~
+* name
+* help
+* default value (optional)
+* list of allowed Config IDs (this allows a list of possible
+  config files in bazaar.conf only option and use it while
+  bootstrapping the config creations)
+* blacklist of config IDs (some options *can't* be stored (modified) by the
+  user)
+
+OptionRegistry
+~~~~~~~~~~~~~~
+* ensures that an option ID is a unique name
+
+Section
+~~~~~~~
+* section ID (for a given Store)
+* dict of (name, value) pairs defining options
+
+* dict of (name, original_value) pairs used to detect conflicting
+  modifications
+
+Stack
+~~~~~
+* A list of read-only Section/Stack objects
+
+* A single mutable Section object and its associated Store (defined only if
+  the stack support modification)
+
+* a lazy cache for the option values (should be reset on modifications as
+  interpolations will make it tricky to update incrementally).
+
+* ensures that the Stores involved generate as less IOs as possible
+
+* ensures that the transaction is the object life time (i.e. modifications
+  will be taken into account *iff* they are comitted explicitly).
+
+ConfigRegistry
+~~~~~~~~~~~~~~
+
+* ensures that a config ID is a unique identifier
+* register Stacks
+
+Store
+~~~~~
+
+* url
+* config ID
+* can serialize/deserialize a dict of Sections
+* can cache reads and writes
+* ensures that the transaction is the object life time (i.e. modifications
+  will be taken into account *iff* they are comitted explicitly).
+* can be read-only or read/write at build time
+* can provide an ordered list of Section for a given context
+
+Examples
+--------
+
+section examples
+~~~~~~~~~~~~~~~~
+
+* os.environ
+* options provided on the command-line
+* actual branch.conf
+* any section in a Store
+* a dict for section or store specific options ('relpath', 'nick', etc)
+
+store examples:
+~~~~~~~~~~~~~~~
+
+* ConfigObj (bazaar.conf)
+
+* DB (<scheme>://bazaar.launchpad.net/bazaar.conf)
+
+stack examples
+~~~~~~~~~~~~~~
+
+The actual GlobalConfig will become a stack with:
+* options from the command-line
+* os.environ
+* the default section from bazaar.conf
+
+The actual BranchConfig will become a stack with:
+* options from the command-line
+* os.environ
+* a stack for the matching sections in locations.conf
+* a stack for the matching sections in branch.conf
+* a stack for the matching sections in bazaar.conf
+
+The modifications will be made to the section in branch.conf specified when
+building the branch config object (generally the default section).

