Merge lp:~zaber/openupgrade-server/6.1-docs into lp:openupgrade-server/6.1

[Don Kirkby]

Question 208187 reminded me that the documentation never explicitly spells out the steps required to run a migration. This is my attempt to spell it out at the end of the introduction.

[Stefan Rijnhart (Opener) (stefan-opener)]

Hi Don,

thank you for being involved with the project and picking this up!

I have made some suggestions here, tell me what you think:

https://code.launchpad.net/~therp-nl/openupgrade-server/6.1-migration-howto-additions/+merge/123687

Cheers,
Stefan.

[lp:~zaber/openupgrade-server/6.1-docs]

3992. By Don Kirkby on 2012-09-11

Merge Stefan's suggestions for migration steps.

[Don Kirkby (donkirkby)]

Good suggestions, Stefan. I merged them in.

[Stefan Rijnhart (Opener) (stefan-opener)]

Merged. Thanks again!

review: Approve

=== modified file 'openerp/openupgrade/doc/source/intro.rst'
--- openerp/openupgrade/doc/source/intro.rst	2012-06-06 09:13:43 +0000
+++ openerp/openupgrade/doc/source/intro.rst	2012-09-11 19:12:21 +0000
@@ -18,3 +18,38 @@
 Apart from a collection of migration scripts, this project aims at providing developers with a set of tools that they can use to extract the changes that their migration scripts need to cover. You can read more on that in the :doc:`analysis` section.
 
 Please do not use the OpenUpgrade software to run a live instance of your OpenERP database. It is not maintained for that purpose. Use the official OpenERP software for that.
+
+Migrating Your Database
+=======================
+
+1. Check out the OpenUpgrade source code from Launchpad for the branches you
+   need. Each branch migrates to its version from the previous version, so
+   branch 6.0 migrates from 5.0 to 6.0. If you are skipping versions, you still
+   need to run all the branches in between.
+
+2. Compare your set of installed modules with the modules that are covered by
+   the OpenUpgrade Addons branch you are using. Upgrading a database that has
+   uncovered modules installed is likely to fail. Authoritative in this respect
+   is the existence and contents of a *user_notes.txt* file in the
+   migrations/[version] subdirectory of each module. We also try to indicate
+   module coverage in the documentation but it sometimes lags behind.
+
+3. Decide which database you are going to upgrade. You absolutely *must* make a
+   backup of your live database before you start this process!
+
+4. Edit the configuration files and command line parameters to point to the
+   database you are going to upgrade. The parameters will probably be the same
+   as you use on your live server, except they point to the OpenUpgrade
+   addons source code, point to the database you want to upgrade, and add the
+   *--update all --stop-after-init* flags.
+
+5. Run the upgrade and check for errors. You will probably learn a lot about
+   your data and have to do some manual clean up before and after the upgrade. 
+   Expect to repeat the process several times as you encounter errors, clean up
+   your data, and try again. If necessary, ask for help or report bugs on
+   Launchpad.
+
+6. Once the data migration is successful, run the official version of OpenERP
+   against it to test how the migrated data behaves under the new version. 
+   Remember that the OpenUpgrade version of the source code is only intended to 
+   perform the migration, not run the OpenERP server.