6213.1.1
by Jelmer Vernooij
Add feature flags spec. |
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 |
|
6213.1.3
by Jelmer Vernooij
s/importance/necessity |
39 |
a name and some sort of indicator that tells the bzr client its |
40 |
"necessity" - optional, required, ... |
|
6213.1.1
by Jelmer Vernooij
Add feature flags spec. |
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 |
||
6213.1.3
by Jelmer Vernooij
s/importance/necessity |
51 |
Feature necessity |
52 |
----------------- |
|
6213.1.1
by Jelmer Vernooij
Add feature flags spec. |
53 |
|
54 |
The initial implementation will feature the following set of possible |
|
6213.1.3
by Jelmer Vernooij
s/importance/necessity |
55 |
settings for feature "necessity". Any format necessity that can't |
6213.1.1
by Jelmer Vernooij
Add feature flags spec. |
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 |
- write-required: read access is possible if the feature is not supported, |
|
66 |
but write access requires it |
|
67 |
||
68 |
Format changes |
|
69 |
-------------- |
|
70 |
||
71 |
The feature information would be included in the appropriate ``format`` file |
|
72 |
(``.bzr/branch-format``, ``.bzr/branch/format``, ``.bzr/repository/format`` or |
|
73 |
``.bzr/checkout/format``). This file currently always contains a single |
|
74 |
line with the format name. Older versions of bzr read the full file. |
|
75 |
||
76 |
By using the other lines for feature information it is possible to add feature |
|
77 |
flags in a backwards compatible manner; older clients will simply fail to open |
|
78 |
repositories with feature flags set, giving a unknown format error. |
|
79 |
||
80 |
The other advantage of doing this is that we don't need any additional |
|
81 |
roundtrips when opening a remote format. An example .bzr/repository/format |
|
82 |
file could then look like this:: |
|
83 |
||
84 |
Bazaar repository format 2a (needs bzr 1.16 or later) |
|
85 |
optional git |
|
86 |
optional search |
|
87 |
optional tiplog |
|
88 |
required nested-trees |
|
89 |
||
90 |
In other words, this is a "2a" bzr format which also stores a cache of |
|
91 |
Git Tree/Commit objects, a bzr-search index, and a reflog. It also contains |
|
92 |
revisions with nested trees. |
|
93 |
||
94 |
API Changes |
|
95 |
----------- |
|
96 |
||
97 |
Class methods will be added to ``BzrDirComponentFormat`` to allow registering |
|
98 |
and deregistering the presence of particular features. This class is inherited |
|
99 |
by ``BzrBranchFormat``, ``VersionedFileRepositoryFormat`` and |
|
100 |
``InventoryWorkingTreeFormat``. |
|
101 |
||
102 |
* BzrDirComponentFormat.register_feature(name) |
|
103 |
* BzrDirComponentFormat.unregister_feature(name) |
|
104 |
||
105 |
Upon opening, BzrDirComponentFormat will be responsible for checking that the |
|
106 |
required features are present. lock_write will raise an exception |
|
107 |
when there is an un unsupported mandatory feature required for write access. |
|
108 |
||
109 |
Methods will also be added to BzrDirComponentFormat to allow plugins, etc, |
|
110 |
to check whether a feature is present and adding new features: |
|
111 |
||
6213.1.3
by Jelmer Vernooij
s/importance/necessity |
112 |
* BzrDirComponentFormat.set_feature(name, necessity) |
113 |
* BzrDirComponentFormat.get_feature(name) -> necessity |
|
6213.1.1
by Jelmer Vernooij
Add feature flags spec. |
114 |
|
6213.1.2
by Jelmer Vernooij
Add link to requires file. |
115 |
See also |
116 |
-------- |
|
117 |
||
118 |
Mercurial has a similar feature, using its `.hg/requires`_ file. |
|
119 |
||
120 |
.. _.hg/requires: http://mercurial.selenic.com/wiki/RequiresFile |
|
121 |
||
6213.1.1
by Jelmer Vernooij
Add feature flags spec. |
122 |
.. |
123 |
vim: ft=rst tw=74 ai |