« back to all changes in this revision
Viewing changes to doc/developers/new-config-rationale.txt
- browse files at revision 6305.5.8
- compare with another revision
- download diff
- download tarball
- view history from revision 6305.5.8
- Committer: Jelmer Vernooij
- Date: 2011-12-09 16:22:02 UTC
- mfrom: (6352.2.2 hpss-no-vfs)
- mto: (6282.6.30 hpss-get-inventories)
- mto: This revision was merged to the branch mainline in revision 6371.
- Revision ID: jelmer@samba.org-20111209162202-29ad2kq34su6etws
Merge hpss-no-vfs branch.
- files added:
- bzrlib/tests/test_vf_search.py
- files modified:
- bzrlib/__init__.py
added
removed
doc/developers/new-config-rationale.txt
1
================================
2
Simplifying Bazaar Configuration
3
================================
4
5
Goal
6
====
7
8
Not all needs can be addressed by the default values used inside bzr and
9
bzrlib, no matter how well they are chosen (and they are ;).
10
11
Options that are rarely used don't deserve a corresponding command line
12
switch in one or several commands.
13
14
Many parts of ``bzrlib`` depends on some constants though and the user
15
should be able to customize the behavior to suit his needs so these
16
constants need to become configuration options or more generally, be easier
17
to set.
18
19
These options can be set from the command-line, acquired from an environment
20
variable or recorded in a configuration file.
21
22
To simplify writing (and reading), this document refers to the old and new
23
config designs:
24
* the old design is using ``Config`` as a base class for all config files,
25
* the new design use ``ConfigStacks`` of ``Section`` from config ``Stores``.
26
27
28
Current issues
29
==============
30
31
* Many parts of ``bzrlib`` declare constants and there is no way for the
32
user to look at or modify them (see http://pad.lv/832061).
33
34
* The old design requires a configuration object to create, modify or delete
35
a configuration option in a given configuration file. ``bzr config``
36
makes it almost transparent for the user. Internally though, not all cases
37
are handled: only BranchConfig implements chained configs, nothing is
38
provided at the repository level and too many plugins define their own
39
section or even their own config file. (config.Stack now provides a way to
40
chain config files, BranchStack properly implements the desired behavior,
41
``bzr config`` uses the new design).
42
43
* ``locations.conf`` defines the options that need to override any setting
44
in ``branch.conf`` for both local and remotes branches (but some remote
45
branch options just ignore ``locations.conf``). Many users want a way to
46
define default values for options that are not defined in ``branch.conf``
47
(and even more users think that ``locations.conf`` provide default values,
48
see also http://pad.lv/843211 and http://pad.lv/832046). This could be
49
approximated today by *not* defining these options in ``branch.conf`` but
50
in ``locations.conf`` instead. This workaround doesn't allow a user to
51
define defaults in ``locations.conf`` and override them in
52
``branch.conf``. (Allowing sections in 'bazaar.conf' (or introducing a new
53
defaults.conf' allowing sections) can now address that. Defining and using
54
a new file is easier as it avoids handling a migration path for
55
bazaar.conf and doesn't require banning the use of sections for special
56
purpose needs (ALIASES and BOOKMARKS for example)).
57
58
* Defining a new option requires adding a new method in the ``Config``
59
object to get access to features like:
60
61
* should the option be inherited by more specific sections, (this was more
62
or less the default in the old design, it is addressed by section
63
matchers in the new one).
64
65
* should the inherited value append the relative path between the
66
section one and the location it applies to (see http://pad.lv/832013),
67
68
* the default value (including calling any python code that may be
69
required to calculate this value)(see http://pad.lv/832064),
70
71
* priority between sections in various config files (this is defined by
72
the section matcher associated with a given config store for stacks,
73
http://pad.lv/832046 is about adding a section matcher with clearer
74
semantics than the one used for locations.conf).
75
76
A related problem is that, in the actual implementation, some
77
configuration options have defined methods, others don't and this is
78
inconsistent. (Using only Stacks addresses that).
79
80
* Access to the 'active' configuration option value from the command line
81
doesn't give access to the specific section. (This is only a concern if
82
the user has no other way to address a specific configuration option
83
including Store and Section when using ``bzr config``) (see http://pad.lv/725234).
84
85
* Rules for configuration options are not clearly defined for remote
86
branches (they may differ between dumb and smart servers the former will
87
use the local ``bazaar.conf`` and ``locations.conf`` files while the later
88
will use (or ignore ?) the remote ones).
89
90
* The features offered by the Bazaar configuration files should be easily
91
accessible to plugin authors either by supporting plugin configuration
92
options in the configuration files or allowing the plugins to define their
93
own configuration files. (Separating Section, Store and Stack starts
94
addressing that, a stack registry should complete the needed means).
95
96
* While the actual configuration files support sections, they are used in
97
mutually exclusive ways that make it impossible to offer the same set of
98
features to all configuration files:
99
100
* ``bazaar.conf`` use arbitrary names for sections. ``DEFAULT`` is used
101
for global options, ``ALIASES`` are used to define command aliases,
102
plugins can define their own sections, some plugins do that
103
(``bzr-bookmarks`` use ``BOOKMARKS`` for example), some other define
104
their own sections (this is addressed with the new design by using only
105
the ``DEFAULT`` section and ignore the others. When needed, one can
106
create a specific stack to get access to a specific section).
107
108
* ``locations.conf`` use globs as section names. This provides an easy
109
way to associate a set of options to a matching working tree or
110
branch, including remote ones.
111
112
* ``branch.conf`` doesn't use any section.
113
114
* There is no easy way to get configuration options for a given repository
115
or an arbitrary path. Working trees and branches are generally organized
116
in hierarchies and being able to share the option definitions is an often
117
required feature. This can also address some needs exhibited by various
118
branch schemes like looms, pipeline, colocated branches and nested
119
trees. Being able to specify options *in* a working tree could also help
120
support conflict resolution options for a given file, directory or
121
subtree (see http://pad.lv/359320).
122
123
* Since sections allow different definitions for the same option, a total
124
order should be defined between sections to select the right definition
125
for a given context (paths or globs for ``locations.conf`` but other
126
schemes can be used, window names for qbzr for example). Allowing globs
127
for section names is harmful in this respect since the order is currently
128
defined as being the lexicographical one. The caveat here is that if the
129
order is always defined for a given set of sections it can change when one
130
or several globs are modified and the user may get surprising and unwanted
131
results in these cases. The lexicographical order is otherwise fine to
132
define what section is more specific than another. (This may not be a
133
problem in real life since longer globs are generally more specific than
134
shorter ones and explicit paths should also be longer than matching
135
globs. That may leave a glob and a path of equal length in a gray area but
136
in practice using ``bzr config`` should give enough feedback to address
137
them. See also http://pad.lv/832046 asking for a less magical section matcher).
138
139
* Internally, configuration files (and their fallbacks, ``bazaar.conf`` and
140
``locations.conf`` for ``branch.conf``) are read every time *one* option is
141
queried. Likewise, setting or deleting a configuration option implies
142
writing the configuration file *immediately* after re-reading the file to
143
avoid racing updates (see http://pad.lv/832042).
144
145
* The current implementation use a mix of transport-based and direct file
146
systems operations (Addressed by Store implementation relying on
147
transports only).
148
149
* While the underlying ``ConfigObj`` implementation provides an
150
interpolation feature, the ``bzrlib`` implementation doesn't provide an
151
easy handling of templates where other configuration options can be
152
interpolated. Instead, ``locations.conf`` (and only it) allows for
153
``appendpath`` and ``norecurse``. (Partially implemented, cross-section
154
and cross-file interpolation still to be implemented, see
155
http://pad.lv/832013 for the remaining parts).
156
157
* Inherited list values can't be modified, a more specific configuration can
158
only redefine the whole list.
159
160
* There is no easy way to define dicts (the most obvious one being to use a
161
dedicated section which is already overloaded). Using embedded sections
162
for this would not be practical either if we keep using a no-name section
163
for default values. In a few known cases, a bencoded dict is stored in a
164
config value, so while this isn't user-friendly, not providing a better
165
alternative shouldn't be a concern. A possible, limited, implementation
166
can be envisioned: limiting the dict to a single level only, with simple
167
names as keys and unicode strings as values. The keys can then be mapped
168
to options prefixed with the dict name.
169
170
171
Proposed implementation
172
=======================
173
174
175
Configuration files definition
176
------------------------------
177
178
While of course configurations files can be versioned they are not intended
179
to be accessed in sync with the files they refer to (one can imagine
180
handling versioned properties this way but this is *not* what the bazaar
181
configuration files are targeted at). ``bzr`` will always refer to
182
configuration files as they exist on disk when an option is queried or set.
183
184
The configuration files are generally local to the file system but some of
185
them can be accessed remotely (``branch.conf``, ``repo.conf``).
186
187
188
Naming
189
------
190
191
Option names are organized into a name space for a given configuration file
192
(or a set of related configuration files). One such set includes
193
``bazaar.conf``, ``locations.conf``, ``branch.conf``, etc. Plugins can
194
define their own sets for their own needs.
195
196
Using a name space is meant to help:
197
198
* avoid collisions between bzr and plugins and between plugins,
199
200
* discover the available options and making them easier to remember,
201
202
* organise the documentation for the option set.
203
204
Using valid python identifiers is recommended but not enforced (but we may
205
do so in the future).
206
207
The option name space is organized by topic:
208
209
* bzrlib options are grouped by topic (``branch``, ``tree``, ``repo``)
210
211
* plugins are encouraged (but not required) to prefix their specific options
212
with their name (``qbzr.`` for qbzr)
213
214
* collisions are detected at registration time so users are protected from
215
incompatibilities between plugins,
216
217
* options that need to be used by several plugins (or shared between ``bzr``
218
core and plugins) should be discussed but these discussions are already
219
happening so the risk of misuse is low enough.
220
221
Value
222
-----
223
224
All option values are text. They are provided as Unicode strings to API
225
users with some refinements:
226
227
* boolean values can be obtained for a set of acceptable strings (yes/no,
228
y/n, on/off, etc), (implemented with the ``from_unicode`` parameter)
229
230
* a list of strings from a value containing a comma separated list of
231
strings.
232
233
Since the configuration files can be edited by the user, ``bzr`` doesn't
234
expect their content to be valid at all times. Instead, the code using
235
options should be ready to handle *invalid* values by warning the user and
236
falling back to a default value.
237
238
Likely, if an option is not defined in any configuration file, the code
239
should fallback to a default value (helpers should be provided by the API to
240
handle common cases: warning the user, getting a particular type of value,
241
returning a default value)(most of that is now handled at Option definition).
242
243
This also ensures compatibility with values provided via environment
244
variables or from the command line (where no validation can be expected
245
either)(done in the new design, some cases missing, see http://pad.lv/832064).
246
247
248
Option expansion
249
----------------
250
251
Some option values can be templates and contain references to other
252
options. This is especially useful to define URLs in sections shared for
253
multiple branches for example. It can also be used to describe commands
254
where some parameters are set by ``bzrlib`` at runtime.
255
256
Since option values are text-only, and to avoid clashing with other option
257
expansion (also known as interpolation) syntaxes, references are enclosed
258
with curly brackets::
259
260
push_location = lp:~{launchpad_username}/bzr/{nick}
261
262
In the example above, ``launchpad_username`` is an already defined
263
configuration option while ``nick`` is the branch nickname and is set when a
264
configuration applies to a given branch.
265
266
The interpolation implementation should accept an additional dict so that
267
``bzrlib`` or plugins can define references that can be expanded without
268
being existing configuration options::
269
270
diff_command={cmd} {cmd_opts} {file_a} {file_b}
271
272
There are two common errors that should be handled when handling interpolation:
273
274
* loops: when a configuration value refers to itself, directly or indirectly,
275
276
* undefined references: when a configuration value refers to an unknown option.
277
278
The loop handling can be modified to allow cross-sections and cross-files
279
interpolation: if an option refers to itself (directly or indirectly) during
280
an expansion, the fallback sections or files can be queried for its value.
281
282
This allows list values to refer to the definition in the less specific
283
configurations::
284
285
bazaar.conf:
286
debug_flags = hpss
287
288
branch.conf for mybranch:
289
debug_flags = {debug_flags}, hpssdetail
290
291
$ bzr -d mybranch config debug_flags
292
hpss, hpssdetail
293
294
Undefined references are detected if they are not defined in any
295
configuration. This will trigger errors while displaying the value. Diagnosing
296
typos should be doable in this case.
297
298
Configuration file syntax
299
-------------------------
300
301
The configuration file is mostly an ``ini-file``. It contains ``name = value``
302
lines grouped in sections. A section starts with a string enclosed in squared
303
brackets ('[section_name]`), this string uniquely identifies the section in
304
the file. Comments are allowed by prefixing them with the '#' character.
305
306
A section is named by the path (or some other unuique identifier) it should
307
apply to (more examples below).
308
309
When sections are used, they provide a finer grain of configuration by
310
defining option sets that apply to some working trees, branches,
311
repositories (or any kind of context) or part of them. The relationship
312
between a given context and the sections it applies to is defined by the
313
config file.
314
315
So far, Bazaar uses a glob in ``locations.conf`` and select the sections
316
that apply to a given url (or a local path).
317
318
The subset is defined by the common leading path or a glob.
319
320
Different kinds of section names can be defined:
321
322
* a full url: used to described options for remote branches and
323
repositories (LocationMatcher supports this).
324
325
* local absolute path: used for working trees, branches or repositories
326
on the local disks (LocationMatcher supports this).
327
328
* relative path: the path is relative to the configuration file and can be
329
used for colocated branches or threads in a loom, i.e any working tree,
330
branch or repository that is located in a place related to the
331
configuration file path. Some configuration files may define this path
332
relationship in specific ways to make them easier to use (i.e. if a config
333
file is somewhere below ``.bzr`` and refers to threads in a loom for
334
example, the relative path would be the thread name, it doesn't have to be
335
an *exact* relative path, as long as its interpretation is unambiguous and
336
clear for the user) (No section matchers support this so far, needs to
337
file a bug)
338
339
Section matching
340
----------------
341
342
Section names define another name space (than the option names one) with an
343
entirely different purpose: in a given configuration file, for a given
344
context, only some sections will be relevant and will be queried in a
345
specific order.
346
347
This matching is specific to each config file and implemented by the
348
SectionMatcher objects.
349
350
Whatever this matching does, the user can observe the results with the ``bzr
351
config`` command which displays the sections in the order they are queried.
352
353
LocationMatcher
354
~~~~~~~~~~~~~~~
355
356
The context here is either:
357
358
* an URL,
359
360
* a local path.
361
362
Note that for both the provided context and the section names, if an URL uses
363
a ``file:///`` form, it is converted to a local path.
364
365
The sections names can use globs for each path component
366
(i.e. ``/dir/*/subdir`` is allowed but ``/dir/\*\*/subdir`` will match
367
``/dir/a/subdir`` but not ``/dir/a/b/subdir``.
368
369
The reason is that the ordering is defined by sorting the section names
370
matching the context on the number of path components followed by the path
371
itself in lexicographical order. This results in most specific sections being
372
queried before the more generic ones.
373
374
PathMatcher
375
~~~~~~~~~~~
376
377
``LocationMatcher`` has some obscure (for unaware users) edge cases and
378
limitations that can be surprising. ``PathMatcher`` aims at addressing these
379
issues by providing simpler rules while still giving full control to the
380
user (http://pad.lv/832046).
381
382
The context here is a local path, absolute or relative. If the path is
383
relative it is interpreted from the file base directory.
384
385
Note that 'base directory' for configuration files in Bazaar directories is
386
really:
387
388
* the home directory for files under ``~/.bazaar``,
389
390
* the ``.bzr`` base directory for files under ``.bzr``.
391
392
The order is the one observed in the file so most generic values are specified
393
first and most specific ones last. As such, the order in the file is the
394
opposite of the one displayed by ``bzr config`` which displays most specific
395
values first. This seems to be the most natural order in both cases.
396
397
A section matches if the section name is a prefix of the context path
398
(relative paths being converted to absolute on the fly).
399
400
The Option object
401
-----------------
402
403
(copied from a recent version of bzr.dev for easier reading, refer to the
404
original for an up to date version)
405
406
The Option object is used to define its properties:
407
408
* name: a name: a valid python identifier (even if it's not used as an
409
identifier in python itself). This is also used to register the option.
410
411
* default: the default value that Stack.get() should return if no
412
value can be found for the option.
413
414
* default_from_env: a list of environment variables. The first variable set
415
will provide a default value overriding 'default' which remains the
416
default value if *no* environment variable is set.
417
418
* help: a doc string describing the option, the first line should be a
419
summary and can be followed by a blank line and a more detailed
420
explanation.
421
422
* from_unicode: a callable accepting a unicode string and returning a
423
suitable value for the option. If the string cannot be coerced it should
424
return None.
425
426
* invalid: the action to be taken when an invalid value is encountered in a
427
store (during a Stack.get()).
428
429
The Section object
430
------------------
431
432
Options are grouped into sections which share some properties with the well
433
known dict objects:
434
435
* the key is the name,
436
* you can get, set and remove an option,
437
* the value is a unicode string.
438
439
MutableSection is needed to set or remove an option, ReadOnlySection should
440
be used otherwise.
441
442
The Store object
443
----------------
444
445
This is an implementation-level object that should rarely be used directly.
446
447
* it can be local or remote
448
449
* locking
450
451
All lock operations should be implemented via transport objects. (True for
452
Store).
453
454
* option life cycle
455
456
Working trees, branches and repositories should define a config attribute
457
following the same life cycle as their lock: the associated config file is
458
read once and written once if needed. This should minimize the file system
459
accesses or the network requests. There is no known racing scenarios for
460
configuration options, changing the existing implementation to this less
461
constrained one shouldn't introduce any. Yet, in order to detect such
462
racing scenarios, we can add a check that the current content of the
463
configuration file is the expected one before writing the new content and
464
emit warnings if differences occur. The checks should be performed for the
465
modified values only. As of today (and in the foreseeable future), the
466
size of the configuration files are small enough to be kept in memory (see
467
http://pad.lv/832042).
468
469
The Stack object
470
-----------------
471
472
This the object that provides access to the needed features:
473
474
* getting an option value,
475
476
* setting an option value,
477
478
* deleting an option value,
479
480
* handling a list of configuration files and for each of them a section
481
matcher providing the sections that should be tried in the given order to
482
find an option.
483
484
* handling a Store and a section where option creation, modification and
485
deletion will occur.
486
487
Depending on the files involved, a working tree, branch or repository object
488
(or more generally a context) should be provided to access the corresponding
489
configuration files. Note that providing a working tree object also
490
implicitly provides the associated branch and repository object so only one
491
of them is required (or none for configuration files specific to the user
492
like ``bazaar.conf``).
493
494
Getting an option value
495
~~~~~~~~~~~~~~~~~~~~~~~
496
497
Depending on the option, there are various places where it can be defined
498
and several ways to override these settings when needed.
499
500
The following lists all possible places where a configuration option can
501
be defined, but some options will make sense in only some of them. The
502
first to define a value for an option wins (None is therefore used to
503
express that an option is not set).
504
505
* command-line
506
``-Ooption=value`` see http://pad.lv/491196.
507
508
* ``~/.bazaar/locations.conf``
509
510
When an option is set in ``locations.conf`` it overrides any other
511
configuration file. This should be used with care as it allows setting a
512
different value than what is recommended by the project
513
514
* ``tree`` (Not Implemented Yet)
515
516
The options related to the working tree.
517
518
This includes all options related to commits, ignored files, junk files,
519
etc.
520
521
Note that the sections defined there can use relative paths if some
522
options should apply to a subtree or some specific files only.
523
524
See http://pad.lv/430538 and http://pad.lv/654998.
525
526
* ``branch`` located in ``.bzr/branch/branch.conf``
527
528
The options related to the branch.
529
530
Sections can be defined for colocated branches or loom threads.
531
532
* ``repository`` (Not Implemented Yet)
533
534
The options related to the repository.
535
536
Using an option to describe whether or not a repository is shared could
537
help address http://pad.lv/342119 but this will probably requires a format
538
bump).
539
540
* ``project`` (Not Implemented Yet)
541
542
The options common to all branches and working trees for a project.
543
544
* ``organization`` (Not Implemented Yet)
545
546
The options common to all branches and working trees for an organization.
547
548
See http://pad.lv/419854.
549
550
* ``system`` (Not Implemented Yet but see http://pad.lv/419854 and
551
https://code.launchpad.net/~thomir/bzr/add-global-config/+merge/69592)
552
553
The options common to all users of a system (may be /etc/bzr/defaults
554
or /usr/local/etc/bzr/defaults or
555
/Library/Preferences/com.canonical.defaults or c:\windows\bazaar.conf
556
(someone fix this one please ;) depending on the OS).
557
558
* ``bazaar.conf``
559
560
The options the user has selected for the host he is using.
561
562
Sections can be defined for both remote and local branches to define
563
default values (i.e. the most common use of ``locations.conf`` today).
564
565
* default (implemented by the OptionRegistry)
566
567
The options defined in the ``bzr`` source code.
568
569
This will be implemented via the Option objects.
570
571
Plugins can define additional configuration files as they see fit and
572
insert them in this list, see their documentation for details.
573
574
Compatibility
575
=============
576
577
There are ways to keep the same files while ensuring compatibility via various
578
tricks but there are cases where using new files to replace the old ones is
579
definitely easier:
580
581
* no need to ensure that the new files are correctly handled by old bzr
582
versions,
583
584
* making it clear for users that there is a switch and let them migrate at
585
their own pace.
586
587
The known cases so far are described below.
588
589
Obvious at this point:
590
591
* Branch provides ``get_config`` for the old design and ``get_config_stack``
592
for the new design so that both designs are supported. Once the store
593
sharing is implemented, we may want to use an attribute for the stack and
594
deprecate both ``get_config`` and ``get_config_stack``.
595
596
* Sections names in ``bazaar.conf`` are arbitrary (except ``DEFAULT``) so
597
it's easier to leave the file untouched and let plugin authors and users
598
migrate away (or not) from them. For ``bzr`` itself, that means
599
``DEFAULT`` is the only section used for most of the options and provides
600
user defaults. ``ALIASES`` requires a specific stack but only the ``bzr
601
alias`` command cares about that.
602
603
* Option policies should be deprecated:
604
605
* The ``norecurse`` policy is useless, all options are recursive by
606
default. If specific values are needed for specific paths, they can just
607
be defined as such (in the appropriate sections or files).
608
609
* The ``appendpath`` policy should be implemented via interpolation and a
610
``relpath`` option provided by the configuration framework
611
(http://pad.lv/832013).
612
613
* Section order in ``locations.conf`` has issues which make a migration to a
614
different way to organize the sections (hence the file content) far easier
615
with a new file.
616
617
* ``locations.conf`` is really for overrides but many users have been using it
618
to provide defaults. There is no way to know if the whole content has been
619
used for defaults or overrides or a mix of both. So there is no way to
620
migrate this automatically.
621
622
Unclear at this point:
623
624
* [BOOKMARKS] section can be replaced by ``bookmarks.xxx`` options (the
625
bookmarks plugins already uses ``bookmarks_xxx`` in branch.conf since no
626
sections were supported there). The easiest here is probably to just merge
627
the plugin into core and use the appropriate option names consistently. A
628
``config:`` directory service may even be better as any option can be used
629
as a bookmark. This allows things like::
630
631
[/whatever/path]
632
my_push = lp:<launchpad.login>/xxx/{nick}
633
web_site=ftp://example.com/
634
635
bzr push config:web_site
636
637
Which means we completely replace the plugin and don't need to care about
638
migrating the section.
639
640
* [ALIASES] section can be replaced by corresponding bzr.alias.xxx
641
options. This could be automated by creating the corresponding options ?
642
643
* I don't know about other sections, feedback welcome. Plugin authors are
644
encouraged to migrate to the new name space scheme by prefixing their
645
options with their plugin name.
646
647
Notes
648
=====
649
650
These are random notes about concepts, ideas or issues not implemented yet.
651
652
Developer facing concepts
653
-------------------------
654
655
Option
656
~~~~~~
657
658
* list of allowed Config IDs (this allows a list of possible config files in
659
bazaar.conf only option and use it while bootstrapping the config
660
creations).
661
662
* blacklist of config IDs (some options *can't* be stored (modified) by the
663
user)
664
665
An alternative is to just let the devs decide which stack they use for a
666
given option, ``stacked_on_location`` for example is said to relate to the
667
branch only and changing it or setting it in a different config file may not
668
be appropriate. This may not be a good example as there is also the
669
``default_stack_on`` option which can be set only in ``control.conf``
670
though...
671
672
Stack
673
~~~~~
674
675
* a lazy cache for the option values (should be reset on modifications as
676
interpolations will make it tricky to update incrementally) (see FIXME in
677
config.py Stack.get()))
678
679
* ensures that the Stores involved generate as less IOs as possible (see
680
http://pad.lv/832042)
681
682
* ensures that the transaction is the object life time (i.e. modifications
683
will be taken into account *iff* they are committed explicitly).
684
685
StackRegistry
686
~~~~~~~~~~~~~
687
688
* ensures that a config ID is a unique identifier
689
* register Stacks
690
691
Store
692
~~~~~
693
694
* ensures that the transaction is the object life time (i.e. modifications
695
will be taken into account *iff* they are committed explicitly).
696
697
Examples
698
--------
699
700
store examples:
701
~~~~~~~~~~~~~~~
702
703
* ConfigObj (bazaar.conf)
704
705
* DB (<scheme>://bazaar.launchpad.net/bazaar.conf)
706
707
708
Why and when locking config files matter
709
----------------------------------------
710
711
This is relevant for http://pad.lv/832042.
712
713
``bzr`` behavior, as well as the objects it acts upon, is configured via a
714
set of so-called configuration files.
715
716
These files allow to define working trees, branches and repositories, their
717
relationships and how ``bzr`` should handle them.
718
719
The default behavior of ``bzr`` is aimed at making this configuration as
720
transparent as possible by keeping track of how these objects are created
721
and modified when they are used. In short, they are useless until you want
722
to change the default behavior in some specific context.
723
724
We mostly **read** config options. Therefore all we care about is to
725
guarantee that:
726
727
* we get a valid config file at all times when reading,
728
729
* we always leave a valid config file when writing (via the rename dance)
730
731
From there, conceptually, all operations can clearly define whether or not
732
they need to modify a config file and do so only when they succeed. All
733
modifications occurring during such an operation are delayed until the very
734
end of the operation.
735
736
Now, we want to minimize the overlapping times where one bzr operation has
737
changed a value and another concurrent operation is unaware of this
738
modification.
739
740
These overlapping periods are *as of today* rare.
741
742
The only known case, http://pad.lv/525571 has been fixed in bzr-2.1.3. The
743
bug there was triggered when two processes tried to write the same config
744
file at the same time leaving an invalid file in the end.
745
746
Such a period can be recognized and detected though: when changing an option
747
value, if the preserved original value is different in the config file,
748
someone else modified it and the operation can be invalid because it relied
749
on the original value.
750
751
For the sake of the example, if an option value represent a global unique ID
752
via a simple counter (very bad idea), if two operations try to increment it,
753
both will use the same value that won't be unique anymore. Checking the
754
value present in the file when trying to save the updated value with
755
identify such a collision.
756
757
An assumption is floating around: it should be enough to report when an
758
operation is modifying an already modified option and observe that no-one
759
reports such occurrences.
760
761
Note that this assumption is made in a context where *no* known scenarios
762
exist in the bzr code base not in any plugin (for a best effort value of
763
'any', feedback highly welcome, bug reports even ;)
764
765
With this in mind, we can change the definition of config options, stores
766
and stacks to ensure that:
767
768
* a config file is read only once when in read access,
769
770
* a config file is read only once and written only once when in write
771
access, adding the check mentioned above will require *one* additional
772
read.
773
774
A reader can then safely assume that reading a config file gives it a valid
775
(and coherent) definition of the configuration when the operation
776
starts. All the operation has to do is to declare which config files may be
777
modified by an operation (whether or not we can be liberal on this 'may be'
778
is yet to be defined).
Loggerhead is a web-based interface for Breezy
Version: 2.0.1