Tips for upgrading an existing site to a Drupal distribution

A current project we're working on at Chocolate Lily involves upgrading a Drupal 6 site to use the Drupal 7 Open Outreach distribution. It's the first time we've used a Drupal distribution for an existing Drupal site instead of a new one. Having worked on my share of hairy Drupal upgrade projects, I went into this project with a fair bit of apprehension.

But I've been pleasantly surprised. The basic upgrade process was relatively quick and painless.

As we went I wrote up some notes on how to upgrade an existing site to Open Outreach. Here I'll generecize that a bit to answer the question: how do you upgrade an existing site to use a Drupal distribution?

Fresh install or upgrade?

Drupal distributions are usually used as a starting point for developing a new website. The most straightforward way to use a distribution is to install it from scratch. From there, you can selectively migrate in content from other sources, including one or more existing websites. Migrating data here might be as simple as copying and pasting several pages from an old site into the new site. For larger sites, it could involve writing custom migration scripts or using an existing Drupal module like Migrate or Feeds.

If you already have a Drupal website that has a considerable amount of content or a large number of users or has custom functionality you want to keep, though, you might want to try directly upgrading the site to use the distribution. Doing so could save you a lot of time in migrating content. But it will also raise a number of challenges. Upgrading to a distribution is probably something you should try only if you have the skills and time needed to do troubleshooting and some custom data work.

Basic upgrade to a Drupal distribution

Here are basic steps to take to upgrade an existing Drupal site to use a distribution. These are rough guidelines only. Because each site and each distribution is configured differently, you're likely to run into additional complexities. But these notes should at least get you started in the right direction.

1. Select a distribution to use. You'll want to find the distribution that most closely matches your site requirements. See the listings and comparisons of Drupal distributions on drupal.org.
2. Back up. Don't work with your current live site. Instead, create a copy of the site and its database and work with the copies.
3. Update the site to the same Drupal core release as is used in the latest release of the distribution you're using. One way to find out what version of Drupal the distribution is using is to download it and look in the file includes/bootstrap.inc for a line like this: define('VERSION', '7.10');. If your site is in Drupal 6 and the distribution is in Drupal 7, you'll need to upgrade to Drupal 7. See the drupal.org documentation for detailed upgrade instructions. Here is a synopsis of some of the key steps.
   • Update your site to the latest version of Drupal 6 (core and contributed modules). Before upgrading to Drupal 7, disable and uninstall modules you know you won't be using in the new site. To help determine which modules to uninstall, you could review the list of modules included in the distribution, which often are found in the download in the directory profiles/[distribution_name]/modules. If a given module is not in the distribution and you don't foresee needing its functionality on your new site, you may choose to uninstall it.
   • Do an upgrade to Drupal 7 core.
   • Also upgrade any custom (non-core) data that you intend to keep on your new site. At the very least, you'll likely need to migrate Drupal 6 CCK custom fields to Drupal 7 fields.
4. Download the latest release of the distribution. Download and extract the latest release and copy your existing site's Drupal 7 version settings.php file and files directory to the sites/default directory in the distribution install. This will point the new site to your existing site database.
5. Change your site's 'install_profile' variable to the "machine name" of the distribution. [Update: the profile switcher module can help automate this step.] Typically a distribution is installed via an "install profile". To determine the machine name of your distribution, look in the profiles directory for a directory that's the same as or similar to your distribution's name. To tell your site that it is using this distribution, you likely will need to reset a variable in the 'variable' table. To do so, download and enable the Devel module and then run the following code at devel/php: variable_set('install_profile', '[distribution_name]'); where [distribution_name] is the machine name of your distribution. Alternately, you can reset the variable by running a command in your database. For openoutreach, this would be: UPDATE variable SET value = 's:12:"openoutreach"' WHERE name = 'install_profile';. Until you make this change, you likely won't see any of the modules or themes that ship with the distribution, as they're in the install profile's directory.
6. Run updates. Run update.php to update any contributed modules that were enabled on your existing site and that are also present in the distribution you're using.
7. Enable the distribution's install profile. [Update: the profile switcher module can help automate this step.] If your distribution is based on an install profile, you need to enable it now. Install profiles behave much like modules, and so can be enabled either using Drush or via the user interface at admin/modules. However, by default, install profiles are hidden, to prevent accidentally disabling or uninstalling them. If you're using the user interface and don't find a module with a name the same as or similar to that of your distribution, you may need to manually edit the install profile's .info file, adding the line hidden = FALSE. See the drupal.org documentation on the .info file format for details.
8. Select and enable the features you want to use. At admin/structure/features, under the "Features" tab, enable features that you wish to use on the site. Recommended: enable the features one by one, so that you can note and respond to any errors. If you are prompted about orphaned dependencies, select "Leave enabled". For more information about the individual features, read any available documentation on the distribution you're using. See also the section below on "Assessing and preventing component naming conflicts".

Cleaning up your site

The steps above outline how to get a distribution minimally installed on an existing site. But you'll still have a lot of work to do to reconcile your existing site content and structure with what has been created by the distribution. Here are a few tips to get you started--but you should begin with the assumption that there will be lots more you'll discover and need to fix.

• Roles. Many distributions will create one or more custom roles. Examples include contributor, editor, and administrator. If any of these roughly correspond to existing roles on your site, delete the roles created by the distribution and rename the existing ones to use the distribution role names. For example, if your site has a role called "site administrator" and the distribution has created a role called "administrator", delete the newly created "administrator" role and rename "site administrator" to "administrator". After adjusting the role names, visit admin/config/people/accounts, ensure the "administrator" role is selected as the "Administrator role", and save the form. Consolidating the roles in this way will get you the functionality of the distribution's roles and permissions while maintaining your existing users' role allocations.
• Content types and fields. You may have existing content types on your site that overlap with those provided by the distribution. For example, if you have an existing content type called 'news', it might have a function very close to that of an 'article' content provided by one of the features you've enabled. To begin to use the new feature's functionality, you could consider converting the existing 'news' content into 'article' content.
  • Download and install the Node convert module.
  • At admin/structure/node_convert_templates, create one or more templates for converting your content. Then use the admin/content page to filter for the type of content you are converting from, select the appropriate conversion from the "Update options", and apply.
• Blocks and contexts. Many distributions use the Context module to position blocks. Your existing site may use the core Block module for this purpose, may use Context or some other tool, or may use a combination of tools for block placement. With your new distribution's blocks displaying as well as those enabled by your existing site, you may get more than you need or want. To address this issue, selectively disable blocks left over from your existing site. If they were custom blocks, you may wish to delete them.

After each step of reconciling existing site elements with those created by the distribution, you may need to "revert" one or more features from the distribution. See the Feature module documentation on reverting features.

Assessing and preventing component naming conflicts

Most distributions are built using the Features module, which allows exporting configuration from a Drupal site - content types, fields, views, and so on - into code, so that it can be enabled on multiple sites. For components like content types and fields to be exportable, they need to have a "machine name"--a unique name that will be the same on every site they're enabled on. For example, a date-type field used to store the date of an event might have the machine name field_date.

If the distribution is installed from scratch, we can be sure that the components we're creating won't conflict with existing components on the site. But when we're converting an existing site into a one based on a distribution, there's the potential that a component we're creating will have the same name as one that already exists on the site. In certain cases, such a conflict can cause a site error that's difficult to resolve.

The main issue to watch out for is: the site already has a field with the same name as a field that will be created by the distribution and the existing field is of a different type than the distribution's one. Drupal is unable to change the type of an existing field, so this situation will trigger an error.

There's no totally easy way to determine if a feature will conflict with existing components on your site. For fields, try the following:

• At admin/structure/features, click the "Rebuild" link for the feature you're looking at. Look for any fields listed under a heading "Fields". The names here are of field "instances"--the version of a field that's applied to a particular content type. What we're concerned with is the actual field name, which is the part at the end beginning 'field_'.
• Ensure the Fields UI module is enabled. At admin/structure/types, click the "Manage fields" link for a content type and look for fields with the same name as one of the fields in the feature. If you find one, you have the potential for a conflict--an error will occur if the field types are different.

Errors and what to do about them

• I get the error message Notice: Undefined index: distribution_name in drupal_install_profile_distribution_name(). This means you haven't yet enabled your install profile.
• I get a fatal error saying a class or function isn't available. This is a common problem when code has been moved around. Two sources are (a) a required module is not present and (b) the Drupal files registry needs to be rebuilt. Ensure the modules that were on your old site are also available on your new one. Make sure you've set your install profile so that modules that ship with your profile are available. You may need to visit admin/modules to refresh the location of your module files. If all else fails, consider whether you need to use Registry rebuild.

Wrapping up

Upgrading an existing site to use a distribution like Open Outreach is more work than just starting fresh. It takes some planning and the willingness to work through some potential challenges.

If you're up for a few bumps, though, merging an existing site's data with a distribution can get you the benefit of quickly ramping up functionality and design without losing the core of your site: your content and users.