Merge lp:~vila/bzr/doc-new-config into lp:bzr
- doc-new-config
- Merge into bzr.dev
| Status: | Merged |
|---|---|
| Merge reported by: | Vincent Ladeuil |
| Merged at revision: | not available |
| Proposed branch: | lp:~vila/bzr/doc-new-config |
| Merge into: | lp:bzr |
| Prerequisite: | lp:~vila/bzr/672382-list-values |
| Diff against target: |
449 lines (+434/-0) 2 files modified
doc/developers/configuration.txt (+433/-0) doc/developers/index.txt (+1/-0) |
| To merge this branch: | bzr merge lp:~vila/bzr/doc-new-config |
| Related bugs: |
| Reviewer | Review Type | Date Requested | Status |
|---|---|---|---|
| Andrew Bennetts | Approve | ||
|
Review via email:
|
|||
Commit message
Description of the change
This is a brain dump of some thoughts about a new configuration option handling implementation.
Any kind of feedback welcome :)
I'd like to better separate this document into a user oriented one and a developer oriented one in the future so help welcome on this too.
| Andrew Bennetts (spiv) wrote : | # |
| Andrew Bennetts (spiv) wrote : | # |
As far as the proposed implementation goes, my thoughts are:
* there's lots of room for bikeshedding over syntax and even features... but this seems reasonable to me
* I'm a bit worried about performance: we should make sure the actual implementation imposes as little cost to the startup time as possible. In particular I wonder about the costs of evaluating definitions that refer to other definitions while guarding against cycles etc. It would be nice to have a configuration format that in principle doesn't require any more data to be read, parsed and validated than is relevant to the current operation.
* To a lesser extent I'm also concerned about the performance impact of adding more kinds of config file. It'll probably be fine, but we should measure.
* How will we manage the transition from the current config files to your proposed files?
* I'd like more detail about what replacements for appendpath will look like. Is there going to be a magic {rest-of-path] interpolation value, or something like that?
* In general it would be good to have more examples, perhaps even start the proposal with an example configuration file.
* I'm not sure how the proposed name spaces work: e.g. will users need to write “bzr.debug_flags” rather than just “debug_flags” everywhere?
As far as landing this branch goes: I think land it. It should be discussed on the list, but there's no reason not to land this branch on trunk in the meantime.
| Martin Pool (mbp) wrote : | # |
Overall:
I'm ok to land it. I would somewhat prefer to put it into devnotes
rather than trunk, because it is more of working notes than
documentation, though I have to admit devnotes has not been very
active.
I agree with spiv that seeing some examples of the configuration files
and APIs would probably help a lot.
It seems like there are various aspects that can be tackled
semi-independently though with ordering constraints, perhaps starting
with the new api for getting configuration values.
On 13 November 2010 02:18, Vincent Ladeuil <email address hidden> wrote:
> Vincent Ladeuil has proposed merging lp:~vila/bzr/doc-new-config into lp:bzr with lp:~vila/bzr/672382-list-values as a prerequisite.
>
> Requested reviews:
> bzr-core (bzr-core)
>
>
> This is a brain dump of some thoughts about a new configuration option handling implementation.
>
> Any kind of feedback welcome :)
>
> I'd like to better separate this document into a user oriented one and a developer oriented one in the future so help welcome on this too.
I'm glad you wrote this up.
I wonder if "here are problems we have now and proposed solutions"
should really live in the main tree, but it's better to have it there
than nowhere. In particular, the 'current' bit rarely seems to get
updated when things fixing it land.
Perhaps some of this can be recycled into user documentation or
developer documentation as the features it describes land.
One further issue is that some values seem to be safe to take from
untrustworthy data, eg remote or in-tree configuration (eg branch
nick), and others are not (eg a hook to run). I have been wondering
if we ought to make this part of the declaration of a hook, but I'm
not sure if a simple safe/unsafe split is enough.
> +Not all needs can be addressed by the default values used inside bzr and
> +bzrlib, no matter how well they are chosen (and they are ;).
> +
> +Many parts of ``bzrlib`` depends on some constants though and the user
> +should be able to customize the behavior to suit his needs so these
> +constants need to become configuration options.
> +
> +These options can be set from the command-line, in an environment variable
> +or recorded in a configuration file.
> +
> +Current issues
> +==============
I guess all of these, except perhaps the first (which is general)
should have bugs, but there may be little point manually pasting them
here.
> +
> +* Many parts of ``bzrlib`` declare constants and there is no way for the
> + user to look at or modify them.
> +
> +* The current API requires a configuration object to create, modify or
> + delete a configuration option in a given configuration file. ``bzr
> + config`` makes it almost transparent for the user. Internally though, not
> + all cases are handled: only BranchConfig implements chained configs,
> + nothing is provided at the repository level and too many plugins define
> + their own section or even their own config file.
The fact that you need an object is not a problem (afaics); the fact
that we have one class per place they can be stored is distasteful.
> +
> +* ``locations.conf`` defines the options that needs to override any setting
> + in ``branch.conf`` fo...
| Vincent Ladeuil (vila) wrote : | # |
>>>>> Andrew Bennetts <email address hidden> writes:
> Review: Approve
> As far as the proposed implementation goes, my thoughts are:
> * there's lots of room for bikeshedding over syntax and even
> features... but this seems reasonable to me
> * I'm a bit worried about performance: we should make sure the
> actual implementation imposes as little cost to the startup time
> as possible. In particular I wonder about the costs of
> evaluating definitions that refer to other definitions while
> guarding against cycles etc.
Negligible, as long as it doesn't imply multiple IOs for the same config
file. This is not guaranteed by the current implementation as alluded in
the 'option life cycle' section.
Compared to parsing a config file, interpolating one option value should
also be negligible (this is easier to measure but requires using config
files with an "average" content to be ). Also note that the actual
implementation is using configobj which provides interpolation and is
already active by default, you can even use it today with the %(option)s
syntax.
> It would be nice to have a configuration format that in principle
> doesn't require any more data to be read, parsed and validated
> than is relevant to the current operation.
That's a bit vague :)
My current thoughts are that we shouldn't try to validate the values
themselves, there are strings. period. Callers need to fallback to
default values if they can't find valid values in the files, which
includes the case where the option is not defined at all. As long as we
allow hand-editing of the config files, there is no guarantee that their
content is valid. From there, we can at best warn the user that some
content is invalid, but we can't block a bzr command because of that.
If we agree on that, then reading a config file can't fail and we can
focus on minimizing the number of times such a file should be read or
written.
Or may be you are referring to the edge case where we need to read all
config files in order to check that none of them define a given option ?
This is a concern with the actual implementation (see below) especially
if we start to use more or more config options (as in all the constants
used today in bzrlib).
> * To a lesser extent I'm also concerned about the performance
> impact of adding more kinds of config file. It'll probably be
> fine, but we should measure.
So far, with the actual implementation, getting a config option value
requires reading one or several config files depending on the
context. Setting a new value requires reading and writing a config file
(whether or not we had already read it).
I'd like to change the implementation so that, during one bzrlib
"session" (hand waving, think of it as one bzr command), getting a
config value requires reading one or more config files but only once
(i.e. if we need more values, we won't read the same file
again). Setting a new value requires writing a config file (optionally
re-reading it for safety) but doing so only once by config file for
which at least one option has been modified.
So overall, we should issue the same num...
| Vincent Ladeuil (vila) wrote : | # |
>>>>> Martin Pool <email address hidden> writes:
> Overall:
> I'm ok to land it. I would somewhat prefer to put it into devnotes
> rather than trunk, because it is more of working notes than
> documentation,
I'll do that.
> though I have to admit devnotes has not been very active.
> I agree with spiv that seeing some examples of the configuration files
> and APIs would probably help a lot.
Sure, I'll keep working on it to turn it into proper documentation. I
wanted some rough agreement before going further and try to split it
into work items.
> It seems like there are various aspects that can be tackled
> semi-independently though with ordering constraints, perhaps
> starting with the new api for getting configuration values.
I'm still unclear of the path to follow from here, my next target was a
first step in interpolation limited in scope to values defined in a
single config file.
<snip/>
> I wonder if "here are problems we have now and proposed solutions"
> should really live in the main tree, but it's better to have it there
> than nowhere. In particular, the 'current' bit rarely seems to get
> updated when things fixing it land.
Right, I try to address that by keeping it in the upper thread in my
loom, so that after I land something I keep coming to it.
> Perhaps some of this can be recycled into user documentation or
> developer documentation as the features it describes land.
That's the idea, I may even start with that before implementing anything.
> One further issue is that some values seem to be safe to take from
> untrustworthy data, eg remote or in-tree configuration (eg branch
> nick), and others are not (eg a hook to run). I have been
> wondering if we ought to make this part of the declaration of a
> hook, but I'm not sure if a simple safe/unsafe split is enough.
Me neither, one thing I haven't done yet, it to list all the
actual/potential config options to get a better idea.
<snip/>
>> +Current issues
>> +==============
> I guess all of these, except perhaps the first (which is general)
> should have bugs, but there may be little point manually pasting
> them here.
I've tried to mention the ones I was aware of in the text.
<snip/>
> The fact that you need an object is not a problem (afaics); the fact
> that we have one class per place they can be stored is distasteful.
Yup. The goal is that the same object should be usable in all cases and
ideally already provided in most of them (via the wt, branch, repo, etc
(hand-waving on the etc;)).
<snip/>
>> This is not a big concern so far as very few needs required
>> dicts as option values.
> last sentence doesn't quite parse.
'gtk_file_
a dict in the branch.conf file. I'm not sure I know other cases.
Is:
In a few known cases, a bencoded dict is stored in a config value, so
while this isn't user-friendly, not providing a better alternative
shouldn't be a concern.
clearer ?
> One more, for which there is a bug, is wanting a -O per-process config
> setting. ...
- 5520. By Vincent Ladeuil
-
Merge 672382-list-values into doc-new-config
- 5521. By Vincent Ladeuil
-
Merge bzr.dev into doc-new-config
- 5522. By Vincent Ladeuil
-
Fix some tweaks from review.
| Vincent Ladeuil (vila) wrote : | # |
Landed in lp:~bzr-core/bzr/devnotes/.
Keep replying by mail if you have further comments though !
Preview Diff
| 1 | === added file 'doc/developers/configuration.txt' | |||
| 2 | --- doc/developers/configuration.txt 1970-01-01 00:00:00 +0000 | |||
| 3 | +++ doc/developers/configuration.txt 2010-12-02 08:39:33 +0000 | |||
| 4 | @@ -0,0 +1,433 @@ | |||
| 5 | 1 | ================== | ||
| 6 | 2 | Configuring Bazaar | ||
| 7 | 3 | ================== | ||
| 8 | 4 | |||
| 9 | 5 | Goal | ||
| 10 | 6 | ==== | ||
| 11 | 7 | |||
| 12 | 8 | Not all needs can be addressed by the default values used inside bzr and | ||
| 13 | 9 | bzrlib, no matter how well they are chosen (and they are ;). | ||
| 14 | 10 | |||
| 15 | 11 | Many parts of ``bzrlib`` depends on some constants though and the user | ||
| 16 | 12 | should be able to customize the behavior to suit his needs so these | ||
| 17 | 13 | constants need to become configuration options. | ||
| 18 | 14 | |||
| 19 | 15 | These options can be set from the command-line, in an environment variable | ||
| 20 | 16 | or recorded in a configuration file. | ||
| 21 | 17 | |||
| 22 | 18 | Current issues | ||
| 23 | 19 | ============== | ||
| 24 | 20 | |||
| 25 | 21 | * Many parts of ``bzrlib`` declare constants and there is no way for the | ||
| 26 | 22 | user to look at or modify them. | ||
| 27 | 23 | |||
| 28 | 24 | * The current API requires a configuration object to create, modify or | ||
| 29 | 25 | delete a configuration option in a given configuration file. ``bzr | ||
| 30 | 26 | config`` makes it almost transparent for the user. Internally though, not | ||
| 31 | 27 | all cases are handled: only BranchConfig implements chained configs, | ||
| 32 | 28 | nothing is provided at the repository level and too many plugins define | ||
| 33 | 29 | their own section or even their own config file. | ||
| 34 | 30 | |||
| 35 | 31 | * ``locations.conf`` defines the options that needs to override any setting | ||
| 36 | 32 | in ``branch.conf`` for both local and remotes branches. Many users want a | ||
| 37 | 33 | way to define default values for options that are not defined in | ||
| 38 | 34 | ``branch.conf``. This could be approximated today by *not* defining these | ||
| 39 | 35 | options in ``branch.conf`` but in ``locations.conf`` instead. This | ||
| 40 | 36 | workaround doesn't allow a user to define defaults in ``locations.conf`` | ||
| 41 | 37 | and override them in ``branch.conf``. | ||
| 42 | 38 | |||
| 43 | 39 | * Defining a new option requires adding a new method in the ``Config`` | ||
| 44 | 40 | object to get access to features like: | ||
| 45 | 41 | |||
| 46 | 42 | * should the option be inherited by more specific sections, | ||
| 47 | 43 | |||
| 48 | 44 | * should the inherited value append the relative path between the | ||
| 49 | 45 | section one and the location it applies to. | ||
| 50 | 46 | |||
| 51 | 47 | * the default value (including calling any python code that may be | ||
| 52 | 48 | required to calculate this value), | ||
| 53 | 49 | |||
| 54 | 50 | * priority between sections and various config files | ||
| 55 | 51 | |||
| 56 | 52 | A related problem is that, in the actual implementation, some | ||
| 57 | 53 | configuration options have defined methods, other don't and this is | ||
| 58 | 54 | inconsistent. | ||
| 59 | 55 | |||
| 60 | 56 | * Access to the 'active' configuration option value from the command line | ||
| 61 | 57 | doesn't give access to specific section. | ||
| 62 | 58 | |||
| 63 | 59 | * Rules for configuration options are not clearly defined for remote | ||
| 64 | 60 | branches (they may differ between dumb and smart servers). | ||
| 65 | 61 | |||
| 66 | 62 | * The features offered by the Bazaar configuration files should be easily | ||
| 67 | 63 | accessible to plugin authors either by supporting plugin configuration | ||
| 68 | 64 | options in the configuration files or allowing plugin to define their | ||
| 69 | 65 | own configuration files. | ||
| 70 | 66 | |||
| 71 | 67 | * While the actual configuration files support sections, they are used in | ||
| 72 | 68 | mutually exclusive ways that make it impossible to offer the same set of | ||
| 73 | 69 | features to all configuration files: | ||
| 74 | 70 | |||
| 75 | 71 | * ``bazaar.conf`` use arbitrary names for sections. ``DEFAULT`` is used | ||
| 76 | 72 | for global options, ``ALIASES`` are used to define command aliases, | ||
| 77 | 73 | plugins can define their own sections, some plugins do that | ||
| 78 | 74 | (``bzr-bookmarks`` use ``BOOKMARKS`` for example), some other define | ||
| 79 | 75 | their own sections. | ||
| 80 | 76 | |||
| 81 | 77 | * ``locations.conf`` use globs as section names. This provides an easy | ||
| 82 | 78 | way to associate a set of options to a matching working tree or | ||
| 83 | 79 | branch, including remote ones. | ||
| 84 | 80 | |||
| 85 | 81 | * ``branch.conf`` doesn't use any section. | ||
| 86 | 82 | |||
| 87 | 83 | * There is no easy way to get configuration options for a given repository | ||
| 88 | 84 | or an arbitrary path. Working trees and branches are generally organized | ||
| 89 | 85 | in hierarchies and being able to share the option definitions is an often | ||
| 90 | 86 | required feature. This can also address some needs exhibited by various | ||
| 91 | 87 | branch schemes like looms, pipeline, colocated branches and nested | ||
| 92 | 88 | trees. Being able to specify options *in* a working tree could also help | ||
| 93 | 89 | support conflict resolution options for a given file, directory or | ||
| 94 | 90 | subtree. | ||
| 95 | 91 | |||
| 96 | 92 | * Since sections allow different definitions for the same option, a total | ||
| 97 | 93 | order should be defined between sections to select the right definition | ||
| 98 | 94 | for a given path. Allowing globs for section names is harmful in this | ||
| 99 | 95 | respect since the order is currently defined as being the lexicographical | ||
| 100 | 96 | one. The caveat here is that if the order is always defined for a given | ||
| 101 | 97 | set of sections it can change when one or several globs are modified and | ||
| 102 | 98 | the user may get surprising and unwanted results in these cases. The | ||
| 103 | 99 | lexicographical order is otherwise fine to define what section is more | ||
| 104 | 100 | specific than another. (This may not be a problem in real life since | ||
| 105 | 101 | longer globs are generally more specific than shorter ones and explicit | ||
| 106 | 102 | paths should also be longer than matching globs. That may leave a glob and | ||
| 107 | 103 | a path of equal length in a gray area but in practice using ``bzr config`` | ||
| 108 | 104 | should give enough feedback to address them). | ||
| 109 | 105 | |||
| 110 | 106 | * Internally, configuration files (and their fallbacks, ``bazaar.conf`` and | ||
| 111 | 107 | ``locations.conf`` for ``branch.conf``) are read every time *one* option is | ||
| 112 | 108 | queried. Likewise, setting or deleting a configuration option implies | ||
| 113 | 109 | writing the configuration file *immediately* after re-reading the file to | ||
| 114 | 110 | avoid racing updates. | ||
| 115 | 111 | |||
| 116 | 112 | * The current implementation use a mix of transport-based and direct file | ||
| 117 | 113 | systems operations. | ||
| 118 | 114 | |||
| 119 | 115 | * While the underlying ``ConfigObj`` implementation provides an | ||
| 120 | 116 | interpolation feature, the ``bzrlib`` implementation doesn't provide an | ||
| 121 | 117 | easy handling of templates where other configuration options can be | ||
| 122 | 118 | interpolated. Instead, ``locations.conf`` (and only it) allows for | ||
| 123 | 119 | ``appendpath`` and ``norecurse``. | ||
| 124 | 120 | |||
| 125 | 121 | * Inherited list values can't be modified, a more specific configuration can | ||
| 126 | 122 | only redefine the whole list. | ||
| 127 | 123 | |||
| 128 | 124 | * There is no easy way to define dicts (the most obvious one being to use a | ||
| 129 | 125 | dedicated section which is already overloaded). Using embedded sections | ||
| 130 | 126 | for this would not be practical either if we keep using a no-name section | ||
| 131 | 127 | for default values. In a few known cases, a bencoded dict is stored in a | ||
| 132 | 128 | config value, so while this isn't user-friendly, not providing a better | ||
| 133 | 129 | alternative shouldn't be a concern. | ||
| 134 | 130 | |||
| 135 | 131 | |||
| 136 | 132 | Proposed implementation | ||
| 137 | 133 | ======================= | ||
| 138 | 134 | |||
| 139 | 135 | |||
| 140 | 136 | Configuration files definition | ||
| 141 | 137 | ------------------------------ | ||
| 142 | 138 | |||
| 143 | 139 | While of course configurations files can be versioned they are not intended | ||
| 144 | 140 | to be accessed in sync with the files they refer to (one can imagine | ||
| 145 | 141 | handling versioned properties this way but this is *not* what the bazaar | ||
| 146 | 142 | configuration files are targeted at). ``bzr`` will always refer to | ||
| 147 | 143 | configuration files as they exist on disk when an option is queried or set. | ||
| 148 | 144 | |||
| 149 | 145 | The configuration files are generally local to the file system but some of | ||
| 150 | 146 | them can be accessed remotely (``branch.conf``, ``repo.conf``). | ||
| 151 | 147 | |||
| 152 | 148 | |||
| 153 | 149 | Naming | ||
| 154 | 150 | ------ | ||
| 155 | 151 | |||
| 156 | 152 | The option name space is organized as follow: | ||
| 157 | 153 | |||
| 158 | 154 | * Bazaar itself defines all its constants as ``bzr.option_name``. | ||
| 159 | 155 | |||
| 160 | 156 | * plugins can define their own options by prefixing them with the plugin | ||
| 161 | 157 | name as ``svn.option_name`` for the ``svn`` plugin. | ||
| 162 | 158 | |||
| 163 | 159 | Using valid python identifiers is recommended but not enforced (but we may | ||
| 164 | 160 | do so in the future). | ||
| 165 | 161 | |||
| 166 | 162 | Value | ||
| 167 | 163 | ----- | ||
| 168 | 164 | |||
| 169 | 165 | All option values are text. They are provided as Unicode strings to API | ||
| 170 | 166 | users with some refinements: | ||
| 171 | 167 | |||
| 172 | 168 | * boolean values can be obtained for a set of acceptable strings (yes/no, | ||
| 173 | 169 | y/n, on/off, etc), | ||
| 174 | 170 | |||
| 175 | 171 | * a list of strings from a value containing a comma separated list of | ||
| 176 | 172 | strings. | ||
| 177 | 173 | |||
| 178 | 174 | Since the configuration files can be edited by the user, ``bzr`` doesn't | ||
| 179 | 175 | expect their content to be validated. Instead, the code using options should | ||
| 180 | 176 | be ready to handle *invalid* values by warning the user and fallback to a | ||
| 181 | 177 | default value. Likely, if an option is not defined in any configuration | ||
| 182 | 178 | file, the code should fallback to a default value (helpers should be | ||
| 183 | 179 | provided by the API to handle common cases, warning the user, getting a | ||
| 184 | 180 | particular type of value, returning a default value). | ||
| 185 | 181 | |||
| 186 | 182 | This also ensures compatibility with values provided via environment | ||
| 187 | 183 | variables or from the command line. | ||
| 188 | 184 | |||
| 189 | 185 | Interpolation | ||
| 190 | 186 | ------------- | ||
| 191 | 187 | |||
| 192 | 188 | Some option values can be templates and contain references to other | ||
| 193 | 189 | options. This is especially useful to define URLs in sections shared for | ||
| 194 | 190 | multiple branches for example. It can also be used to describe commands | ||
| 195 | 191 | where some parameters are set by ``bzrlib`` at runtime. | ||
| 196 | 192 | |||
| 197 | 193 | Since options values are text-only, and to avoid clashing with other | ||
| 198 | 194 | interpolation syntaxes, references are enclosed with curly brackets:: | ||
| 199 | 195 | |||
| 200 | 196 | push_location = lp:~{launchpad_username}/bzr/{nick} | ||
| 201 | 197 | |||
| 202 | 198 | In the example above, ``launchpad_username`` is an already defined | ||
| 203 | 199 | configuration option while ``nick`` is the branch nickname and is set when a | ||
| 204 | 200 | configuration applies to a given branch. | ||
| 205 | 201 | |||
| 206 | 202 | The interpolation implementation should accept an additional dict so that | ||
| 207 | 203 | ``bzrlib`` or plugins can define references that can be interpolated without | ||
| 208 | 204 | being existing configuration options:: | ||
| 209 | 205 | |||
| 210 | 206 | diff_command={cmd} {cmd_opts} {file_a} {file_b} | ||
| 211 | 207 | |||
| 212 | 208 | There are two common errors that should be handled when handling interpolation: | ||
| 213 | 209 | |||
| 214 | 210 | * loops: when a configuration value refers to itself, directly or indirectly, | ||
| 215 | 211 | |||
| 216 | 212 | * undefined references: when a configuration value refers to an unknown option. | ||
| 217 | 213 | |||
| 218 | 214 | One possible implementation is to report errors when such references are | ||
| 219 | 215 | encountered. | ||
| 220 | 216 | |||
| 221 | 217 | Another implementation could be envisioned though: when a loop is | ||
| 222 | 218 | encountered, we can fall back to the less specific configurations. This | ||
| 223 | 219 | allows list values to refer to the definition in the less specific | ||
| 224 | 220 | configurations allowing:: | ||
| 225 | 221 | |||
| 226 | 222 | bazaar.conf: | ||
| 227 | 223 | debug_flags = hpss | ||
| 228 | 224 | |||
| 229 | 225 | branch.conf for mybranch: | ||
| 230 | 226 | debug_flags = {debug_flags}, hpssdetail | ||
| 231 | 227 | |||
| 232 | 228 | $ bzr -d mybranch config debug_flags | ||
| 233 | 229 | hpss, hpssdetail | ||
| 234 | 230 | |||
| 235 | 231 | Undefined references would still be detected if they are not defined in any | ||
| 236 | 232 | configuration or just stay unresolved which should be enough to trigger | ||
| 237 | 233 | errors displaying the value. Diagnosing typos should be doable in this case. | ||
| 238 | 234 | |||
| 239 | 235 | Configuration file syntax | ||
| 240 | 236 | ------------------------- | ||
| 241 | 237 | |||
| 242 | 238 | The configuration file is mostly an ``ini-file``. It contains ``name = | ||
| 243 | 239 | value`` lines grouped in sections. Comments are allowed by prefixing them | ||
| 244 | 240 | with the '#' character. | ||
| 245 | 241 | |||
| 246 | 242 | A section is named by the path it should apply to (more examples below). | ||
| 247 | 243 | |||
| 248 | 244 | Options defined outside of any section act as defaults when no section | ||
| 249 | 245 | applies. This means that in the most common cases, the user doesn't need to | ||
| 250 | 246 | define any section. | ||
| 251 | 247 | |||
| 252 | 248 | When sections are used, they provide a finer grain of configuration by | ||
| 253 | 249 | defining option sets that apply to some working trees, branches, | ||
| 254 | 250 | repositories or part of them. | ||
| 255 | 251 | |||
| 256 | 252 | The subset is defined by the common leading path or a glob. | ||
| 257 | 253 | |||
| 258 | 254 | * a full url: used to described options for remote branches and | ||
| 259 | 255 | repositories. | ||
| 260 | 256 | |||
| 261 | 257 | * local absolute path: used for working trees, branches or repositories | ||
| 262 | 258 | on the local disks. | ||
| 263 | 259 | |||
| 264 | 260 | * relative path: the path is relative to the configuration file and can be | ||
| 265 | 261 | used for colocated branches or threads in a loom, i.e any working tree, | ||
| 266 | 262 | branch or repository that is located in a place related to the | ||
| 267 | 263 | configuration file path. Some configuration files may define this path | ||
| 268 | 264 | relationship in specific ways to make them easier to use (i.e. if a config | ||
| 269 | 265 | file is somewhere below ``.bzr`` and refers to threads in a loom for | ||
| 270 | 266 | example, the relative path would be the thread name, it doesn't have to be | ||
| 271 | 267 | an *exact* relative path, as long as its interpretation is unambiguous and | ||
| 272 | 268 | clear for the user). | ||
| 273 | 269 | |||
| 274 | 270 | Whatever path is used, the options apply if the branch path starts with | ||
| 275 | 271 | the path defining the section (or if the glob matches). | ||
| 276 | 272 | |||
| 277 | 273 | The ConfigOption object | ||
| 278 | 274 | ----------------------- | ||
| 279 | 275 | |||
| 280 | 276 | In addition to the configuration files, one internal configuration dict can | ||
| 281 | 277 | contain definitions for some configuration options. This will allow a finer | ||
| 282 | 278 | grained definition of the default values and the online help. | ||
| 283 | 279 | |||
| 284 | 280 | The ConfigOption object will define: | ||
| 285 | 281 | |||
| 286 | 282 | * name | ||
| 287 | 283 | |||
| 288 | 284 | * default value. ``None`` is the "default" default value. | ||
| 289 | 285 | |||
| 290 | 286 | * docstring used for the help | ||
| 291 | 287 | |||
| 292 | 288 | * a list of config files where the option can be defined. | ||
| 293 | 289 | |||
| 294 | 290 | The ConfigFile object | ||
| 295 | 291 | --------------------- | ||
| 296 | 292 | |||
| 297 | 293 | This is an implementation-level object that should rarely be used directly. | ||
| 298 | 294 | |||
| 299 | 295 | * it can be local or remote | ||
| 300 | 296 | |||
| 301 | 297 | * locking | ||
| 302 | 298 | |||
| 303 | 299 | All lock operations should be implemented via transport objects. | ||
| 304 | 300 | |||
| 305 | 301 | * option life cycle | ||
| 306 | 302 | |||
| 307 | 303 | Working trees, branches and repositories should define a config attribute | ||
| 308 | 304 | following the same life cycle as their lock: the associated config file is | ||
| 309 | 305 | read once and written once if needed. This should minimize the file system | ||
| 310 | 306 | accesses or the network requests. There is no known racing scenarios for | ||
| 311 | 307 | configuration options, changing the existing implementation to this less | ||
| 312 | 308 | constrained one shouldn't introduce any. Yet, in order to detect such | ||
| 313 | 309 | racing scenarios, we can check that the current content of the | ||
| 314 | 310 | configuration file is the expected one before writing the new content and | ||
| 315 | 311 | emit warnings if differences occurred. The checks should be performed for | ||
| 316 | 312 | the modified values only. As of today, the size of the configuration files | ||
| 317 | 313 | are small enough to be kept in memory. | ||
| 318 | 314 | |||
| 319 | 315 | The Config object | ||
| 320 | 316 | ----------------- | ||
| 321 | 317 | |||
| 322 | 318 | This the object that provides access to the needed features: | ||
| 323 | 319 | |||
| 324 | 320 | * getting an option value, | ||
| 325 | 321 | |||
| 326 | 322 | * setting an option value, | ||
| 327 | 323 | |||
| 328 | 324 | * deleting an option value, | ||
| 329 | 325 | |||
| 330 | 326 | * handling a list of configuration files that should be tried in the given | ||
| 331 | 327 | order to find an option. | ||
| 332 | 328 | |||
| 333 | 329 | Depending on the files involved, a working tree, branch or repository object | ||
| 334 | 330 | should be provided to access the corresponding configuration files. Note | ||
| 335 | 331 | that providing a working tree object also implicitly provides the | ||
| 336 | 332 | associated branch and repository object so only one of them is required (or | ||
| 337 | 333 | none for configuration files specific to the user like bazaar.conf and | ||
| 338 | 334 | locations.conf). | ||
| 339 | 335 | |||
| 340 | 336 | Getting an option value | ||
| 341 | 337 | ~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 342 | 338 | |||
| 343 | 339 | Depending on the option, there are various places where it can be defined | ||
| 344 | 340 | and several ways to override these settings when needed. | ||
| 345 | 341 | |||
| 346 | 342 | The following lists all possible places where a configuration option can | ||
| 347 | 343 | be defined, but some options will make sense in only some of them. The | ||
| 348 | 344 | first to define a value for an option wins (None is therefore used to | ||
| 349 | 345 | express that an option is not set). | ||
| 350 | 346 | |||
| 351 | 347 | * command-line (Not Implemented Yet) | ||
| 352 | 348 | ``-Ooption=value`` see bug #491196. | ||
| 353 | 349 | |||
| 354 | 350 | * environment variable | ||
| 355 | 351 | |||
| 356 | 352 | ``export BZR_OPTION=value`` | ||
| 357 | 353 | |||
| 358 | 354 | Some environment variables doesn't have a corresponding configuration | ||
| 359 | 355 | option (BZR_PLUGIN_PATH) and most configuration options doesn't have a | ||
| 360 | 356 | corresponding environment variable. | ||
| 361 | 357 | |||
| 362 | 358 | * locations.conf | ||
| 363 | 359 | |||
| 364 | 360 | When an option is set in ``locations.conf`` it overrides any other | ||
| 365 | 361 | configuration file. This should be used with care as it allows setting a | ||
| 366 | 362 | different value than what is recommended by the project | ||
| 367 | 363 | |||
| 368 | 364 | * tree.conf (Not Implemented Yet) | ||
| 369 | 365 | |||
| 370 | 366 | The options related to the working tree. | ||
| 371 | 367 | |||
| 372 | 368 | This includes all options related to commits, ignored files, junk files, | ||
| 373 | 369 | etc. | ||
| 374 | 370 | |||
| 375 | 371 | Note that the sections defined there can use relative paths if some | ||
| 376 | 372 | options should apply to a subtree or some specific files only. | ||
| 377 | 373 | |||
| 378 | 374 | See bug #430538 and bug #654998. | ||
| 379 | 375 | |||
| 380 | 376 | * branch.conf | ||
| 381 | 377 | |||
| 382 | 378 | The options related to the branch. | ||
| 383 | 379 | |||
| 384 | 380 | Sections can be defined for co-located branches or loom threads. | ||
| 385 | 381 | |||
| 386 | 382 | * repo.conf (Not Implemented Yet) | ||
| 387 | 383 | |||
| 388 | 384 | The options related to the repository. | ||
| 389 | 385 | |||
| 390 | 386 | Using an option to describe whether or not a repository is shared could | ||
| 391 | 387 | help address bug #342119 but this will probably requires a format bump). | ||
| 392 | 388 | |||
| 393 | 389 | * project.conf (Not Implemented Yet) | ||
| 394 | 390 | |||
| 395 | 391 | The options common to all branches and working trees for a project. | ||
| 396 | 392 | |||
| 397 | 393 | * organization.conf (Not Implemented Yet) | ||
| 398 | 394 | |||
| 399 | 395 | The options common to all branches and working trees for an organization. | ||
| 400 | 396 | |||
| 401 | 397 | See bug #419854. | ||
| 402 | 398 | |||
| 403 | 399 | * bazaar.conf | ||
| 404 | 400 | |||
| 405 | 401 | The options the user has selected for the host he is using. | ||
| 406 | 402 | |||
| 407 | 403 | Sections can be defined for both remote and local branches to define | ||
| 408 | 404 | default values (i.e. the most common use of ``locations.conf`` today). | ||
| 409 | 405 | |||
| 410 | 406 | * default (Not Implemented Yet) | ||
| 411 | 407 | |||
| 412 | 408 | The options defined in the ``bzr`` source code. | ||
| 413 | 409 | |||
| 414 | 410 | This will be implemented via the ConfigOption objects. | ||
| 415 | 411 | |||
| 416 | 412 | Plugins can define additional configuration files as they see fit and | ||
| 417 | 413 | insert them in this list, see their documentation for details. | ||
| 418 | 414 | |||
| 419 | 415 | Compatibility | ||
| 420 | 416 | ============= | ||
| 421 | 417 | |||
| 422 | 418 | * The ``DEFAULT`` section in bazaar.conf should still be recognized but | ||
| 423 | 419 | won't be mandatory anymore. | ||
| 424 | 420 | |||
| 425 | 421 | * Other sections in the ``bazaar.conf`` configuration file are still | ||
| 426 | 422 | supported but their use is discouraged and we may deprecate them in the | ||
| 427 | 423 | future. Plugin authors are encouraged to migrate to the new name space | ||
| 428 | 424 | scheme by prefixing their options with their plugin name. | ||
| 429 | 425 | |||
| 430 | 426 | * Option policies should be deprecated: | ||
| 431 | 427 | |||
| 432 | 428 | * The ``norecurse`` policy is useless, all options are recursive by | ||
| 433 | 429 | default. If specific values are needed for specific paths, they can just | ||
| 434 | 430 | be defined as such. | ||
| 435 | 431 | |||
| 436 | 432 | * The ``appendpath`` policy should be implemented via interpolation and a | ||
| 437 | 433 | ``relpath`` option provided by the configuration framework. | ||
| 438 | 0 | 434 | ||
| 439 | === modified file 'doc/developers/index.txt' | |||
| 440 | --- doc/developers/index.txt 2010-10-13 04:13:48 +0000 | |||
| 441 | +++ doc/developers/index.txt 2010-12-02 08:39:33 +0000 | |||
| 442 | @@ -38,6 +38,7 @@ | |||
| 443 | 38 | 38 | ||
| 444 | 39 | transports | 39 | transports |
| 445 | 40 | ui | 40 | ui |
| 446 | 41 | configuration | ||
| 447 | 41 | 42 | ||
| 448 | 42 | Releasing and Packaging | 43 | Releasing and Packaging |
| 449 | 43 | ======================= | 44 | ======================= |
I've started looking at this. So far I can say: that is a clear and comprehensive list of the current issues. Thank you!