Updating Drupal using SVN Vendor Branches

At ImageX Media all of our projects are managed through "Subversion (SVN)":http://svnbook.red-bean.com/. Most of our sites all share the same base (the latest version of "Acquia Drupal":http://acquia.com/, a few contributed modules all our sites use, and an install profile based on "packgr":http://drupal.org/project/packgr). For those of you who also manage your sites in SVN you know that simply copying the latest version of Drupal over top of the old version doesn't cut it. Even some "scripted methods":http://www.chapterthree.com/blog/matt_cheney/howto_upgrade_svn_managed_drupal_installation_without_cvs can be cumbersome if the changes are complex. This tutorial will show you how to setup Drupal as vendor branch in your subversion repository. This will allow you to apply changes that are made between versions without losing or overwriting contributed modules or patches that you may have made to your install of Drupal. In fact, if you're working on multiple Drupal projects you can have them all share the same base and security updates can be rolled out much easier. h3. Assumptions Before we dive in we need to be clear about a couple assumptions I am making about your current knowledge level and system setup. # I am assuming that you already have a Drupal site(s) that is managed in Subversion and that you are familiar with and have experience with the basic functions and workflow in Subversion. If you don't here are some place you might want to start: "Subversion for Designers":http://www.thinkvitamin.com/features/design/subversion-for-designers, "A Visual Guide to Version Control":http://betterexplained.com/articles/a-visual-guide-to-version-control/, "Version Control with Subversion":http://svnbook.red-bean.com/, and "Subversion Cheat Sheet":http://ariejan.net/upload/svncheatsheet-1.0.1.pdf. # These instructions assume that you have an instance of Drupal/Acquia Drupal that is out of date and needs to be upgraded. These steps don't really help until you have something to upgrade. # We run a version of Drupal called "Acquia Drupal":http://acquia.com/ which includes the core Drupal code, plus some very popular contributed modules that are used on almost every site we create. Despite that, these instruction work just fine with a normal install of Drupal and I will try to point out there differences when they apply. h3. Step 1: Downloading Drupal The process we are following essentially compares the changes that were made between two version of Drupal and then applies those changes to the trunk of our repository. Accordingly, we actually need to download two version of Drupal. The "latest version" which is the most up to date version of Drupal and the "historic version" of Drupal which is what your site is currently running. (As a point of illustration, if the latest version and historic version were the same the "changeset" that would result would be empty, but it would work theoretically.) *Acquia Drupal:* For those of you following along with Acquia Drupal. You can download the latest version from here: http://acquia.com/downloads and the historic version you are running from here: http://acquia.com/acquia-drupal-release-history (make sure to pick the historic version you are actually running). _Note that for each release there are two options, "New Install" and "Upgrade". I recommend using the "New Install", because this will keep track of changes to the settings and htaccess file which we may want to be aware of. Though choosing Upgrade would work just fine too; the key is to make sure to use the same version each time._ *Drupal:* For those of you following along with the vanilla version of Drupal you can download the latest copy from the Drupal homepage and you can find your current version from this page: http://drupal.org/node/3060/release Download & unpack both versions into a folder somewhere on your hard drive. h3. Step 2: Your Subversion Repository (Repo) Your repository structure needs to look something like this: /trunk /branches /tags /vendors I'll assume you have trunk folder or something with a similar purpose. If you don't have a branches and tags folder, its recommended but you can proceed with this tutorial without. If you don't have a "vendors" folder, go ahead and create it now. Next, add a subfolder to "vendors" either called "acquia" or "drupal" depending which version you are using. h3. Step 3: Importing the historic version Now, that the SVN repo structure is correct we need to import the historic version of Drupal (that is the version you're currently running your site on and is out of date). To start, bring up the command line and navigate so that you are in the same folder that your unpacked Drupal/Acquia folder is in. (Make sure to be outside of the Drupal/Acquia folder and not inside it). Then run the following command: svn import -m "Importing Acquia Drupal 1.1.0" acquia-drupal-1.1.0 https://svn.domain.com/reponame/vendors/acquia/current Let's unpack that. svn import is the command which imports un-versioned files into a repository at some location. -m "Importing Acquia Drupal 1.1.0" is the SVN log message which just keeps a record of what we are doing. You will need to change this to represent the version of Drupal which you are importing. acquia-drupal-1.1.0 this is the unpacked folder name of the Historical Version of drupal which you downloaded. https://svn.domain.com/reponame/ should be replaced with the URL of the SVN repository. vendors/acquia/current is the path to new a folder which we are creating, you will need to make sure it matches your own path, ie. you may have called it vendors/drupal instead. "current" is a new folder we are creating. We then want to follow that up by tagging what we have in current with the corresponding version number: svn copy https://svn.domain.com/reponame/vendors/acquia/current https://svn.domain.com/reponame/vendors/acquia/1.1.0 -m "Tagging the 1.1.0 release of the Acquia Drupal" You will need to change "1.1.0" to whatever version it relates to. h3. Step 4: Updating the Vendor Branch with the latest version 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":http://svn.collab.net/repos/svn/trunk/contrib/client-side/svn_load_dirs/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 (or make a copy of it an place it) in the same folder which your unpacked, downloaded version of Drupal are living. Then run the following: ./svn_load_dirs.pl https://svn.domain.com/reponame/vendors/acquia current acquia-drupal-1.1.1 -t 1.1.1 Let's take a look at that in more detail. https://svn.domain.com/reponame/vendors/acquia is the path to the acquia/drupal vendor branch. current is the folder in which the "latest version" will always live and is the folder which we are telling the script to make the changes to. acquia-drupal-1.1.1 is the local path to the latest version of Drupal. -t 1.1.1 tells the script to also tag the version we are importing with a specific version. 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. So now current we will have the following folders in our repository: vendors/acquia/current vendors/acquia/1.1.1 vendors/acquia/1.1.0 Where vendors/acquia/current and vendors/acquia/1.1.1 are essentially the same thing. h3. Step 5: Merging the changes into trunk If you haven't done so already you will need to check out a working copy of your repository's trunk onto your local machine. Once you have done so, change directories so that you are inside the trunk folder (also the root of the website and run the following): svn merge https://svn.domain.com/reponame/vendors/acquia/1.1.0 https://svn.domain.com/reponame/vendors/acquia/current . Here is what's happening: svn merge creates a changes set between the historic version (1.1.0) and the latest version (current) and applies those changes to the working copy. We then need to test that merge was successful and everything is working as we suspect. On our Drupal site we likely need to run update.php. If your satisified, then commit the changes: svn commit -m "Upgrading from Acquia Drupal 1.1.0 to 1.1.1" h3. Maintaining your Vendor Branch Now as new versions of Drupal come out you will need to download the latest version and repeat steps 5 and 6. Note that if you make a patch to your version of Drupal, it will be maintained because you are using the merge command. So you do not need to worry about contrib modules being removed or patches disappearing each time you upgrade.