[RFC][DRAFT] Updated guide for upgrading to rich-roots [and the 2.0 beta formats]

[Robert Collins]

Upgrading to a rich root or 2.0 format
++++++++++++++++++++++++++++++++++++++

Overall process
===============

* Test that your code migrates
* Schedule a migration time and tell all users
* Users migrate in advance of trunk
* Backup
* Migrate
* Rollback if necessary

Test migration
==============

* Run 'bzr check'.  If there are errors try
  * 'bzr reconcile' and 'bzr check' to see if they are known
    issues bzr can fix
  * Otherwise file a bug at https://bugs.launchpad.net/bzr
* Take a copy of trunk now that it is clean. If you have a shared
repository you need to branch into a new shared repository or standalone
branch before doing the upgrade.
* Run 'bzr upgrade --<format>' to upgrade to that format.
* Run 'bzr check'. If there are errors, file a bug.

Schedule a time
===============

All stacking branches *must* upgrade before your trunk branch (or
whatever branch they stacked on). So its very important to give users
plenty of time to upgrade. If you have a tight knit community or are not
using stacked branches you can likely do this in 24 hours or so. If the
community is more widespread leave more time. If you are using launchpad
you will be using stacked branches. Launchpad cannot yet upgrade these
for you, and once upgraded a stacked branch cannot be used until the
trunk upgrades - another key reason to advertise this process widely.

Users migrate
=============

Users should follow the 'do a test migration' instructions for each
branch they have. 

If branches fail, file bugs and the user should alert the coordinator
that the migration can't go ahead.

If you have stacked branches, you currently cannot migrate.

A backup should be taken of repositories/branches before backing up.

Backup
======

Take a full backup of your trunk and project branches.

Migrate
=======

* Follow the migration checklist again (new commits need checking too).
Instead of copying before upgrading though, just upgrade in-place.

Rollback
========

* Check things are working well for all users. If not, rollback before
people start committing in the new format: once they start you cannot
roll back.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20090611/4b9f6a90/attachment.pgp