Rev 4894: (nmb) Add migration section to admin-guide in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 4894 [merge]
revision-id: pqm at pqm.ubuntu.com-20091214121014-5j9tx0x9tr1dkyh5
parent: pqm at pqm.ubuntu.com-20091214111344-g3sb77go2xfy1nby
parent: nmb at wartburg.edu-20091207182900-svd2gf4wdrezw377
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2009-12-14 12:10:14 +0000
message:
  (nmb) Add migration section to admin-guide
modified:
  doc/en/admin-guide/migration.txt migration.txt-20091205144603-lgpl0e0z6lzk2rdw-8
=== modified file 'doc/en/admin-guide/migration.txt'
--- a/doc/en/admin-guide/migration.txt	2009-12-07 18:12:21 +0000
+++ b/doc/en/admin-guide/migration.txt	2009-12-07 18:29:00 +0000
@@ -1,8 +1,73 @@
 Migration
 =========
 
+Migrating between version control systems can be a complicated process, and
+Bazaar has extensive documentation on the process at 
+http://doc.bazaar-vcs.org/migration/en and we won't attempt to repeat that
+here.  We will try to give a few motivating examples for conversion from
+Mercurial and Subversion.
+
 Fast Import
 -----------
 
+In many projects wishing to use Bazaar, there is pre-existing history for the
+codebase that should be taken into consideration.  Bazaar leverages an
+interchange format originally developed for Git called `fast-import` to
+provide migration strategies for many other version control systems.  To
+work with fast-import files, Bazaar needs the `fastimport`_ plugin.  This can
+be installed as with any Bazaar plugin.
+
+.. _fastimport: http://launchpad.net/bzr-fastimport
+
+The way that fast-import can be used for migration is to export the existing
+history into a fast-import file, then use the ``bzr fast-import`` command.
+The `fastimport` plugin includes exporters for Subversion, CVS, Git, Mercurial
+and darcs, accessible as the ``fast-export-from-XXX`` commands.  Note that
+``fast-import`` should not be used in a branch with existing history.
+
+Assuming that ProjectX was first developed in Mercurial before switching to
+Bazaar, and that the Mercurial repository is in ``/srv/hg/projectx``, the
+following commands will import that history into a newly created ``trunk``
+branch.  (Recall that in `Further Configuration
+<simple-setups.html#further-configuration>`_ we created the
+``/srv/bzr/projectx`` directory as a shared repository.)
+
+::
+
+  $ cd /srv/bzr/projectx
+  $ bzr fast-export-from-hg ../../hg/projectx projectx.fi
+  $ bzr init trunk
+  $ bzr fast-import projectx.fi trunk
+
 Subversion Conversion
 ---------------------
+
+As the most common centralized version control system, migration from
+Subversion is particularly important for any *new* version control system.
+Bazaar's `svn`_ plugin provides tools for interaction with Subversion
+projects.  In fact, Bazaar can be used transparently with projects stored in
+Subversion, but that is beyond the scope of this document.  (See
+http://doc.bazaar-vcs.org/en/migration/foreign/bzr-on-svn-projects.html for
+more on that subject.)  What is relevant here is the ``svn-import`` command
+provided by that plugin.  This can import an entire subversion repository
+including tags and branches, particularly if they are stored in Subversion's
+recommended directory structure: ``/tags/``, ``/branches/`` and ``/trunk/``.
+
+This command has flexible ways to specify what paths within the Subversion
+repository contain branches and which contain tags.  For example, the
+recommended layout for Subversion projects (called ``trunk`` by the svn
+plugin) could be specified in ``~/.bazaar/subversion.conf`` as
+
+::
+
+  [203ae883-c723-44c9-aabd-cb56e4f81c9a]
+  branches = branches/*
+  tags = tags/*
+
+This allows substantially complicated Subversion repositories to be converted
+into a set of separate Bazaar branches.  After installing the svn plugin, see
+``bzr help svn-import`` and ``bzr help svn-layout``.
+
+.. _svn: http://launchpad.net/bzr-svn
+
+.. TODO: Legacy VCS to bzr sync.  Tailor?  Incremental conversions?