Rev 4529: (igc) Bazaar 2.0 Upgrade Guide in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Mon Jul 13 09:08:08 BST 2009
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 4529 [merge]
revision-id: pqm at pqm.ubuntu.com-20090713080805-x2kz90cdzjwdegpc
parent: pqm at pqm.ubuntu.com-20090713044713-6aura7n13gurrfuy
parent: ian.clatworthy at canonical.com-20090713070824-9ox0sfnj116pvqp1
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2009-07-13 09:08:05 +0100
message:
(igc) Bazaar 2.0 Upgrade Guide
added:
doc/en/upgrade-guide/ upgradeguide-20090702082510-q2pocf7uhntljqnl-1
doc/en/upgrade-guide/data_migration.txt data_migration.txt-20090702082510-q2pocf7uhntljqnl-2
doc/en/upgrade-guide/index.txt index.txt-20090702082510-q2pocf7uhntljqnl-3
doc/en/upgrade-guide/overview.txt overview.txt-20090702082510-q2pocf7uhntljqnl-4
doc/en/upgrade-guide/tips_and_tricks.txt tips_and_tricks.txt-20090702082510-q2pocf7uhntljqnl-5
modified:
Makefile Makefile-20050805140406-d96e3498bb61c5bb
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/index.txt index.txt-20070813101924-07gd9i9d2jt124bf-1
=== modified file 'Makefile'
--- a/Makefile 2009-06-29 11:02:31 +0000
+++ b/Makefile 2009-07-13 06:04:28 +0000
@@ -90,6 +90,9 @@
$(wildcard doc/*/user-guide/index.txt) \
$(derived_txt_files) \
doc/en/developer-guide/HACKING.txt \
+ doc/en/upgrade-guide/index.txt \
+ $(wildcard doc/es/guia-usario/*.txt) \
+ doc/es/mini-tutorial/index.txt \
doc/index.txt \
$(wildcard doc/index.*.txt)
non_txt_files := \
@@ -178,6 +181,11 @@
man1/bzr.1: $(MAN_DEPENDENCIES)
PYTHONPATH=.:$$PYTHONPATH $(PYTHON) tools/generate_docs.py -o $@ man
+upgrade_guide_dependencies = $(wildcard $(addsuffix /*.txt, doc/en/upgrade-guide))
+
+doc/en/upgrade-guide/index.html: $(upgrade_guide_dependencies)
+ $(rst2html) --stylesheet=../../default.css $(dir $@)index.txt $@
+
# build a png of our performance task list
#
# this is no longer built by default; you can build it if you want to look at it
=== modified file 'NEWS'
--- a/NEWS 2009-07-13 04:47:13 +0000
+++ b/NEWS 2009-07-13 08:08:05 +0000
@@ -19,18 +19,20 @@
Bug Fixes
*********
-Internals
-*********
-
Improvements
************
Documentation
*************
+* Added Bazaar 2.0 Upgrade Guide. (Ian Clatworthy)
+
API Changes
***********
+Internals
+*********
+
bzr 1.17rc1 "So late it's brunch" 2009-07-13
############################################
=== added directory 'doc/en/upgrade-guide'
=== added file 'doc/en/upgrade-guide/data_migration.txt'
--- a/doc/en/upgrade-guide/data_migration.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/upgrade-guide/data_migration.txt 2009-07-03 05:22:27 +0000
@@ -0,0 +1,167 @@
+Data migration
+##############
+
+Preparing for data migration
+----------------------------
+
+Before starting a migration, there are a few important things to do
+first:
+
+1. Take a complete backup.
+
+2. Take some time to purge obsolete branches.
+
+A complete backup gives you a safety net in case anything goes wrong.
+
+Purging obsolete branches reduces the amount of data that needs to
+be migrated. See `Finding obsolete branches`_ later for some tips
+on doing this.
+
+
+Introducing the upgrade-related commands
+----------------------------------------
+
+There are 3 important commands to be aware of when migrating data.
+
+* **check** - check a repository, branch or tree for data integrity errors
+
+* **reconcile** - fix data integrity errors
+
+* **upgrade** - migrate data to a different format.
+
+**reconcile** is rarely needed but it's good practice to run **check**
+before and after runing **upgrade**.
+
+For detailed help on these commands, see the `Bazaar User Reference`_.
+
+.. _Bazaar User Reference: ../user-reference/bzr_man.html
+
+
+Communicating with your community
+---------------------------------
+
+To enable a smooth transistion to the new format, you should:
+
+1. Make one person responsible for migrating the trunk.
+
+2. Test the migration of trunk works successfully.
+
+3. Schedule a time for the trunk migration and notify your community
+ in advance.
+
+This advance warning should be long enough for users to have time
+to upgrade Bazaar and any required plugins before the migration date.
+
+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.
+
+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.
+
+
+Migrating a standalone branch
+-----------------------------
+
+The steps are:
+
+1. Run **bzr check**.
+
+2. If there are errors, try using **bzr reconcile** 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.
+
+2. Run **bzr upgrade --format** where *format* is 2a or later.
+
+3. Run **bzr check** to confirm the final result is good.
+
+
+Migrating branches in a shared repository
+-----------------------------------------
+
+Upgrade things in the following order:
+
+1. Upgrade the shared repository.
+2. Upgrade the branches.
+3. Upgrade any lightweight checkouts.
+
+As in the standalone branch case, be sure to run **check** before
+and after the upgrade to check for any existing or introduced issues.
+
+
+Migrating branches on Launchpad
+-------------------------------
+
+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.
+
+Here are the steps to follow:
+
+1. The nominated person grabs a copy of trunk and does the migration.
+
+2. On Launchpad, unset the current trunk from being the development focus.
+ (This *must* be done or the following step won't work as expected.)
+
+3. Push the migrated trunk to Launchpad.
+
+4. Set it as the development focus.
+
+5. Ask users subscribed to the old trunk to subscribe to the new one.
+
+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.
+
+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.
+
+
+Migrating local branches after a central trunk has migrated
+-----------------------------------------------------------
+
+To migrate a standalone branch:
+
+1. Grab the latest branch from the central location into a
+ new directory.
+
+2. Pull or merge any changes you've made in your existing branch
+ into the new branch.
+
+To migrate branches in a shared repository:
+
+1. Create a fresh shared repository in the new format (2a or later).
+
+2. Grab the latest branch from the central location into a
+ new directory inside the shared repository.
+
+3. Decide which of your local branches you want to migrate. (If you
+ haven't already, now's a good time for `Finding obsolete branches`_
+ and purging them, after backing up first of course.)
+
+4. To migrate each local branch of interest, there are 2 options:
+
+ * **init** an empty branch in the new repository and **pull** the
+ revisions from the branch in the old repository across.
+
+ * In the new repository, **branch** from trunk to the new branch
+ name then **merge** your changes from the matching branch in the
+ old repository.
+
+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 want to edit your branch.conf file to update the
+parent branch setting.
+
+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.
=== added file 'doc/en/upgrade-guide/index.txt'
--- a/doc/en/upgrade-guide/index.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/upgrade-guide/index.txt 2009-07-13 06:58:49 +0000
@@ -0,0 +1,17 @@
+########################
+Bazaar 2.0 Upgrade Guide
+########################
+
+.. Please mark sections in included files as following:
+.. level 1 ========
+.. level 2 --------
+.. level 3 ~~~~~~~~
+.. level 4 ^^^^^^^^ (it is better not to use nesting deeper than 3 levels)
+
+.. contents:: :depth: 2
+.. sectnum::
+
+
+.. include:: overview.txt
+.. include:: data_migration.txt
+.. include:: tips_and_tricks.txt
=== added file 'doc/en/upgrade-guide/overview.txt'
--- a/doc/en/upgrade-guide/overview.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/upgrade-guide/overview.txt 2009-07-13 06:58:49 +0000
@@ -0,0 +1,90 @@
+Overview
+########
+
+High level upgrade process
+--------------------------
+
+In broad terms, there are 3 steps involved in upgrading to Bazaar 2.x:
+
+1. Upgrade the core software
+
+2. Upgrade required plugins
+
+3. Migrate data to the new default format.
+
+Bazaar 2.x supports branches in earlier formats so the third step is
+strictly not required. However, the new default format in Bazaar 2.x
+is more space efficient, faster on large projects and provides a range
+of new features, so it is recommended that most projects migrate to it
+at a convenient time.
+
+For most users, upgrading to 2.x 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.
+
+
+Upgrading the core software
+---------------------------
+
+The steps required to upgrade the core software vary from operating
+system to operating system. There is nothing special about upgrading
+from Bazaar 1.x to Bazaar 2.0 compared to upgrading from Bazaar 1.x
+to Bazaar 1.y. In either case, a brief outline of the steps is given
+below.
+
+To upgrade Bazaar on Linux:
+
+1. Ensure your package manager is configured with the required
+ software sources, e.g. the official release PPA for Ubuntu:
+ https://launchpad.net/~bzr/+archive
+
+2. Use your package manager to upgrade to the latest version.
+
+To upgrade Bazaar on Windows:
+
+1. Uninstall the existing version using Add/Remove Programs.
+
+2. Install the new version using the relevant installer.
+
+To upgrade Bazaar on OS X (via the installer):
+
+1. Install the new version using the relevant installer.
+
+To upgrade Bazaar on OS X (via MacPorts):
+
+1. Refresh the package metadata using **sudo port selfupdate**
+
+2. Upgrade to the latest version using **sudo port upgrade bzr**
+
+For further information on installing and upgrading, see
+http://bazaar-vcs.org/Download.
+
+
+Upgrading required plugins
+--------------------------
+
+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.
+
+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 Linux and UNIX 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.
+
+
+Migrating data to the new default format
+----------------------------------------
+
+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.
=== added file 'doc/en/upgrade-guide/tips_and_tricks.txt'
--- a/doc/en/upgrade-guide/tips_and_tricks.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/upgrade-guide/tips_and_tricks.txt 2009-07-13 06:58:49 +0000
@@ -0,0 +1,35 @@
+Tips and tricks
+###############
+
+Finding obsolete branches
+-------------------------
+
+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.
+
+When checking for an obsolete branch, there are three
+things in particular to confirm:
+
+1. The working tree has no in-progress changes.
+
+2. The working tree has no shelved changes.
+
+3. Any locally committed revisions have been merged
+ into the parent branch.
+
+After changing into the root of a branch, the commands
+to check these things respectively are::
+
+ bzr status
+ bzr shelve --list
+ bzr missing --mine-only
+
+If your branches are stored in a shared repository locally,
+you may find the *Local Changes* 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.
=== modified file 'doc/index.txt'
--- a/doc/index.txt 2009-06-01 22:45:06 +0000
+++ b/doc/index.txt 2009-07-02 08:26:00 +0000
@@ -19,6 +19,8 @@
* `Release Notes <en/release-notes/NEWS.html>`_
+* `2.0 Upgrade Guide <en/upgrade-guide/index.html>`_
+
* `Developer Document Catalog <developers/index.html>`_ |--| for developers
of Bazaar and plugins
More information about the bazaar-commits
mailing list