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

[Jonathan Lange]

On Thu, Jun 11, 2009 at 3:42 PM, Robert
Collins<robert.collins at canonical.com> wrote:
> 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

Does "and" here mean "followed by"?

>    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.

I think it would be worth adding an example here.
e.g.

bzr init-repo (--<format> ???) new-repo
bzr branch old-repo/trunk new-repo/trunk

I've just read down to the bottom. AIUI the "if you have a shared
repo" clause is here to prevent people from putting their copy of
trunk into the same shared repo -- is this correct? If so, it's worth
adding some redundancy, e.g.
  If you have a shared repository, do not copy trunk into that same
repository. Instead, branch into a new shared repository or standalone
branch.

> * Run 'bzr upgrade --<format>' to upgrade to that format.
> * Run 'bzr check'. If there are errors, file a bug.
>

Since you refer to this section a bit, it might help to number these
steps so you can refer to them more clearly

> 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.

In the general case, this is not true.

Our data show that nearly all of the stacked branches on Launchpad are
for Canonical-sponsored projects. We've attributed this largely to
Bazaar using pack-0.92 as the default format.

> 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.
>

You've put "do a test migration" in quotes. If you're referring to the
first section, then it's clearer to match the heading exactly.

> 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.
>

This contradicts the spirit of the first sentence of "Schedule a
time". Is it true?

Also, as a general rule, words like "currently" should be avoided in
favour of more specific terms like "with Bazaar 1.16 or earlier".

> A backup should be taken of repositories/branches before backing up.
>
> Backup
> ======
>
> Take a full backup of your trunk and project branches.
>

Foolhardy devils like myself will need to be further warned: "Although
'bzr upgrade' makes a backup.bzr directory, this is likely to be
insufficient for full restoration."

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

Will the check command still have to check all of the old revisions again?

> 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.
>
>

When Launchpad upgraded to 1.6, many developers were confused by the
difference between upgrading a branch and upgrading a shared
repository. In particular, many of us forgot to upgrade every branch
we had.

Has upgrade's behaviour changed since then? Is it worth adding some
warnings along these lines to the document?

This is a great document, thanks for taking the time to draft it.

jml