Using Subversion externals property for WordPress upgrades

I find that upgrading apps like WordPress, Drupal, Symfony and open source PHP apps is simple for less complicated environments, but once you start adding in things like new directories, custom themes/modules, source code control as well as separate development, test, and production systems, the upgrades start to get pretty hairy.

Take WordPress for example. A typical upgrade of WordPress involves copying the new WordPress files over your existing files. Then you have to copy back safe versions of things like wp-config.php, .htaccess (if you're using it), as well as any custom themes/modules from the wp-content/ directory. Not to mention any of your own directories that should exist alongside your wp-includes/ and wp-content/ directories. After that you can run the upgrade.php file.

These upgrade steps aren't terrible. They're quite a bit better then most open source apps out there but they still suffer from a few problems:

1. If you have your code, including your WordPress install, in Subversion or another source code control system, you have to commit all the files that change with each WordPress version. There may be files added, deleted, etc. You'll have to keep combing thru "svn status" messages to figure out everything you need to do to get all the WordPress files into your repository. This can be painful. And take a long time.
2. WordPress is specifically written so that you don't ever have to muck with the guts of it. You create themes and plugins for added functionality. So, since you're not maintaining the code that powers WordPress, do you really need all those deltas in your Subversion repository? I think not.
3. What do you do with your own code in directories that sits alongside wp-includes/? What if it’s in a Subversion repo?

The WordPress site also has instructions for using Subversion with your site. Here, they advocate the use of “svn switch” to update your site. This is much more manageable and solves a few of the above problems. Most svn users can probably can get away with this method. But unfortunately not me.

I have additional directories on some of my sites that I need to add into my WordPress install. So I have to copy/move them into the WordPress dirs which gets tough. And then my “svn status” will get all wonky because my WordPress dir is under one repo and my code is under another. This was endlessly confusing for me.

So I found myself looking for a way to completely wall off my WordPress install from the rest of my files. I was reminded recently of the use of the Subversion externals property and my mind started buzzing with possibilities. With "externals," I can say:

Pull the stable WordPress code from WordPress.org and put it into this directory named /docs/wp/

Then my other directories, which are under my own local subversion repo can exist at /docs/dir1, /docs/dir2, etc. Of course, some Apache Alias magic is needed to make all this work.

Here's the way I set it up for my some of my projects. So far so good. This is a bit hairy to set up but subsequent upgrades are a breeze. I use this across development, testing, and production systems (how to get those environments to work with WordPress will be another entry)

First off, the previous Apache document root for domain1 was at /www/domain1/docs, so the WordPress files wound up like this:

/www/domain1/docs/wp-content/
/www/domain1/docs/wp-includes/

But I also have a lot of dirs that sit alongside of wordpress like this:

/www/domain1/docs/dir1
/www/domain1/docs/dir2

We're going to wind up changing that.

Create an subversion external property in /www/domain1/docs for WordPress
[code]
$$ cd /www/domain1/docs
$$ export SVN_EDITOR=vi ( or your editor of choice )
$$ svn propedit svn:externals .
[/code]
vi starts up and you can add the following line:

[code]wp http://svn.automattic.com/WordPress/tags/2.3.3[/code]

Save and exit
[code]$$ svn commit
$$ svn update [/code]

( This downloads the WordPress code from the above address into your wp/ directory. Now we are cooking. )

• Now, /www/domain1/docs/wp is where all your WordPress code lives.
• Copy wp-config.php to /www/domain1/docs/wp/
• Copy .htaccess to /www/domain1/docs/wp/
• Create a link from the stock wp-content/ dir to your personal wp-content dir like this

[code]$$ cd /www/domain1/docs/wp
$$ rm -Rf wp-content/ ( use -Rf with care please! )
$$ ln -s /www/domain1/docs/wp-content wp-content
[/code]

• In Apache config, set document root for this domain to /www/domain1/docs/wp
• Put wp-content/ dir and any other non-WordPress dirs/files into /www/domain1/docs
• Create an alias for wp-content/ and any other non-WordPress dirs/files in Apache config

[code]
Alias /wp-content /www/domain1/docs/wp-content
Alias /dir1 /www/domain1/docs/dir1
Alias /dir2 /www/domain1/docs/dir2
[/code]
This looks like a lot of work, but it's really only a lot the first time around. Next time WordPress has an upgrade:
[code]
$$ cd /www/domain1/docs
$$ svn propedit svn:externals . ( change the tag to new version of WordPress )
$$ cd wp/
$$ rm wp-content (to remove the link)
$$ svn update (to update to new version of WordPress)
$$ rm -Rf wp-content/
$$ ln -s /www/domain1/docs/wp-content wp-content
[/code]

Everything after the propedit in this group can and should be scripted which will basically give you a 2 step process for upgrading WordPress, while keeping you wp-content/ dir under local source code control, as well as leaving room for any other directories or files your site might require.

This technique will probably also work with Symfony although I haven’t tried it yet.