← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/feature-flags.txt

  • Committer: John Arbash Meinel
  • Author(s): Mark Hammond
  • Date: 2008-09-09 17:02:21 UTC
  • mto: This revision was merged to the branch mainline in revision 3697.
  • Revision ID: john@arbash-meinel.com-20080909170221-svim3jw2mrz0amp3
An updated transparent icon for bzr.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/feature-flags.txt
1
 
Format feature flags
2
 
====================
3
 
 
4
 
.. contents::
5
 
 
6
 
Rationale
7
 
---------
8
 
 
9
 
In the past when new features were added that required a change to the
10
 
on-disk format, Bazaar has introduced a new format (in other words,
11
 
a different string in .bzr/branch-format, .bzr/branch/format,
12
 
.bzr/repository/format or .bzr/checkout/format). The main reason for this
13
 
was that it made old versions of Bazaar give a sensible error message
14
 
when they encountered on-disk data that they could not understand.
15
 
 
16
 
There are also several disadvantages to such an approach:
17
 
 
18
 
 * Once upgraded, a newer version of Bazaar is required to access the data
19
 
   (it is often possible to downgrade the format later on)
20
 
 
21
 
 * Upgrading requires an explicit action by the user. It could be
22
 
   done automatically, but then accessing a repository with a newer version
23
 
   of Bazaar might accidentally render it inaccessible by older.
24
 
 
25
 
Not all format changes should necessarily render the data inaccessible
26
 
to older versions of Bazaar.
27
 
 
28
 
There are also various plugins that store extra metadata in the Bazaar
29
 
version control directory. They currently have no way of indicating that
30
 
e.g. writing to the repository requires a particular plugin to be installed
31
 
(so the metadata can be kept up to date, for example).
32
 
 
33
 
Proposed approach
34
 
-----------------
35
 
 
36
 
To allow for more granular changes to the format, this spec proposes
37
 
to add feature flags to the Bazaar formats, indicating
38
 
what kind of data is present in that repository. Each feature has
39
 
a name and some sort of indicator that tells the bzr client its
40
 
"necessity" - optional, required, ...
41
 
 
42
 
bzr clients would be able to open data with features that are
43
 
set as "optional" but that they do not support. If there are features
44
 
that aren't supported which are marked "required" in the repository they
45
 
would refuse to open the repository.
46
 
 
47
 
Various kinds of metadata, e.g. ones that are generated from the
48
 
repository itself and can be discarded without losing data (caches)
49
 
would fall in the optional category.
50
 
 
51
 
Feature necessity
52
 
-----------------
53
 
 
54
 
The initial implementation will feature the following two possible
55
 
settings for feature ``necessity``. Any format necessity that can't
56
 
be understood should be interpreted as "required", and an appropriate
57
 
warning printed.
58
 
 
59
 
 - optional: the feature is present, but writing/reading of the
60
 
      repository/branch/checkout is possible without support for the
61
 
      feature. Useful for things like caches (e.g. bzr-search index,
62
 
      annotate cache)
63
 
 - required: read and write access is only possible if the feature
64
 
      is supported. Useful for things like nested trees.
65
 
 
66
 
In the future, we might add more values for necessity. Older
67
 
versions of bzr treat unknown necessities as "required". Some likely
68
 
candidates for new necessities that might be added in the future:
69
 
 
70
 
 - read-optional: read access is possible if the feature is not supported,
71
 
      but write access requires it
72
 
 - client-read-optional: directly writing to the object requires
73
 
      the feature, but reading or writing through an intermediary (such as
74
 
      a HPSS server) doesn't.
75
 
 
76
 
Format changes
77
 
--------------
78
 
 
79
 
The feature information would be included in the appropriate ``format`` file
80
 
(``.bzr/branch-format``, ``.bzr/branch/format``, ``.bzr/repository/format`` or
81
 
``.bzr/checkout/format``). This file currently always contains a single
82
 
line with the format name. Older versions of bzr read the full file.
83
 
 
84
 
By using the other lines for feature information it is possible to add feature
85
 
flags in a backwards compatible manner; older clients will simply fail to open
86
 
repositories with feature flags set, giving a unknown format error.
87
 
 
88
 
The other advantage of doing this is that we don't need any additional
89
 
roundtrips when opening a remote format. An example .bzr/repository/format
90
 
file could then look like this::
91
 
 
92
 
  Bazaar repository format 2a (needs bzr 1.16 or later)
93
 
  optional git
94
 
  optional search
95
 
  optional tiplog
96
 
  required nested-trees
97
 
 
98
 
In other words, this is a "2a" bzr format which also stores a cache of
99
 
Git Tree/Commit objects, a bzr-search index, and a reflog. It also contains
100
 
revisions with nested trees.
101
 
 
102
 
API Changes
103
 
-----------
104
 
 
105
 
Class methods will be added to ``BzrFormat`` to allow registering
106
 
and unregistering the presence of particular features.
107
 
 
108
 
 * BzrFormat.register_feature(name)
109
 
 * BzrFormat.unregister_feature(name)
110
 
 
111
 
The namespace for features is global. It is assumed
112
 
that the plugin that provides the feature X provides that feature
113
 
in all objects that it is relevant for. For example, if a plugin
114
 
provides the ``nested-trees`` feature, it is assumed to support
115
 
that in both working trees and repositories. If this is not the case,
116
 
it should use a different feature name for the working tree support
117
 
and the repository support.
118
 
 
119
 
BzrFormat is inherited by ``BranchFormatMetaDir``, ``BzrDirFormat``,
120
 
``RepositoryFormatMetaDir`` and ``WorkingTreeFormatMetaDir``.
121
 
 
122
 
Upon opening, BzrFormat will be responsible for checking that the
123
 
required features are present.  lock_write will raise an exception
124
 
when there is an unsupported mandatory feature required for write access.
125
 
 
126
 
Methods will also be added to BzrFormat to allow plugins, etc,
127
 
to check whether a feature is present and adding new features:
128
 
 
129
 
 * BzrFormat.features.set(name, necessity)
130
 
 * BzrFormat.features.get(name) -> necessity
131
 
 
132
 
Enabling features
133
 
-----------------
134
 
 
135
 
Features are enabled through the ``update_feature_flags`` method on
136
 
``Repository``, ``Branch``, ``WorkingTree`` and ``BzrDir``.
137
 
 
138
 
These methods are called by whatever needs to enable features.
139
 
When they do that is up to them - e.g. bzr-search would enable its
140
 
feature when ``bzr index`` is first run.
141
 
 
142
 
See also
143
 
--------
144
 
 
145
 
Mercurial has a similar feature, using its `.hg/requires`_ file.
146
 
 
147
 
.. _.hg/requires: http://mercurial.selenic.com/wiki/RequiresFile
148
 
 
149
 
..
150
 
   vim: ft=rst tw=74 ai