Rev 62: Update to better match actual progress. in file:///home/vila/src/bzr/devnotes/
Vincent Ladeuil
v.ladeuil+lp at free.fr
Tue Sep 20 16:00:03 UTC 2011
At file:///home/vila/src/bzr/devnotes/
------------------------------------------------------------
revno: 62
revision-id: v.ladeuil+lp at free.fr-20110920160003-ys1cexygjrxv55ab
parent: v.ladeuil+lp at free.fr-20110914092853-73r4u6l8cjcf3xyf
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: devnotes
timestamp: Tue 2011-09-20 18:00:03 +0200
message:
Update to better match actual progress.
-------------- next part --------------
=== modified file 'configuration.txt'
--- a/configuration.txt 2011-09-14 09:28:53 +0000
+++ b/configuration.txt 2011-09-20 16:00:03 +0000
@@ -8,54 +8,69 @@
Not all needs can be addressed by the default values used inside bzr and
bzrlib, no matter how well they are chosen (and they are ;).
+Options that are rarely used don't deserve a corresponding command line
+switch in one or several commands.
+
Many parts of ``bzrlib`` depends on some constants though and the user
should be able to customize the behavior to suit his needs so these
-constants need to become configuration options.
-
-These options can be set from the command-line, in an environment variable
-or recorded in a configuration file.
+constants need to become configuration options or more generally, be easier
+to set.
+
+These options can be set from the command-line, acquired from an environment
+variable or recorded in a configuration file.
+
+To simplify writing (and reading) this document refers to the old and new
+config designs:
+* the old design is using Config as a base class for all config files,
+* the new design use stacks of config files.
Current issues
==============
* Many parts of ``bzrlib`` declare constants and there is no way for the
- user to look at or modify them (see bug #832061).
+ user to look at or modify them (see http://pad.lv/832061).
-* The current API requires a configuration object to create, modify or
- delete a configuration option in a given configuration file. ``bzr
- config`` makes it almost transparent for the user. Internally though, not
- all cases are handled: only BranchConfig implements chained configs,
- nothing is provided at the repository level and too many plugins define
- their own section or even their own config file. (config.Stack can now
- provide a way to chain config files).
+* The ld design requires a configuration object to create, modify or delete
+ a configuration option in a given configuration file. ``bzr config``
+ makes it almost transparent for the user. Internally though, not all cases
+ are handled: only BranchConfig implements chained configs, nothing is
+ provided at the repository level and too many plugins define their own
+ section or even their own config file. (config.Stack now provides a way to
+ chain config files).
* ``locations.conf`` defines the options that needs to override any setting
in ``branch.conf`` for both local and remotes branches (but some remote
branch options just ignore ``locations.conf``). Many users want a way to
- define default values for options that are not defined in
- ``branch.conf``. This could be approximated today by *not* defining these
- options in ``branch.conf`` but in ``locations.conf`` instead. This
- workaround doesn't allow a user to define defaults in ``locations.conf``
- and override them in ``branch.conf``. (Allowing sections in 'bazaar.conf'
- (or introducing a new 'user.conf' allowing sections) can now address
- that.)
+ define default values for options that are not defined in ``branch.conf``
+ (and even more users think that ``locations.conf`` provide default values,
+ see also bug #843211 and bug #832046). This could be approximated today by
+ *not* defining these options in ``branch.conf`` but in ``locations.conf``
+ instead. This workaround doesn't allow a user to define defaults in
+ ``locations.conf`` and override them in ``branch.conf``. (Allowing
+ sections in 'bazaar.conf' (or introducing a new defaults.conf' allowing
+ sections) can now address that.)
* Defining a new option requires adding a new method in the ``Config``
object to get access to features like:
- * should the option be inherited by more specific sections,
+ * should the option be inherited by more specific sections, (this was more
+ or less the default in the old design, it is addressed by section
+ matchers in the new one).
* should the inherited value append the relative path between the
- section one and the location it applies to.
+ section one and the location it applies to (see bug #832013),
* the default value (including calling any python code that may be
required to calculate this value)(see bug #832064),
- * priority between sections in various config files
+ * priority between sections in various config files (this is defined by
+ the section matcher associated with a given config store for stacks, bug
+ #832046 is about adding a section matcher with clearer semantics than
+ the one used for locations.conf).
A related problem is that, in the actual implementation, some
configuration options have defined methods, others don't and this is
- inconsistent. (Using only Stacks will address that).
+ inconsistent. (Using only Stacks address that).
* Access to the 'active' configuration option value from the command line
doesn't give access to the specific section. (This is only a concern if
@@ -71,7 +86,7 @@
accessible to plugin authors either by supporting plugin configuration
options in the configuration files or allowing the plugins to define their
own configuration files. (Separating Section, Store and Stack starts
- addressing that).
+ addressing that, a stack registry should complete the needed means).
* While the actual configuration files support sections, they are used in
mutually exclusive ways that make it impossible to offer the same set of
@@ -81,7 +96,9 @@
for global options, ``ALIASES`` are used to define command aliases,
plugins can define their own sections, some plugins do that
(``bzr-bookmarks`` use ``BOOKMARKS`` for example), some other define
- their own sections.
+ their own sections (this is addressed with the new design by using only
+ the ``DEFAULT`` section and ignore the others. When needed, one can
+ create a specific stack to get access to a specific section).
* ``locations.conf`` use globs as section names. This provides an easy
way to associate a set of options to a matching working tree or
@@ -99,19 +116,20 @@
subtree (see bug #359320).
* 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 context (paths or globs for ``locations.conf`` but other schemes can
- be used, window names for qbzr for example). 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 example). 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. See also bug #832046 asking for a less magical section matcher).
* Internally, configuration files (and their fallbacks, ``bazaar.conf`` and
``locations.conf`` for ``branch.conf``) are read every time *one* option is
@@ -128,7 +146,8 @@
easy handling of templates where other configuration options can be
interpolated. Instead, ``locations.conf`` (and only it) allows for
``appendpath`` and ``norecurse``. (Partially implemented, cross-section
- and cross-file interpolation still to be implemented).
+ and cross-file interpolation still to be implemented, see bug #832013 for
+ the remaining parts).
* Inherited list values can't be modified, a more specific configuration can
only redefine the whole list.
@@ -173,19 +192,19 @@
* avoid collisions between bzr and plugins and between plugins,
-* discovering the available options and making them easier to remember,
+* discover the available options and making them easier to remember,
-* organizing the documentation for the option set.
+* organise the documentation for the option set.
Using valid python identifiers is recommended but not enforced (but we may
do so in the future).
-The option name space can be organized based on topic or package
-(see below for more details).
-
-The topic based name space seems to provide the best compromise:
-
-* option names are shorter,
+The option name space is organized by topic:
+
+* bzrlib options are grouped by topic (``branch``, ``tree``, ``repo``)
+
+* plugins are encouraged (but not required) to prefix their specific options
+ with their name (``qbzr.`` for qbzr)
* collisions are detected at registration time so users are protected from
incompatibilities between plugins,
@@ -194,35 +213,6 @@
core and plugins) should be discussed but these discussions are already
happening so the risk of misuse is low enough.
-
-topic based
-~~~~~~~~~~~
-
-* bzrlib options are grouped by topic (``branch``, ``tree``, ``repo``)
-
-* plugins are encouraged (but not required) to prefix their specific options
- with their name (``qbzr.`` for qbzr)
-
-
-package based
-~~~~~~~~~~~~~
-
-* Bazaar itself defines all its constants as ``bzr.option_name`` or
- ``bzr.topic.option_name``, in short, the ``bzr.`` prefix is reserved
- for bzr core/bzrlib itself,
-
-* plugins can define their own options by prefixing them with the plugin
- name as ``svn.option_name`` for the ``svn`` plugin.
-
-Strictly speaking matching option names to their corresponding python name
-space has been considered user hostile (as well as dev hostile) since
-``bzrlib.`` and ``bzrlib.plugins.<plugin_name>`` are too long for no added
-value.
-
-Forcing prefixes allows templates (or other special purposes options) to use
-shorter option names without risking collisions.
-
-
Value
-----
@@ -230,7 +220,7 @@
users with some refinements:
* boolean values can be obtained for a set of acceptable strings (yes/no,
- y/n, on/off, etc),
+ y/n, on/off, etc), (implemented with the ``from_unicode`` parameter)
* a list of strings from a value containing a comma separated list of
strings.
@@ -243,11 +233,11 @@
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 particular type of value,
-returning a default value).
+returning a default value)(most of that is now handled at Option definition).
This also ensures compatibility with values provided via environment
variables or from the command line (where no validation can be expected
-either).
+either)(done in the new design, some cases missing, see bug #832064).
Option expansion
@@ -308,11 +298,8 @@
brackets ('[section_name]`), this string uniquely identifies the section in
the file. 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
-applies. This means that in the most common cases, the user doesn't need to
-define any section.
+A section is named by the path (or some other unuique identifier) it should
+apply to (more examples below).
When sections are used, they provide a finer grain of configuration by
defining option sets that apply to some working trees, branches,
@@ -325,11 +312,13 @@
The subset is defined by the common leading path or a glob.
+Different kinds of section names can be defined:
+
* a full url: used to described options for remote branches and
- repositories.
+ repositories (LocationMatcher supports this).
* local absolute path: used for working trees, branches or repositories
- on the local disks.
+ on the local disks (LocationMatcher supports this).
* 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,
@@ -339,18 +328,16 @@
file is somewhere below ``.bzr`` and refers to threads in a loom for
example, the relative path would be the thread name, it doesn't have to be
an *exact* relative path, as long as its interpretation is unambiguous and
- clear for the user).
-
-Whatever path is used, the options apply if the branch path starts with
-the path defining the section (or if the glob matches).
+ clear for the user) (No section matchers support this so far, needs to
+ file a bug)
Section matching
----------------
Section names define another name space (than the option names one) with an
entirely different purpose: in a given configuration file, for a given
-context, only some sections will be relevant and will be queried in a specific
-order.
+context, only some sections will be relevant and will be queried in a
+specific order.
This matching is specific to each config file and implemented by the
SectionMatcher objects.
@@ -358,9 +345,6 @@
Whatever this matching does, the user can observe the results with the ``bzr
config`` command which displays the sections in the order they are queried.
-The common rule to all matchers is that the no-name section always matches so
-the most generic values can be specified there.
-
LocationMatcher
~~~~~~~~~~~~~~~
@@ -387,7 +371,8 @@
``LocationMatcher`` has some obscure (for unaware users) edge cases and
limitations that can be surprising. ``PathMatcher`` aims at addressing these
-issues by providing simpler rules while still giving full control to the user.
+issues by providing simpler rules while still giving full control to the
+user (bug #832046).
The context here is a local path, absolute or relative. If the path is
relative it is interpreted from the file base directory.
@@ -410,19 +395,44 @@
The Option object
-----------------
-In addition to the configuration files, one internal configuration dict can
-contain definitions for some configuration options. This will allow a finer
-grained definition of the default values and the on-line help.
-
-The ConfigOption object will define:
-
-* name
-
-* default value. ``None`` is the "default" default value.
-
-* doc-string used for the help
-
-* a list of config files where the option can be defined.
+(copied from a recent version of bzr.dev for easier reading, refer to the
+original for an up to date version)
+
+The Option object is used to define its properties:
+
+* name: a name: a valid python identifier (even if it's not used as an
+ identifier in python itself). This is also used to register the option.
+
+* default: the default value that Stack.get() should return if no
+ value can be found for the option.
+
+* default_from_env: a list of environment variables. The first variable set
+ will provide a default value overriding 'default' which remains the
+ default value if *no* environment variable is set.
+
+* help: a doc string describing the option, the first line should be a
+ summary and can be followed by a blank line and a more detailed
+ explanation.
+
+* from_unicode: a callable accepting a unicode string and returning a
+ suitable value for the option. If the string cannot be coerced it should
+ return None.
+
+* invalid: the action to be taken when an invalid value is encountered in a
+ store (during a Stack.get()).
+
+The Section object
+------------------
+
+Options are grouped into sections which share some properties with the well
+known dict objects:
+
+* the key is the name,
+* you can get, set and remove an option,
+* the value is a unicode string.
+
+MutableSection is needed to set or remove an option, ReadOnlySection should
+be used otherwise.
The Store object
----------------
@@ -443,12 +453,13 @@
read once and written once if needed. This should minimize the file system
accesses or the network requests. There is no known racing scenarios for
configuration options, changing the existing implementation to this less
- constrained one shouldn't introduce any. Yet, in order to detect such racing
- scenarios, we can add a check that the current content of the configuration
- file is the expected one before writing the new content and emit warnings if
- differences occur. The checks should be performed for the modified values
- only. As of today (and in the foreseeable future), the size of the
- configuration files are small enough to be kept in memory.
+ constrained one shouldn't introduce any. Yet, in order to detect such
+ racing scenarios, we can add a check that the current content of the
+ configuration file is the expected one before writing the new content and
+ emit warnings if differences occur. The checks should be performed for the
+ modified values only. As of today (and in the foreseeable future), the
+ size of the configuration files are small enough to be kept in memory (see
+ bug #832042).
The Stack object
-----------------
@@ -461,18 +472,19 @@
* deleting an option value,
-* handling a list of configuration sections that should be tried in the given
- order to find an option.
+* handling a list of configuration files and for each of them a section
+ matcher providing the sections that should be tried in the given order to
+ find an option.
-* handling a Store and a section name where option creation, modification and
+* handling a Store and a section where option creation, modification and
deletion will occur.
Depending on the files involved, a working tree, branch or repository object
-should be provided to access the corresponding configuration files. Note
-that providing a working tree object also implicitly provides the
-associated branch and repository object so only one of them is required (or
-none for configuration files specific to the user like bazaar.conf and
-locations.conf).
+(or more generally a context) should be provided to access the corresponding
+configuration files. Note that providing a working tree object also
+implicitly provides the associated branch and repository object so only one
+of them is required (or none for configuration files specific to the user
+like ``bazaar.conf``).
Getting an option value
~~~~~~~~~~~~~~~~~~~~~~~
@@ -488,22 +500,13 @@
* command-line (Not Implemented Yet)
``-Ooption=value`` see bug #491196.
-* environment variable
-
- ``export BZR_OPTION=value``
-
- Some environment variables doesn't have a corresponding configuration
- option (BZR_PLUGIN_PATH) and most configuration options doesn't have a
- corresponding environment variable.
-
-* ``~/.bazaar/locations.conf`` (will be obsoleted by ``overrides`` in
- ``~/.bazaar/overrides``)
+* ``~/.bazaar/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`` (Not Implemented Yet will be located in ``.bzr/checkout/tree.conf`` )
+* ``tree`` (Not Implemented Yet)
The options related to the working tree.
@@ -521,39 +524,39 @@
Sections can be defined for colocated branches or loom threads.
-* ``repository`` (Not Implemented Yet will be located in
- ``.bzr/repository/repository.conf``)
+* ``repository`` (Not Implemented Yet)
The options related to the repository.
Using an option to describe whether or not a repository is shared could
help address bug #342119 but this will probably requires a format bump).
-* ``project`` (Not Implemented Yet location to be defined)
+* ``project`` (Not Implemented Yet)
The options common to all branches and working trees for a project.
-* ``organization`` (Not Implemented Yet location to be defined)
+* ``organization`` (Not Implemented Yet)
The options common to all branches and working trees for an organization.
See bug #419854.
-* ``system`` (Not Implemented Yet will be located in an OS specific location)
+* ``system`` (Not Implemented Yet but see bug #419854 and
+ https://code.launchpad.net/~thomir/bzr/add-global-config/+merge/69592)
The options common to all users of a system (may be /etc/bzr/defaults
or /usr/local/etc/bzr/defaults or
/Library/Preferences/com.canonical.defaults or c:\windows\bazaar.conf
(someone fix this one please ;) depending on the OS).
-* ``bazaar.conf`` (will be obsoleted by ``defaults`` located in ``~/.bazaar``)
+* ``bazaar.conf``
The options the user has selected for the host he is using.
Sections can be defined for both remote and local branches to define
default values (i.e. the most common use of ``locations.conf`` today).
-* default (Not Implemented Yet will be located in ``~/,bazaar/defaults``)
+* default (implemented by the OptionRegistry)
The options defined in the ``bzr`` source code.
@@ -579,13 +582,12 @@
Obvious at this point:
-* [DEFAULT] section is replaced by a no-name section (it may otherwise
- conflict with a a section named after a 'DEFAULT' *path*). This is trival to
- automate by copying the section content into the ``defaults`` no-name
- section. On the other hand, we may want to rename the options too and trying
- to obey both option names in the same file is harder than accepting one name
- is the new file while accepting the old name if the old file is still
- present.
+* Sections names in ``bazaar.conf`` are arbitrary (except ``DEFAULT``) so
+ it's easier to leave the file untouched and let plugin authors and users
+ migrate away (or not) from them. For ``bzr`` itself, that means
+ ``DEFAULT`` is the only section used for most of the options and provides
+ user defaults. ``ALIASES`` requires a specific stack but only the ``bzr
+ alias`` command cares about that.
* Option policies should be deprecated:
@@ -594,7 +596,8 @@
be defined as such (in the appropriate sections or files).
* The ``appendpath`` policy should be implemented via interpolation and a
- ``relpath`` option provided by the configuration framework.
+ ``relpath`` option provided by the configuration framework (bug
+ #832013).
* Section order in ``locations.conf`` has issues which make a migration to a
different way to organize the sections (hence the file content) far easier
@@ -609,10 +612,10 @@
* [BOOKMARKS] section can be replaced by ``bookmarks.xxx`` options (the
bookmarks plugins already uses ``bookmarks_xxx`` in branch.conf since no
- sections were supported there). This could be automated by creating the
- corresponding options ? An alternative would be to just implement a
- 'config:' directory service so any option can be used as a bookmark. This
- allows things like::
+ sections were supported there). The easiest here is probably to just merge
+ the plugin into core and use the appropriate option names consistently. A
+ ``config:`` directory service may even be better as any option can be used
+ as a bookmark. This allows things like::
[/whatever/path]
my_push = lp:<launchpad.login>/xxx/{nick}
@@ -633,22 +636,7 @@
Notes
=====
-User facing concepts
---------------------
-
-An option can be:
-
-* read
-* 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
-
+These are random notes about concepts, ideas or issues not implemented yet.
Developer facing concepts
-------------------------
@@ -656,52 +644,35 @@
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)
+* 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 if the section is mutable.
+An alternative is to just let the devs decide which stack they use for a
+given option, ``stacked_on_location`` for example is said to relate to the
+branch only and changing it or setting it in a different config file may not
+be appropriate. This may not be a good example as there is also the
+``default_stack_on`` option which can be set only in ``control.conf``
+though...
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).
+ interpolations will make it tricky to update incrementally) (see FIXME in
+ config.py Stack.get()))
-* ensures that the Stores involved generate as less IOs as possible
+* ensures that the Stores involved generate as less IOs as possible (see bug
+ #832042)
* ensures that the transaction is the object life time (i.e. modifications
will be taken into account *iff* they are committed explicitly).
-ConfigRegistry
-~~~~~~~~~~~~~~
+StackRegistry
+~~~~~~~~~~~~~
* ensures that a config ID is a unique identifier
* register Stacks
@@ -709,27 +680,12 @@
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 committed 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:
~~~~~~~~~~~~~~~
@@ -737,96 +693,75 @@
* 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).
Why and when locking config files matter
----------------------------------------
-bzr behavior, as well as the objects it acts upon, is configured via a set
-of so-called configuration files.
-
-These files allow to define working trees, branches and
-repositories, their relationships and how bzr should handle them.
-
-The default behavior of bzr is aimed at making this configuration
-as transparent as possible by keeping track of how these objects
-are created and modified when they are used. In short, they are
-useless until you want to change the default behavior in some
-specific context.
-
-We mostly **read** config options. Therefore all we care about is
-to guarantee that:
+This is relevant for bug #832042.
+
+``bzr`` behavior, as well as the objects it acts upon, is configured via a
+set of so-called configuration files.
+
+These files allow to define working trees, branches and repositories, their
+relationships and how ``bzr`` should handle them.
+
+The default behavior of ``bzr`` is aimed at making this configuration as
+transparent as possible by keeping track of how these objects are created
+and modified when they are used. In short, they are useless until you want
+to change the default behavior in some specific context.
+
+We mostly **read** config options. Therefore all we care about is to
+guarantee that:
* we get a valid config file at all times when reading,
* we always leave a valid config file when writing (via the rename dance)
-From there, conceptually, all operations can clearly define
-whether or not they need to modify a config file and do so only
-when they succeed. All modifications occurring during such an
-operation are delayed until the very end of the operation.
+From there, conceptually, all operations can clearly define whether or not
+they need to modify a config file and do so only when they succeed. All
+modifications occurring during such an operation are delayed until the very
+end of the operation.
-Now, we want to minimize the overlapping times where one bzr
-operation has changed a value and another concurrent operation is
-unaware of this modification.
+Now, we want to minimize the overlapping times where one bzr operation has
+changed a value and another concurrent operation is unaware of this
+modification.
These overlapping periods are *as of today* rare.
-The only known case, bug #525571 has been fixed in bzr-2.1.3. The
-bug there was triggered when two processes tried to write the
-same config file at the same time leaving an invalid file in the
-end.
-
-Such a period can be recognized and detected though: when
-changing an option value, if the preserved original value is
-different in the config file, someone else modified it and the
-operation can be invalid because it relied on the original value.
-
-For the sake of the example, if an option value represent a
-global unique ID via a simple counter (very bad idea), if two
-operations try to increment it, both will use the same value that
-won't be unique anymore. Checking the value present in the file
-when trying to save the updated value with identify such a
-collision.
-
-An assumption is floating around: it should be enough to report
-when an operation is modifying an already modified option and
-observe that no-one reports such occurrences.
-
-Note that this assumption is made in a context where *no* known
-scenarios exist in the bzr code base not in any plugin (for a
-best effort value of 'any', feedback highly welcome, bug reports
-even ;)
-
-With this in mind, we can change the definition of config
-options, stores and stacks to ensure that:
+The only known case, bug #525571 has been fixed in bzr-2.1.3. The bug there
+was triggered when two processes tried to write the same config file at the
+same time leaving an invalid file in the end.
+
+Such a period can be recognized and detected though: when changing an option
+value, if the preserved original value is different in the config file,
+someone else modified it and the operation can be invalid because it relied
+on the original value.
+
+For the sake of the example, if an option value represent a global unique ID
+via a simple counter (very bad idea), if two operations try to increment it,
+both will use the same value that won't be unique anymore. Checking the
+value present in the file when trying to save the updated value with
+identify such a collision.
+
+An assumption is floating around: it should be enough to report when an
+operation is modifying an already modified option and observe that no-one
+reports such occurrences.
+
+Note that this assumption is made in a context where *no* known scenarios
+exist in the bzr code base not in any plugin (for a best effort value of
+'any', feedback highly welcome, bug reports even ;)
+
+With this in mind, we can change the definition of config options, stores
+and stacks to ensure that:
* a config file is read only once when in read access,
-* a config file is read only once and written only once when in
- write access, adding the check mentioned above will require
- *one* additional read.
+* a config file is read only once and written only once when in write
+ access, adding the check mentioned above will require *one* additional
+ read.
-A reader can then safely assume that reading a config file gives
-it a valid (and coherent) definition of the configuration when
-the operation starts. All the operation has to do is to declare
-which config files may be modified by an operation (whether or
-not we can be liberal on this 'may be' is yet to be defined).
+A reader can then safely assume that reading a config file gives it a valid
+(and coherent) definition of the configuration when the operation
+starts. All the operation has to do is to declare which config files may be
+modified by an operation (whether or not we can be liberal on this 'may be'
+is yet to be defined).
More information about the bazaar-commits
mailing list