Tips for building a site off a Drupal distribution

As the first few organizations start to try out our Open Outreach distribution, I'm realizing there's a lot to figure out as you build a distribution-based site. Like how much should you customize the site versus taking it as it is? And how do updates and upgrades work? So here are a few pointers. If you have more, please leave comments below.

The first maybe obvious point to realize is just that building a site off a Drupal distribution, especially one that provides a lot of out of the box functionality, is different in important ways from building a site "from scratch" by downloading Drupal core and then adding modules and configuring. Customizing works differently. Updates work differently. So there are some important questions to think through at the start.

Working through these questions will often call for some familiarity with Features, the framework used to build most Drupal distributions. If you're considering customizing a site off of a distribution and aren't yet familiar with how Features works, you'll want to spend a bit of time looking over one or more of the various tutorials out there like Drupal Features module abridged or An introduction to the Drupal Features module and/or the module's documentation.

Key decision

When building a site on a distribution, probably your most important decision is going to be between three options:

  1. Stay on the distribution's update (get a new release for the major version you're using) and upgrade (move to a new major version) path. For most site developers, staying on the distribution's update path will have big advantages. Doing so doesn't mean you can't customize the site somewhat to your own needs. It does mean, though, that you'll need to be careful in the customization you do--more on that below.
  2. "Fork" the site, taking it in its own direction and handle updates yourself rather than relying on future releases of the distribution. This option may be a good one if you have extensive needs that won't be met by the distribution out of the box and are, or have working for you, an experienced site developer who's capable of customizing and maintaining the site. You might also consider this option based on the release status of the distribution. Is it still in alpha or beta? If so, you probably can't count on a stable update path even if you want one. Until it gets a full release, the distribution is likely to go through changes that don't easily update, so you might be best off just taking the site in its own direction.
  3. Combine the two. With this approach, you plan to stay on the distribution's update path, but also do the occasional "manual" update as needed. You might take this approach if you find you need a different version of a module than what ships with the distribution, or want to handle security updates yourself rather than waiting for the distribution to catch up, or want to customize just a select part of the distribution--say, one or two of its features.

If you're not going to stay on the distribution, you might ask, why bother using it at all? But there can still be compelling reasons. Building off of a distribution can give you a huge leg up, by providing functionality that would take you days, weeks, or months of work to reproduce.

For example, at Chocolate Lily we recently produced Nature Explorers, a site for Nature Canada aimed at engaging Canadian youth in outdoors activities. We had less than two months from project start to site launch and a substantial list of functional requirements. A lot of this wasn't covered in Open Outreach, but a lot of it was. So we started with the Open Outreach code base, quickly customized some of the features by manually editing the code, and had a huge jump start on the site by the end of the first week.

Still, if you fork the site you'll be on your own when it comes to future updates and upgrades, so you want to make this decision carefully.

Staying on the distribution update path

The first thing to keep in mind is: the closer you can stick to what the distribution offers, the more value you'll get from it. Take for example Open Atrium, which provides a lot of highly refined intranet functionality. Sure, there are things you might choose to do a bit differently from what OA does out of the box. But before you wade into making those changes, ask yourself: are they really necessary?

Customizing on the distribution

If you're planning to stay on the distribution's update path but still want to customize, here are some ideas and possibilities.

  • Selectively turn off UI feature modules, if the distribution includes them. Some distributions separate user interface configuration like menu items and block display from backend functionality like content types and fields, putting them into distinct feature modules. See these posts about Voicebox and NodeStream. In this case, you can turn off the UI modules and replace their functionality with your own site elements.
  • Make your module additions in sites/all/modules or sites/default/modules. The distribution's files, including modules and themes, will generally be in profiles/[profilename]/modules and profiles/[profilename]/themes, where [profilename] is the name of the profile that you installed. To make sure your customized code is distinct from what ships with the distribution, put yours in sites/all or sites/default. These locations will override the profiles code, meaning that if you need to e.g. use a different version of Views, you can put it in sites/all/modules/views and it will be used instead of the version that shipped with the distribution.
  • Isolate your changes. Whenever you can, try to add new components (views, fields, etc.) rather than changing existing ones. This is because the existing components that ship with the distribution may be changed in future versions of the distribution. For example, in a new release of a distribution a view of events might get enhancements to an existing calendar display. Say you had a need for a "past events" page. If you've edited your own copy of the events view to add your past events page display, it's now "overridden". When you update the distribution, you won't get changes to that view that came with the new version--at least, not without tossing out your own customization.
  • Carefully track any changes you make to components that ship with the distribution. If you really need to make changes to components that ship with the distribution, keep track of them. When it comes time to update, you'll need to make sure you don't "revert" those components (more on this below). Alternately, if the changes you're making are relatively simple and you're comfortable working with Drupal hooks, you could consider making your customizations in a custom module via an implementation of an alter hook for the specific component. For a context, for example, you would implement hook_context_default_contexts_alter(). Or you could try out the Features override module, which offers some limited ability to export overrides to a new feature.

Taking the site its own way

If you're planning to take the site off the distribution update path, here are some potential approaches.

  • Turn off everything you don't need. Take some time at the outset to strip the site down a bit. Consider each feature. Do you need it? Then look at dependencies that feature enabled. Are they needed? The more you can turn off, the less clutter you'll have as you customize.
  • Consider forking individual feature modules. Most distributions are built off the Features module, which enables capturing bundles of site configuration in code. If you're going to take a feature in your own direction, you might want to consider forking it--changing its machine name so that it's no longer linked to the original, which you can do with a bit of search and replace. By doing so, you can use and adapt the original code and at the same time avoid possible future confusion ("Should this feature be updated to the new release?").

Doing updates

With a typical Drupal site, you might be used to downloading and installing module or Drupal core updates one by one, when you receive update notifications.

With a distribution, however, there are additional factors to consider:

  • To achieve its specific aims, a distribution may include "patches" (modifications) to the code it includes. If you update without applying these patches, critical features may break or disappear.
  • Because a distribution is often a complex and carefully designed whole, replacing a single part at a time, like updating a module, can have unexpected outcomes. Changes introduced in the new module version may well break existing functionality.

Updating to the latest distribution release

If you've decided to stay on the distribution update path, you'll probably want to ignore update notices for individual modules. Rather than updating one by one, you'll instead be updating when a new version of the distribution is available.

Like any time you're updating, unless a new release is a designated security update, or contains fixes to problems on your site, you may choose to wait before updating. See the documentation on updating and upgrading a Drupal site.

If the distribution is in alpha or beta, you can expect some rough spots. Be sure you read release notes carefully, and follow any instructions they give.

Gotchas to watch for include:

  • New modules: In some cases a distribution may have introduced new module dependencies between releases. One of the distribution's features may now require a helper module that wasn't required before. Dependencies like this one are automatically enabled when you first enable a module, but are not automatically enabled if the module (in this case, the feature that's part of the distribution) is already enabled on a site. So you may need to manually enable the dependency as part of update.
  • Field type changes: Occasionally a distribution may change the type of an existing field. We did this this between beta releases in Open Outreach, when the field type we were using, 'media', was deprecated and we switched to 'file'. Anyone trying to update will get a fatal error, since the type of an existing field can't be changed. The only solution is to first delete the field - and all its data - before updating.

Basic steps to update your distribution-based site (adapted from Open Publish documentation) might be:

  • Make full backup of your installation.
  • Download the new release and unpack it on top of your old one.
  • Run update, via
  • Do any special stuff specific to the update, like enabling required modules.
  • Clear caches.
  • Go to admin/structure/features if it's a Drupal 7 site or admin/build/features if it's Drupal 6. If you see any features showing "overriden" status, go into the feature with your list of intentionally overridden components in hand. Check overridden components - unless these are components that you've intentionally overridden - and click on "revert components". Repeat for all other overridden features.

But, again, each release will have its quirks--look for release notes to guide you through the update or upgrade.

Updating a "forked" site

If you're updating bit by bit rather than by updating the distribution as a whole, here are some points to keep in mind.

  • Make sure you know what patches need to be applied. The most likely place to find these is in Drush Make (.make) files. Places to look for Drush Make files include:
    • profiles/[profilename] where [profilename] is the name of the profile you installed.
    • The directories of individual features included with the distribution.

    Depending on what code changes have happened meantime, the old version of the patch may not apply--you may need to look for a new one. While you can do this manually - download and apply the new modules plus their patches - another option is to continue to maintain and update the distribution's .make file, so that you continue to have a place where code is tracked.

  • Be careful about switching versions or branches. If the distribution ships with a nonstandard version of a particular module - e.g. the dev branch of views - there's going to be some reason for that choice. Maybe it's to get a patch that hasn't yet reached a stable release. Or maybe it's for compatibility with another module. For example, in Open Outreach we're using the dev branches of Views and Ctools because they're currently required for compatibility with Date and Calendar. In this case, if you're not using the event feature in this distribution, you could try switching to the stable releases of Views and Ctools--but if you are using event, switching would break the site.

Summing up

To restate the obvious, you'll get the biggest benefit from the distribution if there's a close fit between what you need and what it offers. If you can install the distribution and start entering content, fantastic. But if you go in with your eyes open, you can also get a lot of benefit from taking what the distribution has to offer and building from there.

Got more tips or questions about building a site off a distribution? Successful case studies? Disaster stories? Please leave a comment.



Question about existing content type update

Thank you for this article. It is really helpful. I have a confusion with my content type updates. I am using drupal-commons distribution and I want to add some fields in existing content type. This results feature overrides. Now, if I update the distribution code, it may be lost or at least difficult to maintain in future when new update will be available. So, for this kind of scenario what is the best practice to follow. Should I create new feature with overriden values that will go under /sites/all/modules or is there any other ways to solve this problem.

Thank you