CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Requirements
 * Files
 * Setup
 * Performing the Migration
 * Miscellaneous
 * More Information

INTRODUCTION
------------

Current Maintainer: Shaun Haber <shaun.haber@wmg.com>

This directory contains necessary scripts to export content from a Drupal 5
database and import it into a Drupal 6 site. The migration phase is generally
broken into 3 separate steps: initializing, importing, and processing.

The initialization phase should only happen once, but the importing and
processing phases may be run multiple times. It is advisable to do a preliminary
run during site development to test for integration bugs, and to do a final
migration in the moments before a site relaunch.

REQUIREMENTS
------------

 * This script requires Drush. Drush is installed on our development and
   production servers. Our development server is wbrlabs.com. Our production
   server is mgmt1.p.wbrdc.com. To learn more about Drush, visit
   http://drupal.org/project/drush

 * Before the preliminary migration, a snapshot of the production site database
   needs to be setup on the dev server with the same db access credentials as
   the dev site.

 * Before the site launch, the production site must be put in a frozen state or
   be taken offline. At this time, a snapshot of the production database should
   be setup on the dev server with the same db access credentials as the dev
   site.

FILES
-----

An overview of the files contained in this directory:

  * config.ini - The configuration file in ini format.

  * config.inc - Code to parse the configuration file.

  * import.drush.php - The main script, invoked using the drush php-script command

  * process-example.inc - A example script to give an idea of the process phase.

  * process.inc - The placeholder script where you capture the post-import
    actions.

  * README - This file.

SETUP
-----

1. PROVISION THE NEW DEV SITE

   Setting up the new dev site should be the first thing that happens.
   Currently, this is done via a shell script on wbrlabs:

	   /home/wbrlabs/drupal6x/sites/mknew.sh <site-moniker>
	
	 This script will take care of most things including creating a project
   directory in Subversion, creating the dev database, and adding symbolic links
   to the dev environment.

   To finish the installation, visit:
   http://<site-moniker>.wbrdev.com/install.php.

2. COPY THE SCRIPT FILES TO A SPECIFIED LOCATION

   Place these files inside your site directory:

	   E.g., /home/wbrlabs/drupal6x/sites/<newsite>/d6migration
	
3. SETUP SNAPSHOT OF PRODUCTION SITE DATABASE
	
   Perform a mysqldump of the production site database and import it into the
   dev server. If this is the final migration, be sure to put the production
   site in a frozen site or maintenance mode beforehand. Example below:

		 # On production server
		 mysqldump prod_database | gzip > prod_database.sql.gz
		 scp prod_database.sql.gz wbrlabs@wbrlabs.com: # scp file to dev server
		 rm prod_database.sql.gz # Clean up
		
		 # On dev server
		 mysqladmin create prod_database
		 gunzip prod_database.sql.gz
		 mysql prod_database < prod_database.sql
		 rm prod_database.sql # Clean up
		
	 The production db snapshot requires access using the dev site's db 
	 connection.

4. EDIT CONFIG FILE WITH AUTO-INCREMENT VALUES

   Examine the production database snapshot and determine the auto-increment
   values for each table listed in the config.ini file. Consider the current
   site's age, acceleration of produced content, and the estimated date of
   launch of the new site in order to gauge appropriate values.

   Don't be afraid to add plenty of padding. The whole purpose of this is to
   prevent from encountering conflicts on sequenced IDs (they are a huge huge
   pain). You only get one chance to get this right, so be conservative and bump
   the number as high as you see fit.

   Enter the auto-increment values and the production snapshot DB name in the
   config.ini file. This file already contains default values for the
   auto-increments, but these values will vary between sites.

5. INITIALIZE THE DEV SITE

   Initialize the dev site by running drush.

     drush -l <site-moniker>.wbrdev.com php-script import.drush.php init

   This should be done soon after provisioning the site and before any content
   is input into the site. This step should only be performed once. Make sure
   the config.ini is configured correctly before doing this.

PERFORMING THE MIGRATION
------------------------

After following the steps in the setup phase, you will be ready to perform a
migration. The basic procedure goes:

1. COPY THE PRODUCTION DATABASE TO THE DEV SERVER

   This is the same as STEP 3 in the setup phase.

2. RUN THE IMPORT COMMAND FROM THE DRUSH SCRIPT

   The import command inserts or replaces data for the most common Drupal
   tables. See the corresponding __import() function.

     drush -l <site-moniker>.wbrdev.com php-script import.drush.php import

3. RUN ALL PROCESS COMMANDS FROM THE DRUSH SCRIPT

   There will usually be additional actions to perform on the imported content.
   A typical example is to append underscores to all user email addresses has a
   clever way to prevent rogue emails being sent from the dev server.

		 drush -l <site-moniker>.wbrdev.com php-script import.drush.php process
		 drush -l <site-moniker>.wbrdev.com php-script import.drush.php process_1
		 ...
		 drush -l <site-moniker>.wbrdev.com php-script import.drush.php process_N
		
   In the above example, there are multiple process commands. There is no naming
   convention for these, so it's up to you how to name them. All command names
   correspond to identical function names that have 2 prepended underscores. See
   the process-example.inc file.

4. WRITE CODE FOR ACTIONS ON IMPORTED DATA

   It is essential to capture any changes as code and encapsulate them in a
   function. The idea here to make everything repeatable so you can easily
   replay the changes when you perform another migration. Failure to do so means
   any changes will be lost when it comes time to do the final sync.
   
   You will gradually add code to the process.inc file as needed. You can choose
   to put all code in the single __process() function, or you may break it up
   into smaller meaningful functions. You'll need to run the drush php-script for
   each function you add. Function names should begin with 2 underscores. See
   the process-example.inc file.

MISCELLANEOUS
-------------

The physical files for the production site should be preserved and copied to the new site during launch.

	cd /NAS1/websites/drupal6x/sites/<newsite>
  cp -pR /NAS1/websites/drupal5x/sites/<oldsite>/files/* files/
  	
MORE INFORMATION
----------------

Documentation is available at https://docs.01detail.com/node/2026