Real live migration case

Here is how to upgrade a TurboGears 1.1 project to TurboGears 2.0

Outline

These are the steps we'll follow

1. create a working environment of the tg1 project
2. install tg2 on that environment
3. upgrade the project structure
4. upgrade the templates
5. upgrade the model
6. upgrading the controller
7. run under tg2
8. make it so that it will run on tg1 (maybe)

Use case

We'll use the excelent SpammCan pastebin-like app by Christopher Arndt

Project Structure

• spammcan [1]
  • SpammCan [2]
  • tg1-2 [3]
    • SpammCan [4]

1. simply a wrapper directory
2. An svn checkout of the code from svn://chrisarndt.de/projects/SpammCan/trunk
3. a virtualenv as in http://turbogears.org/2.0/docs/main/DownloadInstall.html#setting-up-a-virtual-environment
4. This will be different things, first a tg2 quickstart then a link to our original code in [1]

Setting the Environment

I actually cheated and used bazaar but that is because I found this as a great oportunity to test bzr-svn

So lets start with

$ cd spammcan
$ bzr branch svn://chrisarndt.de/projects/SpammCan/trunk SpammCan
$ cd tg1-2
$ source bin/acticate
$ ln -s ../SpammCan/ .
$ cd SpammCan
$ python setup.py develop

Testing our instalation

Now lets see if everything runs as expected::

$ bootstrap-spammcan $ start-spammcan $ firefox http://0.0.0.0:8080/

That should take you to http://0.0.0.0:8080/new and everything should work, go ahead and paste some spamm!

Installing TurboGears 2

So back to work, shut down cherrypy and let's install TG2 into the virtualenv::

$ easy_install -i http://www.turbogears.org/2.0/downloads/current/index tg.devtools

you may have to run::

$ easy_install -U setuptools

Upgrading our code structure

The steps we are going to follow are:

• create a tg2 project by the same name
• move all the files that are new
• move all the files that have changed place or name
• do changes to the files (imports and such)
• Do complex changes to the files

Now we will temporally delete our SpammCan project from the virtualenv and create a tg2 project by the same name, The reason we are doing this is to preserve the package name:

$ rm lib/python2.5/site-packages/SpammCan.egg-link
$ vi lib/python2.5/site-packages/easy-install.pth

In the last file we need to delete the line that contains SpammCan on it, it's a little tricky but unfortunaly setuptools doesn't have a command for this. Anyway if it did it will delete all our tg1 dependencies which we don't want.

Now On to the TG2 project:

$ cd ..
$ rm SpammCan
$ paster quickstart
Enter project name: SpammCan
Enter package name [spammcan]:
Do you need authentication and authorization in this project? [yes]

We'll reply yes to auth even if that isn't used fully in SpammCan to provide a more complete example.

$ meld ../SpammCan/ SpammCan/

$ cp ../SpammCan/spammcan/static/ ../SpammCan/spammcan/public -r
$ meld ../SpammCan/spammcan/public/ SpammCan/spammcan/public/

.. note :: We need to upgrade the TG2 quickstart with the new CSS layout from 1.1 and then add a section here on why it's so great

def setup_tg2(**kargs):
    pass

setup_tg2(...
)

$ cp model.py model/tg1.py
$ cp controllers.py controllers/tg1.py
$ vi controllers.__init__.py
    from controllers import *

$ vi model.__init__.py
    from model import *

Upgrading the template

This step is trivial if you are using genshi you just need to copy over the files. And your done

The only change you should probably do is master.html, which is documented below

Upgrading the model

We are going to split our model.py into two files auth.py and spamm.py, if you haven't done any changes to the auth code you can skip the auth.py part as that is 100% backwards compatible.

As for the rest of the code if you are already using SQLAlchemy you should just change some imports

turbogears.database.* doesn't exists anymore so you will have to import SQLAlchemy directly except for the metadata defined in your model.__init__.py

again we can use model.template as a base for our diff

turbogears.database.mapper -> sqlalchemy.orm.mapper turbogears.database.metadata -> p.model.metadata

TODO add a comment about SAClass.query

Upgrading the controller

We are going to try to keep things running for both TG1 and TG2 therefore all our code imports will happen in __init__.py and we could switch this to tg1 or tg2 controllers

The process here will be:

• copy the controller to a tg2 file (ticket #2075 provides a good template),
• run paster serve , see what fails
• fix the imports
• run paster serve
• fix other code

List of imports that changed

• turbogears.controllers -> p.lib.base.BaseController
• turbogears.expose -> tg.expose
• turbogears.flash -> tg.flash
• turbogears.redirect -> tg.redirect
• turbogears.validate -> tg.validate
• turbogears.url -> tg.url
• turbogears.validators -> formencode.validators
• turbogears.config -> turbogears.configuration
• cherrypy.request -> tg.request
• p.model.session -> p.model.DBSession

List of components that changed

• @error_handler isn't a decorator anymore but a parameter to validate
• identity -> repoze.who/what *
• cherrypy.request -> tg.request
• cherrypy.NotFound -> abort(404)
• SAclass.query -> p.model.DBSession.query *

for the running part we could trick setuptools like this:

def setup_tg2(**kargs):
   pass
def setup_tg1(**kargs):
   pass

#setup_tg2 = setup
setup_tg1 = setup

setup_tg2(...)

setup_tg1(...)

.. code-block ::
 from turbogears.view import variable_providers
 def add_global_tmpl_vars(vars):
   vars['motd'] = message_of_the_day()
   vars['abs_url'] = absolute_url
   vars['tg_version'] = tg_version

 variable_providers.append(add_global_tmpl_vars)

.. code-block ::
def add_global_tmpl_vars():
    return dict(
           motd = message_of_the_day(),
           abs_url = absolute_url,
           tg_version = tg_version
           )