~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/new-config-rationale.txt

  • Committer: Richard Wilbur
  • Date: 2016-02-04 19:07:28 UTC
  • mto: This revision was merged to the branch mainline in revision 6618.
  • Revision ID: richard.wilbur@gmail.com-20160204190728-p0zvfii6zase0fw7
Update COPYING.txt from the original http://www.gnu.org/licenses/gpl-2.0.txt  (Only differences were in whitespace.)  Thanks to Petr Stodulka for pointing out the discrepancy.

Show diffs side-by-side

added added

removed removed

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