Managing Silverstripe Upgrades In Your SVN Projects

Posted by Al on 29 July 2010 | 2 Comments

Tags: silverstripe, svn, svn_load_dirs, php

Let's face it: FTP is for the web developers of the '90's; real developers use SVN (or some other source control software).

If you haven't heard of SVN and you do any type of file editing at all, you're probably spending far too much time keeping track of changes to files, and having a horrible time of it trying to keep everyone up to date with what you've done lately. I suggest you read the svn book.

If you do use SVN to help manage your web development, sooner or later you'll run into the same stumbling block I've just come across:

I want to update the site I'm working on to Silverstripe version X.X, but...

Don't worry, mon ami. I know you might want to:

• Maintain site-specific hacks automagically without having to repatch every version
• Track the changes of Silverstripe files, as well as your own
• Pick and choose when to update your site
• Be able to update folders across many computers in one fell swoop

We have it all covered below. I learnt most of this from a site on a similar topic for Drupal, and modified it to suit Silverstripe and based on my experience. And without further interruption, I bring you the main article:

Setting up our SVN environment

First up, I'm going to assume you have some basic knowledge of SVN, and you have it all set up in your environment. If you don't, read the svn book I linked earlier. Also, I'm assuming you're using a terminal in a UNIX-like environment. If you're not, you shall have to translate this yourself as required.

We're using a feature of SVN known as Vendor Branches. Well, I say feature but it's really just a clever use of the generic features of SVN. Anyways, here's how it's done.

Step One: Create the folders where we want to go

Create a folder structure similar to the following (I set up a temporary working folder to put all this in):

./vendors/
    silverstripe/
        installer/
        modules/
        upgrades/

This allows us to store the full installer (to make it super easy to set up new sites), any external modules we use (so we can upgrade them as well), and the files needed to do upgrades of existing sites.

Step Two: Start populating the folders with our current version

We'll set up both the installer and the upgrades folder with the version we're running. The coolest way to do it is with SVN (of course):

svn export http://svn.silverstripe.com/open/phpinstaller/tags/2.4.0 ./vendors/silverstripe/installer/v2.4.0
mkdir ./vendors/silverstripe/upgrades/v2.4.0
cp ./vendors/silverstripe/installer/v2.4.0/{cms,googlesitemaps,sapphire} ./vendors/silverstripe/upgrades/v2.4.0/

Change the 2.4.0 for whatever version you're currently running.

Step Three: Get that sucker up there!

Now, we're going to upload that folder into our SVN repository. That's going to create a new structure in the root (alongside tags, branches, and trunk) called vendors. We're also going to keep it nice and organised by having a folder for each version, as well as a folder that links to the current version. We can do that in a few easy commands:

svn import vendors http://svn.hol.net.nz/projects/vendors/ -m "Importing Silverstripe vendor release"
svn copy http://svn.hol.net.nz/projects/vendors/silverstripe/installer/v2.4.0 http://svn.hol.net.nz/projects/vendors/silverstripe/installer current -m "Tagging the 2.4.0 release of Silverstripe as current"
svn copy http://svn.hol.net.nz/projects/vendors/silverstripe/upgrades/v2.4.0 http://svn.hol.net.nz/projects/vendors/silverstripe/upgrades current -m "Tagging the 2.4.0 upgrade of Silverstripe as current"

Again, change the version and the url to match your setup. Don't try and use the exact link above or your computer might explode - you have been warned!

Step Four: Cleanup

Get rid of your working directory for now - we don't need the full structure anymore

rm -rf ./vendors

Working with our vendor branch

Now that we've set up this vendor branch, setting up a new website based on the current version of Silverstripe we have here is incredibly easy:

svn copy http://svn.hol.net.nz/projects/vendors/silverstripe/installer/v2.4.0 http://svn.hol.net.nz/projects/clientsite.co.nz/staging -m "Setting up new Silverstripe website"
svn co http://svn.hol.net.nz/projects/clientsite.co.nz/staging /my/local/server/files/clientsite.co.nz

In the example I gave I store all my client's websites under their domain name, and in either ./staging or ./live, based on the status of the code.

Upgrading Silverstripe

So, a new release of Silverstripe has come out, with a bunch of bug fixes and new features that we really want. However, in some of our projects we've changed some of the core files to twist the site to our unique application (I know it's not best practice, but it happens). Lets get our site up to date with the least hassle possible.

Step One: Download the core module files

We don't need the full installer in this case as we are upgrading our sites. So we'll download the three modules that are distributed separately.

svn export http://svn.silverstripe.com/open/modules/cms/tags/2.4.1/ ss-2.4.1/cms
svn export http://svn.silverstripe.com/open/modules/googlesitemaps/tags/0.1.5/ ss-2.4.1/googlesitemaps
svn export http://svn.silverstripe.com/open/modules/sapphire/tags/2.4.1/ ss-2.4.1/sapphire

Note you can see the individual versions of the modules by checking the svn:externals properties for the installer (easiest way is to browse to http://open.silverstripe.org/browser/phpinstaller/tags/2.4.1)

Step Two: Update the vendor branch

To do this next step we need a file called "svn_load_dirs.pl" which generally comes with SVN. If you can’t find it search for "svn_load_dirs.pl.in" and rename it "svn_load_dirs.pl". If you can’t find that either you can download svn_load_dirs.pl.in and rename it "svn_load_dirs.pl" You may need to edit the file to point it to the location where "svn" lives. To find out where svn lives type (usually '/usr/bin/svn'):

which svn

Then change the line that reads:

my $svn = '@SVN_BINDIR@/svn';

to

my $svn = '/usr/bin/svn';

Place that script somewhere handy, then run

/path/to/svn_load_dirs.pl http://svn.hol.net.nz/projects/vendors/silverstripe/upgrades/ current ss-2.4.1 -t v2.4.1 _no_auto_exe

This script will look at a (source) set of files in an svn repository, compare it to a (destination) set of files, and then automate whatever adds, changes, and deletes are necessary to make the source like the destination. It will check the changes in for you, and it will tag the changeset for you. We add the -no_auto_exe option to stop it from incorrectly thinking a lot of the files have svn:executable set. You will get a list of files deleted and added and are given the opertunity to specify them as simply being moved - this is optional. So now we will have the following folders in our repository:

http://svn.hol.net.nz/projects/vendors/silverstripe/upgrades/current
http://svn.hol.net.nz/projects/vendors/silverstripe/upgrades/v2.4.1
http://svn.hol.net.nz/projects/vendors/silverstripe/upgrades/v2.4.0

Note that current and v2.4.1 are essentially the same.

You probably also want to update the installer files. I like to keep this fresh and pristine, with no trace of previous versions, so I'd usually run through the following commands:

svn rm http://svn.hol.net.nz/projects/vendors/silverstripe/installer/current -m "Making way for new installer version"
svn export http://svn.silverstripe.com/open/phpinstaller/tags/2.4.1 ss-installer-2.4.1
svn import ss-installer-2.4.1/ http://svn.hol.net.nz/projects/vendors/silverstripe/installer/v2.4.1 -m "Uploading SS 2.4.1"
svn copy http://svn.hol.net.nz/projects/vendors/silverstripe/installer/v2.4.1 http://svn.hol.net.nz/projects/vendors/silverstripe/installer/current -m "Tagging SS 2.4.1 as current"

Step Thee: Update your sites

You can do this on each of your sites as and when you are ready. You'll need to check out your site's working directory if you haven't already done so.

svn co http://svn.hol.net.nz/projects/clientsite.co.nz/staging clientsite.co.nz

Now we will merge the differences between v2.4.0 and v2.4.1 into our client's site.

cd clientsite.co.nz
svn merge http://svn.oxynet.co.nz/projects/vendors/silverstripe/upgrades/v2.4.0 http://svn.oxynet.co.nz/projects/vendors/silverstripe/upgrades/current .

Don't forget the '.' at the end - it's kinda important.

Now, if you have modified any of the core files you may have to resolve conflicts before you can commit the client's code back into SVN. This is done as normal (again, check the svn book if you need help).

Make sure you test the site, do the /dev/build and everything else specified in the upgrade notes.

Finally, when we're happy we commit our changes back to SVN.

svn commit -m "Upgraded clientsite.co.nz from SS 2.4.0 to SS 2.4.1"