Rev 50: Merge changes resolving conflicts in file:///home/vila/src/bzr/devnotes/

[Vincent Ladeuil]

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

------------------------------------------------------------
revno: 50
revision-id: v.ladeuil+lp at free.fr-20110512150748-uur855snm98antg2
parent: v.ladeuil+lp at free.fr-20110512142348-q8jf2bt60nh4423n
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: devnotes
timestamp: Thu 2011-05-12 17:07:48 +0200
message:
  Merge changes resolving conflicts
-------------- next part --------------
=== modified file 'configuration.txt'
--- a/configuration.txt	2011-05-12 14:23:48 +0000
+++ b/configuration.txt	2011-05-12 15:07:48 +0000
@@ -504,7 +504,8 @@
 
   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 depending on the OS).
+  /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``)
 
@@ -567,12 +568,17 @@
 
 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)
 
@@ -585,10 +591,11 @@
 ~~~~~~~
 
 * section ID (for a given Store)
+
 * dict of (name, value) pairs defining options
 
 * dict of (name, original_value) pairs used to detect conflicting
-  modifications
+  modifications if the section is mutable.
 
 Stack
 ~~~~~
@@ -662,3 +669,77 @@
 
 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, are 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.
+
+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:
+
+* 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 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).