Rev 6232: (jelmer) Add feature flag specification. (Jelmer Vernooij) in file:///srv/pqm.bazaar-vcs.org/archives/thelove/bzr/%2Btrunk/

[Patch Queue Manager]

At file:///srv/pqm.bazaar-vcs.org/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 6232 [merge]
revision-id: pqm at pqm.ubuntu.com-20111025174826-ezuhhudke8563fzd
parent: pqm at pqm.ubuntu.com-20111025125034-c1z0d52n9two1h9m
parent: jelmer at samba.org-20111024192100-tirpujp3ycs1btmh
committer: Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Tue 2011-10-25 17:48:26 +0000
message:
  (jelmer) Add feature flag specification. (Jelmer Vernooij)
added:
  doc/developers/feature-flags.txt featureflags.txt-20111014011252-hvtwde3cv5dusxnb-1
modified:
  doc/developers/plans.txt       plans.txt-20090907074210-zula633ky077z6vu-8
=== added file 'doc/developers/feature-flags.txt'
--- a/doc/developers/feature-flags.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/feature-flags.txt	2011-10-24 19:21:00 +0000
@@ -0,0 +1,123 @@
+Format feature flags
+====================
+
+.. contents::
+
+Rationale
+---------
+
+In the past when new features were added that required a change to the
+on-disk format, Bazaar has introduced a new format (in other words,
+a different string in .bzr/branch-format, .bzr/branch/format,
+.bzr/repository/format or .bzr/checkout/format). The main reason for this
+was that it made old versions of Bazaar give a sensible error message
+when they encountered on-disk data that they could not understand.
+
+There are also several disadvantages to such an approach:
+
+ * Once upgraded, a newer version of Bazaar is required to access the data
+   (it is often possible to downgrade the format later on)
+
+ * Upgrading requires an explicit action by the user. It could be
+   done automatically, but then accessing a repository with a newer version
+   of Bazaar might accidentally render it inaccessible by older.
+
+Not all format changes should necessarily render the data inaccessible
+to older versions of Bazaar.
+
+There are also various plugins that store extra metadata in the Bazaar
+version control directory. They currently have no way of indicating that
+e.g. writing to the repository requires a particular plugin to be installed
+(so the metadata can be kept up to date, for example).
+
+Proposed approach
+-----------------
+
+To allow for more granular changes to the format, this spec proposes
+to add feature flags to the Bazaar formats, indicating
+what kind of data is present in that repository. Each feature has
+a name and some sort of indicator that tells the bzr client its
+"necessity" - optional, required, ...
+
+bzr clients would be able to open data with features that are
+set as "optional" but that they do not support. If there are features
+that aren't supported which are marked "required" in the repository they
+would refuse to open the repository.
+
+Various kinds of metadata, e.g. ones that are generated from the
+repository itself and can be discarded without losing data (caches)
+would fall in the optional category.
+
+Feature necessity
+-----------------
+
+The initial implementation will feature the following set of possible
+settings for feature "necessity". Any format necessity that can't
+be understood should be interpreted as "required", and an appropriate
+warning printed.
+
+ - optional: the feature is present, but writing/reading of the
+      repository/branch/checkout is possible without support for the
+      feature. Useful for things like caches (e.g. bzr-search index,
+      annotate cache)
+ - required: read and write access is only possible if the feature
+      is supported. Useful for things like nested trees.
+ - write-required: read access is possible if the feature is not supported,
+      but write access requires it
+
+Format changes
+--------------
+
+The feature information would be included in the appropriate ``format`` file
+(``.bzr/branch-format``, ``.bzr/branch/format``, ``.bzr/repository/format`` or
+``.bzr/checkout/format``). This file currently always contains a single
+line with the format name. Older versions of bzr read the full file.
+
+By using the other lines for feature information it is possible to add feature
+flags in a backwards compatible manner; older clients will simply fail to open
+repositories with feature flags set, giving a unknown format error.
+
+The other advantage of doing this is that we don't need any additional
+roundtrips when opening a remote format. An example .bzr/repository/format
+file could then look like this::
+
+  Bazaar repository format 2a (needs bzr 1.16 or later)
+  optional git
+  optional search
+  optional tiplog
+  required nested-trees
+
+In other words, this is a "2a" bzr format which also stores a cache of
+Git Tree/Commit objects, a bzr-search index, and a reflog. It also contains
+revisions with nested trees.
+
+API Changes
+-----------
+
+Class methods will be added to ``BzrDirComponentFormat`` to allow registering
+and deregistering the presence of particular features. This class is inherited
+by ``BzrBranchFormat``, ``VersionedFileRepositoryFormat`` and
+``InventoryWorkingTreeFormat``.
+
+ * BzrDirComponentFormat.register_feature(name)
+ * BzrDirComponentFormat.unregister_feature(name)
+
+Upon opening, BzrDirComponentFormat will be responsible for checking that the
+required features are present.  lock_write will raise an exception
+when there is an un unsupported mandatory feature required for write access.
+
+Methods will also be added to BzrDirComponentFormat to allow plugins, etc,
+to check whether a feature is present and adding new features:
+
+ * BzrDirComponentFormat.set_feature(name, necessity)
+ * BzrDirComponentFormat.get_feature(name) -> necessity
+
+See also
+--------
+
+Mercurial has a similar feature, using its `.hg/requires`_ file.
+
+.. _.hg/requires: http://mercurial.selenic.com/wiki/RequiresFile
+
+..
+   vim: ft=rst tw=74 ai

=== modified file 'doc/developers/plans.txt'
--- a/doc/developers/plans.txt	2010-07-07 11:21:19 +0000
+++ b/doc/developers/plans.txt	2011-10-14 01:18:16 +0000
@@ -6,6 +6,7 @@
 
    performance-roadmap
    colocated-branches
+   feature-flags
    tortoise-strategy
    improved_chk_index
 
@@ -17,7 +18,7 @@
   for storing multiple branches in one file-system directory.
 
 * `Bazaar Windows Shell Extension Options <tortoise-strategy.html>`_ |--|
-  Implmentation strategy for Bazaar Windows Shell Extensions, aka
+  Implementation strategy for Bazaar Windows Shell Extensions, aka
   TortoiseBzr.
 
 * `CHK Optimized index <improved_chk_index.html>`_