At file:///home/pqm/archives/thelove/bzr/%2Btrunk/ ------------------------------------------------------------ revno: 4529 [merge] revision-id: [email protected] parent: [email protected] parent: [email protected] committer: Canonical.com Patch Queue Manager <[email protected]> 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 -- bazaar-commits mailing list [email protected] https://lists.ubuntu.com/mailman/listinfo/bazaar-commits
