<!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 Upgrade Guide — 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="Bazaar User Reference" href="../user-reference/index.html" />
<link rel="prev" title="Bazaar Release Notes" href="../release-notes/bzr-0.1.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../user-reference/index.html" title="Bazaar User Reference"
accesskey="N">next</a></li>
<li class="right" >
<a href="../release-notes/bzr-0.1.html" title="Bazaar Release Notes"
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">Table of Contents (2.6.0)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="bazaar-upgrade-guide">
<h1>Bazaar Upgrade Guide<a class="headerlink" href="#bazaar-upgrade-guide" title="Permalink to this headline">¶</a></h1>
<div class="section" id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<div class="section" id="high-level-upgrade-process">
<h3>High level upgrade process<a class="headerlink" href="#high-level-upgrade-process" title="Permalink to this headline">¶</a></h3>
<p>In broad terms, there are 3 steps involved in upgrading a new format:</p>
<ol class="arabic simple">
<li>Upgrade the core software</li>
<li>Upgrade required plugins</li>
<li>Migrate data to the new default format.</li>
</ol>
<p>Bazaar supports branches in earlier formats so the third step is strictly not
required. However, when new default formats are introduced, they are more
space efficient, faster on large projects and/or provide new features. So it
is recommended that most projects migrate to it at a convenient time.</p>
<p>For most users, upgrading and migrating to the new format is straight
forward. For projects with a large community of developers though, things
become more complex. In these cases, careful planning and good communications
become essential. This document provides general advice which aims to assist
in this regard. If in doubt, please contact us on our mailing list or IRC
channel with any questions or concerns you have.</p>
</div>
<div class="section" id="upgrading-the-core-software">
<h3>Upgrading the core software<a class="headerlink" href="#upgrading-the-core-software" title="Permalink to this headline">¶</a></h3>
<p>The steps required to upgrade the core software vary from operating system to
operating system. A brief outline of the steps is given below.</p>
<p>To upgrade Bazaar on Ubuntu:</p>
<ol class="arabic simple">
<li>Ensure your package manager is configured with the required software
sources, e.g. the official stable release PPA for Ubuntu:
<a class="reference external" href="https://launchpad.net/~bzr/+archive">https://launchpad.net/~bzr/+archive</a></li>
<li>Use your package manager to upgrade to the latest version.</li>
</ol>
<p>To upgrade Bazaar on Windows:</p>
<ol class="arabic simple">
<li>Uninstall the existing version using Add/Remove Programs.</li>
<li>Install the new version using the relevant installer.</li>
</ol>
<p>To upgrade Bazaar on OS X (via the installer):</p>
<ol class="arabic simple">
<li>Install the new version using the relevant installer.</li>
</ol>
<p>To upgrade Bazaar on OS X (via MacPorts):</p>
<ol class="arabic simple">
<li>Refresh the package metadata using <strong>sudo port selfupdate</strong></li>
<li>Upgrade to the latest version using <strong>sudo port upgrade bzr</strong></li>
</ol>
<p>For further information on installing and upgrading, see
<a class="reference external" href="http://wiki.bazaar.canonical.com/Download">http://wiki.bazaar.canonical.com/Download</a>.</p>
</div>
<div class="section" id="upgrading-required-plugins">
<h3>Upgrading required plugins<a class="headerlink" href="#upgrading-required-plugins" title="Permalink to this headline">¶</a></h3>
<p>Many plugins are not dependent on a particular Bazaar version so
upgrading them is optional. Other plugins, notably bzrtools and
bzr-svn, are more tightly associated with Bazaar’s APIs so these
typically need to be upgraded in lockstep with the core software.</p>
<p>For Windows and OS X users, bzrtools and bzr-svn are typically included in
the installer so no special steps are required to upgrade these. For
Ubuntu and other GNU/Linux or Unix systems users, bztrools, bzr-svn and
many other popular plugins can be installed and upgraded using your
platform’s package manager, e.g. Synaptic on Ubuntu.</p>
</div>
<div class="section" id="migrating-data-to-the-new-default-format">
<h3>Migrating data to the new default format<a class="headerlink" href="#migrating-data-to-the-new-default-format" title="Permalink to this headline">¶</a></h3>
<p>As mentioned earlier, the complexity of migrating to a new format
depends on several factors, particularly project community size.
It also depends on how data is currently stored, e.g. in a
standalone branch, multiple branches in a shared repository,
stacked branches on Launchpad, etc. These various scenarios are
covered in the next chapter.</p>
</div>
</div>
<div class="section" id="data-migration">
<h2>Data migration<a class="headerlink" href="#data-migration" title="Permalink to this headline">¶</a></h2>
<div class="section" id="preparing-for-data-migration">
<h3>Preparing for data migration<a class="headerlink" href="#preparing-for-data-migration" title="Permalink to this headline">¶</a></h3>
<p>Before starting a migration, there are a few important things to do
first:</p>
<ol class="arabic simple">
<li>Take a complete backup.</li>
<li>Take some time to purge obsolete branches.</li>
</ol>
<p>A complete backup gives you a safety net in case anything goes wrong.</p>
<p>Purging obsolete branches reduces the amount of data that needs to
be migrated. See <a class="reference internal" href="#finding-obsolete-branches">Finding obsolete branches</a> later for some tips
on doing this.</p>
</div>
<div class="section" id="introducing-the-upgrade-related-commands">
<h3>Introducing the upgrade-related commands<a class="headerlink" href="#introducing-the-upgrade-related-commands" title="Permalink to this headline">¶</a></h3>
<p>There are 3 important commands to be aware of when migrating data.</p>
<ul class="simple">
<li><strong>check</strong> - check a repository, branch or tree for data integrity errors</li>
<li><strong>reconcile</strong> - fix data integrity errors</li>
<li><strong>upgrade</strong> - migrate data to a different format.</li>
</ul>
<p><strong>reconcile</strong> is rarely needed but it’s good practice to run <strong>check</strong>
before and after running <strong>upgrade</strong>.</p>
<p>For detailed help on these commands, see the <a class="reference external" href="../user-reference/index.html">Bazaar User Reference</a>.</p>
</div>
<div class="section" id="communicating-with-your-community">
<h3>Communicating with your community<a class="headerlink" href="#communicating-with-your-community" title="Permalink to this headline">¶</a></h3>
<p>To enable a smooth transition to the new format, you should:</p>
<ol class="arabic simple">
<li>Make one person responsible for migrating the trunk.</li>
<li>Test the migration of trunk works successfully.</li>
<li>Schedule a time for the trunk migration and notify your community
in advance.</li>
</ol>
<p>This advance warning should be long enough for users to have time
to upgrade Bazaar and any required plugins before the migration date.</p>
<p>For larger projects, allow some time for the migration itself.
You should have a good idea of how long the migration will take
after doing the test migration. It may make sense to do the migration
on a weekend or a Friday, giving yourself some breathing space if
things go wrong.</p>
<p>After the trunk is migrated, you’ll need to notify your community
accordingly, giving them instructions as to how to migrate their
local branches. Sample instructions are provided later in this
document.</p>
</div>
<div class="section" id="migrating-a-standalone-branch">
<h3>Migrating a standalone branch<a class="headerlink" href="#migrating-a-standalone-branch" title="Permalink to this headline">¶</a></h3>
<p>The steps are:</p>
<ol class="arabic simple">
<li>Run <strong>bzr check</strong>.</li>
<li>If there are errors, try using <strong>bzr reconcile</strong> to fix them.
If that fails, file a bug so we can help you resolve the issue
and get your trunk clean. If it works, take a backup copy of
your now clean trunk.</li>
</ol>
<ol class="arabic simple" start="2">
<li>Run <strong>bzr upgrade –format</strong> where <em>format</em> is 2a or later.</li>
<li>Run <strong>bzr check</strong> to confirm the final result is good.</li>
</ol>
</div>
<div class="section" id="migrating-branches-in-a-shared-repository">
<h3>Migrating branches in a shared repository<a class="headerlink" href="#migrating-branches-in-a-shared-repository" title="Permalink to this headline">¶</a></h3>
<p>Upgrade things in the following order:</p>
<ol class="arabic simple">
<li>Upgrade the shared repository.</li>
<li>Upgrade the branches.</li>
<li>Upgrade any lightweight checkouts.</li>
</ol>
<p>As in the standalone branch case, be sure to run <strong>check</strong> before
and after the upgrade to check for any existing or introduced issues.</p>
</div>
<div class="section" id="migrating-branches-on-launchpad">
<h3>Migrating branches on Launchpad<a class="headerlink" href="#migrating-branches-on-launchpad" title="Permalink to this headline">¶</a></h3>
<p>You have two options for upgrading your Launchpad branches. You can either
upgrade them remotely or you can upgrade them locally and push the migrated
branch to Launchpad. We recommend the latter. Upgrading remotely currently
requires a fast, rock solid network connection to the Launchpad servers, and
any interruption in that connection can leave you with a partially upgraded
branch. The instructions below are the safest and often fastest way to
upgrade your Launchpad branches.</p>
<p>To allow isolation between public and private branches, Launchpad
uses stacked branches rather than shared repositories as the core
technology for efficient branch storage. The process for migrating
to a new format for projects using Launchpad code hosting is therefore
different to migrating a personal or in-house project.</p>
<p>In Launchpad, a project can define a <em>development series</em> and associate a
branch with that series. The branch then becomes the <em>focus of development</em>
and gets special treatment and a shortcut URL. By default, if anybody
branches your project’s focus of development and pushes changes back to
Launchpad, their branch will be stacked on your development focus branch.
Also, branches can be associated with other Launchpad artifacts such as bugs
and merge proposals. All of these things mean that upgrading your focus of
development branch is trickier.</p>
<p>Here are the steps to follow:</p>
<ol class="arabic simple">
<li>The nominated person grabs a copy of trunk and does the migration locally.</li>
<li>On Launchpad, unset the current trunk from being the development focus.
(This <em>must</em> be done or the following step won’t work as expected.)<ol class="arabic">
<li>Go to your project’s home page on Launchpad</li>
<li>Look for “XXX is the current focus of development”</li>
<li>Click on the edit (pencil) icon</li>
<li>Click on “Change details” in the portlet on the right</li>
<li>Scroll down to where it says “Branch: (Optional)”</li>
<li>Blank out this input field and click “Change”</li>
</ol>
</li>
<li>Push the migrated trunk to Launchpad. See below if you want your
new migrated development focus branch to have the same name as your old
pre-migration development focus branch.</li>
<li>Set it as the development focus. Follow the instructions above but at step
5, enter the name of the newly migrated branch you just pushed.</li>
<li>Ask users subscribed to the old trunk to subscribe to the new one.</li>
</ol>
<p>In summary, these steps mean that the old trunk is still available and
existing branches stacked on it will continue to be so. However, the
development focus has switched to the migrated trunk and any new branches
pushed to Launchpad for your project will now stack on it.</p>
<p>You are now ready to tell your community that the new trunk is available
and to give them instructions on migrating any local branches they have.</p>
<p>If you want your new migrated development focus branch to have the same name
as your old pre-migration branch, you need to do a few extra things before you
establish the new development focus.</p>
<ol class="arabic simple">
<li>Rename your old pre-migration branch; use something like
<strong>foo-obsolete-do-not-use</strong>. You will really not want to delete this
because there will be artifacts (bugs, merge proposals, etc.) associated
with it.</li>
<li>Rename the new migrated branch to the pre-migration branch’s old name.</li>
<li>Re-establish the development focus branch using the new migrated branch’s
new name (i.e. the old pre-migration branch’s original name).</li>
</ol>
</div>
<div class="section" id="migrating-local-branches-after-a-central-trunk-has-migrated">
<h3>Migrating local branches after a central trunk has migrated<a class="headerlink" href="#migrating-local-branches-after-a-central-trunk-has-migrated" title="Permalink to this headline">¶</a></h3>
<p>To migrate a standalone branch:</p>
<ol class="arabic simple">
<li>Grab the latest branch from the central location into a
new directory.</li>
<li>Pull or merge any changes you’ve made in your existing branch
into the new branch.</li>
</ol>
<p>To migrate branches in a shared repository:</p>
<ol class="arabic simple">
<li>Create a fresh shared repository in the new format (2a or later).</li>
<li>Grab the latest branch from the central location into a
new directory inside the shared repository.</li>
<li>Decide which of your local branches you want to migrate. (If you
haven’t already, now’s a good time for <a class="reference internal" href="#finding-obsolete-branches">Finding obsolete branches</a>
and purging them, after backing up first of course.)</li>
<li>To migrate each local branch of interest, there are 2 options:</li>
</ol>
<blockquote>
<div><ul class="simple">
<li><strong>init</strong> an empty branch in the new repository and <strong>pull</strong> the
revisions from the branch in the old repository across.</li>
<li>In the new repository, <strong>branch</strong> from trunk to the new branch
name then <strong>merge</strong> your changes from the matching branch in the
old repository.</li>
</ul>
</div></blockquote>
<p>The first method will give you a branch which is identical (in terms of
revision history) to the old branch, but it’s parent branch will be set to the
old branch, not your new trunk. If you use this method, you’ll probably update
the <tt class="docutils literal"><span class="pre">parent_location</span></tt> configuration variable in the <tt class="docutils literal"><span class="pre">branch.conf</span></tt> file
with:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr config parent_location=XXX
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">XXX</span></tt> being the URL to your new trunk.</p>
<p>In contrast, the second approach sets up the parent branch correctly.
However, it isn’t ideal if you’re not ready to include all the latest
revisions from trunk into that branch yet.</p>
</div>
</div>
<div class="section" id="tips-and-tricks">
<h2>Tips and tricks<a class="headerlink" href="#tips-and-tricks" title="Permalink to this headline">¶</a></h2>
<div class="section" id="finding-obsolete-branches">
<h3>Finding obsolete branches<a class="headerlink" href="#finding-obsolete-branches" title="Permalink to this headline">¶</a></h3>
<p>If you use feature branching for developing each fix
and enhancement separately, you may have several old
branches that are no longer required. In many cases,
the relevant changes may now be merged into trunk.
In other cases, a branch may be obsolete thanks to
another change made by yourself or others.</p>
<p>When checking for an obsolete branch, there are three
things in particular to confirm:</p>
<ol class="arabic simple">
<li>The working tree has no in-progress changes.</li>
<li>The working tree has no shelved changes.</li>
<li>Any locally committed revisions have been merged
into the parent branch.</li>
</ol>
<p>After changing into the root of a branch, the commands
to check these things respectively are:</p>
<div class="highlight-python"><div class="highlight"><pre>bzr status
bzr shelve --list
bzr missing --mine-only
</pre></div>
</div>
<p>If your branches are stored in a shared repository locally,
you may find the <em>Local Changes</em> tab in Bazaar Explorer’s
repository view helpful here (revision 159 or later) as it
shows a summary of these things, excluding the shelve information
currently, for each branch as you select it.</p>
<div class="section" id="licence">
<h4>Licence<a class="headerlink" href="#licence" title="Permalink to this headline">¶</a></h4>
<p>Copyright 2009-2011 Canonical Ltd. Bazaar is free software, and you
may use, modify and redistribute both Bazaar and this document under
the terms of the GNU General Public License version 2 or later. See
<<a class="reference external" href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>>.</p>
</div>
</div>
</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 Upgrade Guide</a><ul>
<li><a class="reference internal" href="#overview">Overview</a><ul>
<li><a class="reference internal" href="#high-level-upgrade-process">High level upgrade process</a></li>
<li><a class="reference internal" href="#upgrading-the-core-software">Upgrading the core software</a></li>
<li><a class="reference internal" href="#upgrading-required-plugins">Upgrading required plugins</a></li>
<li><a class="reference internal" href="#migrating-data-to-the-new-default-format">Migrating data to the new default format</a></li>
</ul>
</li>
<li><a class="reference internal" href="#data-migration">Data migration</a><ul>
<li><a class="reference internal" href="#preparing-for-data-migration">Preparing for data migration</a></li>
<li><a class="reference internal" href="#introducing-the-upgrade-related-commands">Introducing the upgrade-related commands</a></li>
<li><a class="reference internal" href="#communicating-with-your-community">Communicating with your community</a></li>
<li><a class="reference internal" href="#migrating-a-standalone-branch">Migrating a standalone branch</a></li>
<li><a class="reference internal" href="#migrating-branches-in-a-shared-repository">Migrating branches in a shared repository</a></li>
<li><a class="reference internal" href="#migrating-branches-on-launchpad">Migrating branches on Launchpad</a></li>
<li><a class="reference internal" href="#migrating-local-branches-after-a-central-trunk-has-migrated">Migrating local branches after a central trunk has migrated</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tips-and-tricks">Tips and tricks</a><ul>
<li><a class="reference internal" href="#finding-obsolete-branches">Finding obsolete branches</a><ul>
<li><a class="reference internal" href="#licence">Licence</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../release-notes/bzr-0.1.html"
title="previous chapter">Bazaar Release Notes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../user-reference/index.html"
title="next chapter">Bazaar User Reference</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/upgrade-guide/index.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="../user-reference/index.html" title="Bazaar User Reference"
>next</a></li>
<li class="right" >
<a href="../release-notes/bzr-0.1.html" title="Bazaar Release Notes"
>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">Table of Contents (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>
