<!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="Content-Type" content="text/html; charset=utf-8" />
<title>Bazaar Design Principles — Bazaar 2.6.0 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.6.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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>
<link rel="shortcut icon" href="_static/bzr.ico"/>
<link rel="top" title="Bazaar 2.6.0 documentation" href="index.html" />
<link rel="next" title="Plans" href="plans.html" />
<link rel="prev" title="Integrating with Bazaar" href="integration.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="plans.html" title="Plans"
accesskey="N">next</a></li>
<li class="right" >
<a href="integration.html" title="Integrating with Bazaar"
accesskey="P">previous</a> |</li>
<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><a href="index.html">Developer Document Catalog (2.6.0)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="bazaar-design-principles">
<h1>Bazaar Design Principles<a class="headerlink" href="#bazaar-design-principles" title="Permalink to this headline">¶</a></h1>
<p>We have learned or adopted a few general principles for code in Bazaar.
Generally we will try to follow them in future, either for consistency or
because they’ve been proven to work well, or both.</p>
<p>We may need to depart from these principles in particular special cases,
or modify them as we learn more, or we might be diverging for them for no
very good reason but just because of bugs. If in doubt, ask.</p>
<p>See also: <a class="reference external" href="index.html">Bazaar Developer Document Catalog</a>.</p>
<div class="section" id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2>
<p>Untested code is broken code.</p>
<p>So if a function is removed from the normal flow of execution (perhaps
because a new default format was introduced) we have to make sure we can
still execute and test the old code – or remove it altogether.</p>
</div>
<div class="section" id="data-formats">
<h2>Data formats<a class="headerlink" href="#data-formats" title="Permalink to this headline">¶</a></h2>
<p>Fixing code once it’s released is easy; fixing a problematic data format
once people have started using it is more difficult. We should document
and review formats separately from the code that implements them.</p>
<p>Data formats should have clear format markers that allow us to support new
formats in future. It should be easy to read the format without reading
the whole object.</p>
<p>The format marker should be a string understandable by a user that names
the format and gives the bzr release that introduced it. If the bzr
program doesn’t understand that format, it can at least show that format
marker to the user.</p>
<p>Once we mark a format as supported, we’ll continue supporting it for
several future releases, and support upgrading from it
forever.</p>
<p>Once we’ve released a format, we normally don’t change it. Adding new
optional elements can cause problems when older clients don’t understand
those changes, or don’t propagate them properly.</p>
<p>We clearly distinguish internal files from user files. Files inside
<tt class="docutils literal"><span class="pre">.bzr/</span></tt> are only written to by bzr and we discourage users from editing
them. Within bzr, code addressing the abstract interface of the Branch,
BzrDir, etc shouldn’t know where or how the internal files are stored. If
anything else is written in there, it won’t be propagated when pushing or
pulling, and won’t be converted when upgrading. (This is not quite true
though; there is a <tt class="docutils literal"><span class="pre">branch.conf</span></tt>.)</p>
<p>User files within the tree, by contrast, we always store and return
verbatim. It’s OK for Bazaar to read and act on these files (as we do
with <tt class="docutils literal"><span class="pre">.bzrignore</span></tt>), and to update them (as <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">ignore</span></tt> does), but
they remain clearly user files and can be directly edited.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Bazaar Design Principles</a><ul>
<li><a class="reference internal" href="#testing">Testing</a></li>
<li><a class="reference internal" href="#data-formats">Data formats</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="integration.html"
title="previous chapter">Integrating with Bazaar</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="plans.html"
title="next chapter">Plans</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/principles.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="plans.html" title="Plans"
>next</a></li>
<li class="right" >
<a href="integration.html" title="Integrating with Bazaar"
>previous</a> |</li>
<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><a href="index.html">Developer Document Catalog (2.6.0)</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>
