<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Format feature flags — Bazaar 2.7.0 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="shortcut icon" href="_static/bzr.ico"/>
<link rel="search" title="Search" href="search.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="format-feature-flags">
<h1><a class="toc-backref" href="#id1">Format feature flags</a><a class="headerlink" href="#format-feature-flags" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#format-feature-flags" id="id1">Format feature flags</a><ul>
<li><a class="reference internal" href="#rationale" id="id2">Rationale</a></li>
<li><a class="reference internal" href="#proposed-approach" id="id3">Proposed approach</a></li>
<li><a class="reference internal" href="#feature-necessity" id="id4">Feature necessity</a></li>
<li><a class="reference internal" href="#format-changes" id="id5">Format changes</a></li>
<li><a class="reference internal" href="#api-changes" id="id6">API Changes</a></li>
<li><a class="reference internal" href="#enabling-features" id="id7">Enabling features</a></li>
<li><a class="reference internal" href="#see-also" id="id8">See also</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="rationale">
<h2><a class="toc-backref" href="#id2">Rationale</a><a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>There are also several disadvantages to such an approach:</p>
<blockquote>
<div><ul class="simple">
<li>Once upgraded, a newer version of Bazaar is required to access the data
(it is often possible to downgrade the format later on)</li>
<li>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.</li>
</ul>
</div></blockquote>
<p>Not all format changes should necessarily render the data inaccessible
to older versions of Bazaar.</p>
<p>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).</p>
</div>
<div class="section" id="proposed-approach">
<h2><a class="toc-backref" href="#id3">Proposed approach</a><a class="headerlink" href="#proposed-approach" title="Permalink to this headline">¶</a></h2>
<p>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, …</p>
<p>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.</p>
<p>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.</p>
</div>
<div class="section" id="feature-necessity">
<h2><a class="toc-backref" href="#id4">Feature necessity</a><a class="headerlink" href="#feature-necessity" title="Permalink to this headline">¶</a></h2>
<p>The initial implementation will feature the following two possible
settings for feature <code class="docutils literal notranslate"><span class="pre">necessity</span></code>. Any format necessity that can’t
be understood should be interpreted as “required”, and an appropriate
warning printed.</p>
<blockquote>
<div><ul class="simple">
<li><dl class="first docutils">
<dt>optional: the feature is present, but writing/reading of the</dt>
<dd>repository/branch/checkout is possible without support for the
feature. Useful for things like caches (e.g. bzr-search index,
annotate cache)</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>required: read and write access is only possible if the feature</dt>
<dd>is supported. Useful for things like nested trees.</dd>
</dl>
</li>
</ul>
</div></blockquote>
<p>In the future, we might add more values for necessity. Older
versions of bzr treat unknown necessities as “required”. Some likely
candidates for new necessities that might be added in the future:</p>
<blockquote>
<div><ul class="simple">
<li><dl class="first docutils">
<dt>read-optional: read access is possible if the feature is not supported,</dt>
<dd>but write access requires it</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>client-read-optional: directly writing to the object requires</dt>
<dd>the feature, but reading or writing through an intermediary (such as
a HPSS server) doesn’t.</dd>
</dl>
</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="format-changes">
<h2><a class="toc-backref" href="#id5">Format changes</a><a class="headerlink" href="#format-changes" title="Permalink to this headline">¶</a></h2>
<p>The feature information would be included in the appropriate <code class="docutils literal notranslate"><span class="pre">format</span></code> file
(<code class="docutils literal notranslate"><span class="pre">.bzr/branch-format</span></code>, <code class="docutils literal notranslate"><span class="pre">.bzr/branch/format</span></code>, <code class="docutils literal notranslate"><span class="pre">.bzr/repository/format</span></code> or
<code class="docutils literal notranslate"><span class="pre">.bzr/checkout/format</span></code>). This file currently always contains a single
line with the format name. Older versions of bzr read the full file.</p>
<p>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.</p>
<p>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:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Bazaar</span> <span class="n">repository</span> <span class="nb">format</span> <span class="mi">2</span><span class="n">a</span> <span class="p">(</span><span class="n">needs</span> <span class="n">bzr</span> <span class="mf">1.16</span> <span class="ow">or</span> <span class="n">later</span><span class="p">)</span>
<span class="n">optional</span> <span class="n">git</span>
<span class="n">optional</span> <span class="n">search</span>
<span class="n">optional</span> <span class="n">tiplog</span>
<span class="n">required</span> <span class="n">nested</span><span class="o">-</span><span class="n">trees</span>
</pre></div>
</div>
<p>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.</p>
</div>
<div class="section" id="api-changes">
<h2><a class="toc-backref" href="#id6">API Changes</a><a class="headerlink" href="#api-changes" title="Permalink to this headline">¶</a></h2>
<p>Class methods will be added to <code class="docutils literal notranslate"><span class="pre">BzrFormat</span></code> to allow registering
and unregistering the presence of particular features.</p>
<blockquote>
<div><ul class="simple">
<li>BzrFormat.register_feature(name)</li>
<li>BzrFormat.unregister_feature(name)</li>
</ul>
</div></blockquote>
<p>The namespace for features is global. It is assumed
that the plugin that provides the feature X provides that feature
in all objects that it is relevant for. For example, if a plugin
provides the <code class="docutils literal notranslate"><span class="pre">nested-trees</span></code> feature, it is assumed to support
that in both working trees and repositories. If this is not the case,
it should use a different feature name for the working tree support
and the repository support.</p>
<p>BzrFormat is inherited by <code class="docutils literal notranslate"><span class="pre">BranchFormatMetaDir</span></code>, <code class="docutils literal notranslate"><span class="pre">BzrDirFormat</span></code>,
<code class="docutils literal notranslate"><span class="pre">RepositoryFormatMetaDir</span></code> and <code class="docutils literal notranslate"><span class="pre">WorkingTreeFormatMetaDir</span></code>.</p>
<p>Upon opening, BzrFormat will be responsible for checking that the
required features are present. lock_write will raise an exception
when there is an unsupported mandatory feature required for write access.</p>
<p>Methods will also be added to BzrFormat to allow plugins, etc,
to check whether a feature is present and adding new features:</p>
<blockquote>
<div><ul class="simple">
<li>BzrFormat.features.set(name, necessity)</li>
<li>BzrFormat.features.get(name) -> necessity</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="enabling-features">
<h2><a class="toc-backref" href="#id7">Enabling features</a><a class="headerlink" href="#enabling-features" title="Permalink to this headline">¶</a></h2>
<p>Features are enabled through the <code class="docutils literal notranslate"><span class="pre">update_feature_flags</span></code> method on
<code class="docutils literal notranslate"><span class="pre">Repository</span></code>, <code class="docutils literal notranslate"><span class="pre">Branch</span></code>, <code class="docutils literal notranslate"><span class="pre">WorkingTree</span></code> and <code class="docutils literal notranslate"><span class="pre">BzrDir</span></code>.</p>
<p>These methods are called by whatever needs to enable features.
When they do that is up to them - e.g. bzr-search would enable its
feature when <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">index</span></code> is first run.</p>
</div>
<div class="section" id="see-also">
<h2><a class="toc-backref" href="#id8">See also</a><a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<p>Mercurial has a similar feature, using its <a class="reference external" href="http://mercurial.selenic.com/wiki/RequiresFile">.hg/requires</a> file.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Format feature flags</a><ul>
<li><a class="reference internal" href="#rationale">Rationale</a></li>
<li><a class="reference internal" href="#proposed-approach">Proposed approach</a></li>
<li><a class="reference internal" href="#feature-necessity">Feature necessity</a></li>
<li><a class="reference internal" href="#format-changes">Format changes</a></li>
<li><a class="reference internal" href="#api-changes">API Changes</a></li>
<li><a class="reference internal" href="#enabling-features">Enabling features</a></li>
<li><a class="reference internal" href="#see-also">See also</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/feature-flags.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
</div>
</body>
</html>
