← 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: Patch Queue Manager
  • Date: 2011-10-25 17:48:26 UTC
  • mfrom: (6213.1.3 feature-flags-spec)
  • Revision ID: pqm@pqm.ubuntu.com-20111025174826-ezuhhudke8563fzd
(jelmer) Add feature flag specification. (Jelmer Vernooij)

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 set of 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
 - 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
 
 
112
 * BzrDirComponentFormat.set_feature(name, necessity)
 
113
 * BzrDirComponentFormat.get_feature(name) -> necessity
 
114
 
 
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
 
 
122
..
 
123
   vim: ft=rst tw=74 ai