Rev 5507: Start documenting how the configuration files *should* work in file:///home/vila/src/bzr/experimental/config/

[Vincent Ladeuil]

At file:///home/vila/src/bzr/experimental/config/

------------------------------------------------------------
revno: 5507
revision-id: v.ladeuil+lp at free.fr-20101028230315-ab03qwtbes9wc520
parent: pqm at pqm.ubuntu.com-20101018115718-cbuoc2gafnjldngk
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: doc-new-config
timestamp: Fri 2010-10-29 01:03:15 +0200
message:
  Start documenting how the configuration files *should* work
-------------- next part --------------
=== added file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/configuration.txt	2010-10-28 23:03:15 +0000
@@ -0,0 +1,193 @@
+==================
+Configuring Bazaar
+==================
+
+Goal
+====
+
+Not all needs can be addressed by the default values, no matter how well
+they are chosen.
+
+Many parts of ``bzrlib`` depends on options though and the user should be
+able to customize the behavior to suit his needs.
+
+These options can be set from the command-line, in an environment variable
+or recorded in a configuration file.
+
+Naming
+======
+
+The option name space is organized as follow:
+
+* Bazaar itself defines all its constants as ``bzr.option_name``.
+ 
+* plugins can define their own options by prefixing them with the plugin
+  name as ``svn.option_name`` for the ``svn`` plugin.
+
+Using valid python identifiers is recommended but not enforced (but we may
+do so in the future).
+
+Value
+=====
+
+All option values are text. They are provided as Unicode strings to API
+users with some refinements:
+
+* boolean values can be obtained for a set of acceptable strings (yes/no,
+  y/n, on/off, etc),
+
+* a list of strings from a value containing a comma separated list of
+  strings.
+
+Since the configuration files can be edited by the user, ``bzr`` doesn't
+expect it to be validated. Instead, the code using options should 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.
+
+Configuration files
+===================
+
+While of course configurations files can be versioned they are not
+intended to be accessed in sync with the files they refer too (one can
+imagine handling versioned properties this way, this is *not* what the
+bazaar configuration files are targeted at. ``bzr`` will always refer to
+configuration files as they exist on disk when an option is queried or
+set.
+
+The configuration files are generally local to the file system but some of
+them can be accessed remotely (branch.conf, repo.conf).
+
+
+Configuration file syntax
+=========================
+
+The configuration file is mostly an ``ini-file``. It contains ``name =
+value`` lines grouped in sections. Comments are allowed by prefixing them
+with the '#' character.
+
+A section is named by the path it should apply to (more examples below).
+
+Options defined outside of any section act as defaults when no section
+apply. This means that in the most common cases, the user doesn't to
+define any section.
+
+When sections are used, they provide a finer grain of configuration by
+defining set of options that apply to some working trees, branches,
+repositories or part of them.
+
+The subset is defined by the common leading path.
+
+* a full url: used to described options for remote branches and
+  repositories.
+
+* local absolute path: used for working trees, branches or repositories
+  on the local disks.
+
+* relative path: the path is relative to the configuration file and can
+  be used for colocated branches or threads in a loom, i.e any working
+  tree, branch or repository that is located in a place related to the
+  configuration file path. Some configuration files may define this
+  path relationship in specific ways to make them easier to use.
+
+Whatever path is used, the options apply if the branch path starts with
+the path defining the section.
+
+The ConfigOption object
+=======================
+
+* name
+
+* default value. ``None`` is the "default" default value.
+
+* docstring used for the help
+
+* a list of config files where the option can be defined.
+
+
+The ConfigFile object
+=====================
+
+* local or remote
+
+* locking
+
+* option life cycle
+
+* fallback ConfigFile
+
+Getting an option value
+=======================
+
+Depending on the option, there are various places where it can be defined
+and several ways to override these settings when needed.
+
+The following lists all possible places where a configuration option can
+be defined, but some options will make sense in only some of them. The
+first to define a value for an option wins (None is therefore used to
+express that an option is not set).
+
+* command-line
+  ``-Ooption=value``
+
+* environment variable
+
+  ``export BZR_OPTION=value``
+
+* locations.conf
+
+  When an option is set in ``locations.conf`` it overrides any other
+  configuration file. This should be used with care as it allows setting a
+  different value than what is recommended by the project
+
+* tree.conf (Not Implemented Yet)
+
+  The options related to the working tree.
+
+  This includes all options related to commits, ignored files, junk files,
+  etc.
+
+  Note that the sections defined there can use relative paths if some
+  options should apply to a subtree or some specific files only.
+
+* branch.conf
+
+  The options related to the branch.
+
+  Sections can
+
+* repo.conf (Not Implemented Yet)
+
+  The options related to the repository
+
+* project.conf (Not Implemented Yet)
+
+  The options common to all branches and working trees for a project.
+
+* organization.conf (Not Implemented Yet)
+
+  The options common to all branches and working trees for an organization.
+
+* bazaar.conf
+
+  The options the user has selected for the host he is using.
+
+* default (Not Implemented Yet)
+
+  The options defined in the ``bzr`` source code.
+
+Plugins can define additional configuration files as they see fit and
+insert them in this list, see their documentation for details.
+
+
+Compatibility
+=============
+
+* The ``DEFAULT`` section in bazaar.conf should still be recognized but
+  won't be mandatory anymore.
+
+* Other sections in the ``bazaar.conf`` configuration file are still
+  supported but their use is discouraged and we may deprecate them in the
+  future. Plugin authors are encouraged to migrate to the new name space
+  scheme by prefixing their options with their plugin name.
+

=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt	2010-10-13 04:13:48 +0000
+++ b/doc/developers/index.txt	2010-10-28 23:03:15 +0000
@@ -38,6 +38,7 @@
 
    transports
    ui
+   configuration
 
 Releasing and Packaging
 =======================