/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/configuration.txt

  • Committer: Jelmer Vernooij
  • Date: 2020-04-05 19:11:34 UTC
  • mto: (7490.7.16 work)
  • mto: This revision was merged to the branch mainline in revision 7501.
  • Revision ID: jelmer@jelmer.uk-20200405191134-0aebh8ikiwygxma5
Populate the .gitignore file.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/configuration.txt
 
1
Configuring Breezy
 
2
==================
 
3
 
 
4
.. contents::
 
5
   :depth: 2
 
6
 
 
7
As a Breezy developer there are a few things you need to know about
 
8
configuration:
 
9
 
 
10
* how to add a new option,
 
11
 
 
12
* how add a new stack,
 
13
 
 
14
* how add a new store.
 
15
 
 
16
The first sections in this document summarize the steps needed when adding a
 
17
new configuration item, the rest of the document gives more internal details
 
18
on how this is implemented.
 
19
 
 
20
Get an option value
 
21
-------------------
 
22
 
 
23
Options values are obtained with ``stack.get(option_name)`` where ``stack``
 
24
is one of the daughter classes of ``config.Stack``, see their docstrings for
 
25
a description of which sections are used from which stores.
 
26
 
 
27
The value returned is of the type declared for that ``Option`` and if
 
28
nothing is specifically declared you will get the default for that option.
 
29
 
 
30
Add a new option
 
31
----------------
 
32
 
 
33
You add a new ``Option`` to the ``option_registry``, either inside
 
34
``breezy/config.py`` or during initialization of your plugin (use
 
35
``register_lazy`` in this case). New plugins should have systematic
 
36
hierarchical names so that related values are grouped together::
 
37
 
 
38
  option_registry.register(
 
39
      Option('dirstate.fdatasync', default=True,
 
40
            from_unicode=bool_from_store,
 
41
            help="Flush dirstate changes onto physical disk? ...."))
 
42
 
 
43
You then need to decide which stack is appropriate to implement the Option
 
44
policy:
 
45
 
 
46
* which config files (aka ``Store``) needs to be queried, which sections are
 
47
  relevant and in what order,
 
48
 
 
49
* which section will receive the modifications (if relevant).
 
50
 
 
51
The docstrings for the existing stacks cover most of the known use cases.
 
52
 
 
53
Modify an option value or delete an option
 
54
------------------------------------------
 
55
 
 
56
Just reading an option is what is needed most of the time, modifying option
 
57
values or removing options is usually something that is not automated but
 
58
left to the user (with ``brz config``).
 
59
 
 
60
Nevertheless, if you need to save a modified option value, use
 
61
``.set(option_name, value)`` and ``.remove(option_name)`` to delete the
 
62
option. Both methods are provided by the ``Stack`` object.
 
63
 
 
64
But before doing that, you must be sure that the stack you're using have a
 
65
writable section (this is true for ``GlobalStack`` which uses the
 
66
``DEFAULT`` section in ``breezy.conf`` and for ``BranchStack``which uses the
 
67
no-name section in ``branch.conf``).
 
68
 
 
69
Old and new configuration code
 
70
------------------------------
 
71
 
 
72
There is (as of late 2011) some older and some newer configuration code. The
 
73
old code has specific methods for various checks or uses classes like
 
74
``GlobalConfig``.  Don't add to to it; try to remove it.
 
75
 
 
76
If you encounter an option using the old code you may want to migrate
 
77
it. This generally involves:
 
78
 
 
79
* registering the option,
 
80
 
 
81
* replace the old config by a stack:
 
82
 
 
83
  * ``GlobalConfig`` became ``GlobalStack``,
 
84
 
 
85
  * ``LocationConfig`` became ``LocationStack``,
 
86
 
 
87
  * ``BranchConfig`` became ``BranchStack`` (or in this case,
 
88
    ``get_config()`` became ``get_config_stack()``.
 
89
 
 
90
* replace the custom accessor calls with ``conf.get(option_name)``.
 
91
 
 
92
The new config code provides some help for commonly encountered use cases
 
93
that can allow further simplifications like:
 
94
 
 
95
* providing a default value when the option is not defined in any way by the
 
96
  user,
 
97
 
 
98
* convert the unicode string provided by the user into a suitable
 
99
  representation (integer, list, etc).
 
100
 
 
101
If you start migrating a given option to the config stacks, don't stop
 
102
mid-way, all its uses should be covered (tests included). There are some
 
103
edge cases where updates via one API will be not be seen by the other API
 
104
(see http://pad.lv/948339 and http://pad.lv/948344 for details). Roughly,
 
105
the old API always trigger an IO while the new one cache values to avoid
 
106
them. This works fine as long as a given option is handled via a single API.
 
107
 
 
108
Adding a new stack
 
109
------------------
 
110
 
 
111
Stacks capture the various places an option can be declared by the user with
 
112
associated levels of generality and query them in the appropriate order
 
113
returning the first definition found. For example, the
 
114
``append_revisions_only`` option may be declared for all branches of a user
 
115
in ``breezy.conf``, or for a hierarchy of branches in ``locations.conf`` or
 
116
in a single branch in ``branch.conf``.
 
117
 
 
118
Defining a new stack means you need a new way to expose these levels to the
 
119
user that is not covered by the existing stacks.
 
120
 
 
121
This is achieved by declaring:
 
122
 
 
123
* which stores can provide a value for the option,
 
124
 
 
125
* which sections apply to the stack instance, some filtering for a given
 
126
  context can be defined,
 
127
 
 
128
* which (store, section) should receive the modifications.
 
129
 
 
130
Mapping different sections to different stacks is a powerful way to organize
 
131
the options and provide various levels of configuration to the user. This is
 
132
achieved with ``Store`` and ``SectionMatcher`` objects.
 
133
 
 
134
 
 
135
Adding a new store
 
136
------------------
 
137
 
 
138
The following stores are used by ``brz`` in ways that illustrate various
 
139
uses of sections.
 
140
 
 
141
breezy.conf
 
142
===========
 
143
 
 
144
``brz`` itself defines two sections here:
 
145
 
 
146
* ``DEFAULT`` where global options are defined,
 
147
 
 
148
* ``ALIASES`` where command aliases are defined. This section is *not*
 
149
  available via ``GlobalStack``, instead, the ``brz alias`` command uses it
 
150
  for its own purposes.
 
151
 
 
152
Plugins can define either additional options in the ``DEFAULT`` section or
 
153
new sections for their own needs (this is not especially encouraged
 
154
though). The ``bzr-bookmarks`` plugin defines a ``BOOKMARKS`` section there
 
155
for example.
 
156
 
 
157
location.conf
 
158
=============
 
159
 
 
160
``brz`` defines sections corresponding to URLs there and includes the
 
161
relevant sections in ``LocationStack`` and ``BranchStack``. No no-name
 
162
section is recognized in this file.
 
163
 
 
164
branch.conf
 
165
===========
 
166
 
 
167
This file defines the option for a given branch and uses only the no-name
 
168
section.
 
169
 
 
170
Option
 
171
------
 
172
 
 
173
The Option object is used to define its properties:
 
174
 
 
175
* name: a name: a valid python identifier (even if it's not used as an
 
176
  identifier in python itself). This is also used to register the option.
 
177
 
 
178
* from_unicode: a callable accepting a unicode string and returning a
 
179
  suitable value for the option. If the string cannot be coerced it should
 
180
  return None.
 
181
 
 
182
* override_from_env: a list of environment variables. The first variable set
 
183
  will be used as the option value overriding any other definition of the
 
184
  option.
 
185
 
 
186
* default: the default value that Stack.get() should return if no value can
 
187
  be found for the option. This can also be a callable as long as it returns
 
188
  a unicode string.
 
189
 
 
190
* default_from_env: a list of environment variables. The first variable set
 
191
  will provide a default value overriding 'default' which remains the
 
192
  default value if *no* environment variable is set.
 
193
 
 
194
* help: a doc string describing the option, the first line should be a
 
195
  summary and can be followed by a blank line and a more detailed
 
196
  explanation. This will be displayed to the user with::
 
197
 
 
198
    brz help <option name>
 
199
 
 
200
* invalid: the action to be taken when an invalid value is encountered in a
 
201
  store (during a Stack.get()).
 
202
 
 
203
The value of an option is a unicode string or ``None`` if it's not
 
204
defined. By using ``from_unicode`` you can turn this string into a more
 
205
appropriate representation.
 
206
 
 
207
If you need a list value, you should use ``ListOption`` instead.
 
208
 
 
209
For options that take their values from a ``Registry`` object,
 
210
``RegistryOption`` can be used. This will automatically take care of
 
211
looking up the specified values in the dictionary and documenting the
 
212
possible values in help.
 
213
 
 
214
Sections
 
215
--------
 
216
 
 
217
Options are grouped into sections which share some properties with the well
 
218
known dict objects:
 
219
 
 
220
* the key is the name,
 
221
* you can get, set and remove an option,
 
222
* the value is a unicode string.
 
223
 
 
224
MutableSection is needed to set or remove an option, ReadOnlySection should
 
225
be used otherwise.
 
226
 
 
227
 
 
228
Stores
 
229
------
 
230
 
 
231
Options can be persistent in which case they are saved into Stores.
 
232
 
 
233
``config.Store`` defines the abstract interface that all stores should
 
234
implement.
 
235
 
 
236
This object doesn't provide direct access to the options, it only provides
 
237
access to Sections. This is deliberate to ensure that sections can be
 
238
properly shared by reusing the same underlying objects. Accessing options
 
239
should be done via the ``Section`` objects.
 
240
 
 
241
A ``Store`` can contain one or more sections, each section is uniquely
 
242
identified by a unicode string.
 
243
 
 
244
``config.IniFileStore`` is an implementation that use ``ConfigObj``.
 
245
 
 
246
Depending on the object it is associated with (or not) a ``Store`` also needs
 
247
to implement a locking mechanism. ``LockableIniFileStore`` implements such a
 
248
mechanism for ``IniFileStore`` based stores.
 
249
 
 
250
Classes are provided for the usual Breezy configuration files and could be
 
251
used as examples to define new ones if needed. The associated tests provides a
 
252
basis for new classes which only need to register themselves in the right
 
253
places to inherit from the existing basic tests and add their own specific
 
254
ones.
 
255
 
 
256
A ``Store`` defines how option values are stored, this includes:
 
257
 
 
258
* defining the sections where the options are grouped,
 
259
 
 
260
* defining how the values are quoted/unquoted for storage purposes. Stacks
 
261
  use the unquoted values internally (default value handling and option
 
262
  expansion are simpler this way) and ``brz config`` quote them when they
 
263
  need to be displayed.
 
264
 
 
265
 
 
266
Filtering sections
 
267
------------------
 
268
 
 
269
For some contexts, only some sections from a given store will apply. The
 
270
``SectionMatcher`` objects are used to define which sections in a store
 
271
apply to a given context.
 
272
 
 
273
The main constraint here is that a ``SectionMatcher`` should delay the loading
 
274
of the associated store as long as possible. The constructor should collect
 
275
all data needed for the selection and uses it while processing the sections in
 
276
``get_sections``.
 
277
 
 
278
Only ``ReadOnlySection`` objects are manipulated here but a
 
279
``SectionMatcher`` can return dedicated ``Section`` objects to provide
 
280
additional context (the ``LocationSection`` add an ``extra_path`` attribute
 
281
to implement the section local options for example). If no sections match,
 
282
an empty list is returned.
 
283
 
 
284
Options local to a section can be defined for special purposes and be
 
285
handled by ``Section.get()``. One such option is ``relpath`` which is
 
286
defined in ``LocationSection`` as an alternative to the ``appendpath``
 
287
policy.
 
288
 
 
289
For ``appendpath``, the ``LocationSection`` will carry ``extra_path`` as the
 
290
relative path between the section name and the location used. ``relpath``
 
291
will be available as a ``Section`` local option with the same
 
292
value. ``basename`` will carry the location base name and be available as a
 
293
local option with the same name. Note that such options can only be expanded
 
294
inside the section that defines them.
 
295
 
 
296
Specific section matchers can be implemented by overriding ``get_sections``
 
297
or just ``match``.
 
298
 
 
299
``breezy`` provides:
 
300
 
 
301
* ``NameMatcher(store, unique_id)``: To select a single section matching
 
302
  ``unique_id``.
 
303
 
 
304
* ``LocationMatcher(store, location)``: To select all sections that match
 
305
  ``location`` sorted by decreasing number of path components.
 
306
 
 
307
* ``StartingPathMatcher(store, location)``: To select all sections that
 
308
  match ``location`` in the order they appear in the ``store``.
 
309
 
 
310
Stacks
 
311
------
 
312
 
 
313
An option can take different values depending on the context it is
 
314
used. This can involve configuration files, options from the command line,
 
315
default values in breezy and then some.
 
316
 
 
317
Such a context is implemented by creating a list of ``Section`` stacked upon
 
318
each other. A ``Stack`` can then be asked for an option value and returns the
 
319
first definition found.
 
320
 
 
321
This provides a great flexibility to decide priorities between sections when
 
322
the stack is defined without to worry about them in the code itself.
 
323
 
 
324
A stack also defines a mutable section (which can be None) to handle
 
325
modifications.
 
326
 
 
327
Many sections (or even stores) are aimed at providing default values for an
 
328
option but these sections shouldn't be modified lightly as modifying an option
 
329
used for different contexts will indeed be seen by all these contexts.
 
330
 
 
331
Default values in configuration files are defined by users. Developers
 
332
shouldn't have to modify them, as such, no mechanism nor heuristics are used
 
333
to find which section (or sections) should be modified.
 
334
 
 
335
A ``Stack`` defines a mutable section when there is no ambiguity.  If there
 
336
is one, then the *user* should be able to decide and in this case a new
 
337
``Stack`` can be created cheaply.
 
338
 
 
339
Different stacks can be created for different purposes, the existing
 
340
``GlobalStack``, ``LocationStack`` and ``BranchStack`` can be used as basis
 
341
or examples. These classes are the only ones that should be used in code,
 
342
``Stores`` can be used to build them but shouldn't be used otherwise, ditto
 
343
for sections. Again, the associated tests could and should be used against the
 
344
created stacks.
 
345
 
 
346
Also note that ``MemoryStack`` can be used without any disk resources which
 
347
allows for simpler and faster tests. A common pattern is to accept a
 
348
``config`` parameter related to a given feature and test it with predefined
 
349
configurations without involving the whole
 
350
stack. ``breezy.tests.test_commit``, ``breezy.tests.test_gpg`` and
 
351
``breezy.tests.test_smtp_connection`` are good examples.
 
352