Updating Panopoly

Updating Panopoly (or any Drupal distribution) is different than updating a normal Drupal site which you built entirely from scratch.

Note: DO NOT update individual modules included with Panopoly, either manually or using drush up! Panopoly bundles specific versions of the modules it includes, sometimes with important patches. Updating individual modules can break things or cause problems.

Before starting: Backup and capture overrides!

In order to upgrade, we're going to be replacing many of your site's files and running updates on the database. So, before getting started be sure to make a backup!

Also, if you've customized any of Panopoly's configuration in a way that has caused it's Features to become overridden, you should capture those overrides in a module before upgrading! If you try to do it after upgrading, it'll be difficult to tell which overrides are changes that you made, and which are simply differences between the old version of Panopoly and the new.

So, first, to check if any of Panopoly's Features are overridden:

1. Open the admin menu, and click "Structure" -> "Features"
2. Click on "Panopoly" in the vertical tabs
3. Watch the "State" column and wait for the values to change from "Checking..." to either "Default" or "Overridden". This can take a few seconds to a few minutes, depending on how many Features you're using on your site.
4. If any of the Panopoly Features have a state of "Overridden" it means your changes would be lost if all Features were reverted -which may be necessary to fully complete the upgrade!

To prevent your changes getting lost when Features are reverted, you have to capture them in an override module. The easiest way to do this is with Features Override, which is bundled with Panopoly (but not enabled) since version 1.12.

See these great articles on the Phase2 blog about using Features Override:

• A new paradigm for overriding Drupal Features
• Features and Overrides – Part Deux
• Features and Overrides – Part III

Updating on Pantheon

If you installed Panopoly on Pantheon using the one-click installer, then upgrading Panopoly is super easy!

The day a new version of Panopoly is released (or sometimes a day or two after), we'll update the version used by Pantheon's one-click installer. The next time you visit your dashboard on Pantheon, it'll ask you if you want to upgrade. Say "yes" and you're done!

Updating with drush

It's also really easy to upgrade using drush! (so long as you do it the right way - see below). Note: This method has been deprecated as of Drush 9.0.0. To update Panopoly with Drush, you need to use Drush version 8.x.x.

Change into the root directory of your Panopoly site and run:

drush dl panopoly
drush make profiles/panopoly/drupal-org-core.make .
drush updb
drush updb # yes, do it twice!

It'll ask you if you want to overwrite the profiles/panopoly directory and run the database updates. To update a specific version of panopoly, for example 1.20, you can do: drush dl panopoly-7.x-1.20

Afterwards, it's a really good idea to clear the cache just in case:

drush cc all

Also, if you've overridden any Features, some updates to Panopoly won't take effect until you revert all Features. However, if you've customized anything provided by a Feature and haven't put your changes into an override module, reverting all Features will cause your customizations to be lost! See the "Before starting" section for information about how to prevent your changes from being lost.

Here is the Drush command to revert all Features, but be careful:

drush fra -y

Updating manually

1. Download the latest packaged version of Panopoly from Drupal.org. This will include updated versions of all of Panopoly's bundled modules, themes, and libraries.
2. Extract the .tar.gz or .zip file to a new directory.
3. Copy the sites directory from your old Panopoly root to this new directory.
4. Now, move the old Panopoly root somewhere else and replace it with the new Panopoly root so that you're webserver can see it.
5. Run update.php *TWICE* on your site. This may perform several database updates for Panopoly and its bundled apps and modules.
6. Navigate to the admin screen for Features (admin/structure/features) and revert any overridden features (unless you have intentionally made overrides you want to keep - see the "Before starting" section for information about how to prevent your changes from being lost.).

Upgrading to a new version of Panopoly is a lot like upgrading to a new version of Drupal core, so the documentation for doing that manually is also very useful:

http://drupal.org/node/1223018

Updating your child distribution built on Panopoly

If you built a child distribution built on Panopoly (see Developing Distributions with Panopoly), then:

1. Edit your .make file and change the version to the latest version of Panopoly. For example, if you were using Panopoly 1.1:
   

   projects[panopoly_core][version] = 1.1
   

   ... and you wanted to upgrade to Panopoly 1.2, you'd change it to:

   projects[panopoly_core][version] = 1.2
   

2. Re-run your .make file. If you're .make file is called drupal-org.make and you want to update in place, then go into your profile directory and run:
   

   drush make --no-core --contrib-destination=. drupal-org.make
   

3. OPTIONAL: Copy the drupal-org-core.make file from the Panopoly profile to get the same Drupal core version as in the latest Panopoly. However, if you're managing core in a different way (ie. if you're distribution isn't on Drupal.org!), then you can feel free to skip this step.

Finally, you'll need to use update.php or drush updb.

NOTE: While this updates the drupal-org-core.make file, it won't actually update Drupal core on your system! You'll have to do a full rebuild from scratch, not just the profile (like we're doing in step #2 above) for this to happen.

Updates from super old version of Panopoly

Our provisional policy (this is still being discussed) is that we only support updates to the latest version of Panopoly from any version released less than one year ago. This means that:

• Our automated tests will run the update process from each the supported versions on every commit we make to Panopoly -dev
• Any fatal error in the update path is a Critical Bug and we'll fix it as soon as possible (however, this doesn't include issues created by modules added or updated by the users - only what we include with Panopoly

Any bugs found in the update process from Panopoly versions that were released longer than a year ago to the current version will be marked "Closed (won't fix)".

However, all is not lost if you need to update a super old version of Panopoly! First of all, even though we don't support it, the update to the latest version might just work, so try that first. If it doesn't, the update path did work at some point in the past, so you'll just have to do your updates in parts! Meaning, first you update to the last known version where the update path was supported, and from there to the latest version.

Troubleshooting

Here's a few common update errors and how to solve them!

1146 Table ‘drupal.cache_features' doesn't exist'

At some point Features added a new cache table called 'cache_features'. This error happens when another update function tries to clear all caches before the Features update function has had a chance to create the new cache table.

This answer is specifically about Features, but this can (and has happened) with other modules.

Unforunately, there's nothing Panopoly can do to fix the underlying problem because any contrib module you installed could clear caches during an update function. (We automatically test upgrades with only the default Panopoly modules, so we know it doesn't happen unless new modules are installed.)

Steps to fix:

1. Determine the schema_version of the Features (or other) module:
   

   $ drush sqlq "SELECT schema_version FROM system WHERE name = 'features'"
   schema_version
   7199
   

2. Run all update hooks since that schema_version:
   

   $ drush php-eval 'module_load_install("features"); features_update_7200()'
   

3. Update the schema_version to match the last update hook you ran:
   

   drush sqlq "UPDATE system SET schema_version = 7200 WHERE name = 'features'"
   

4. Verify that the new cache table was created (you should see 'cache_features' in this list):
   

   $ drush sqlq "SHOW TABLES LIKE 'cache_%'"
   Tables_in_drupal (cache_%)
   cache_admin_menu
   cache_block
   cache_bootstrap
   cache_entity_fieldable_panels_pane
   cache_features
   cache_field
   cache_filter
   cache_form
   cache_image
   cache_libraries
   cache_media_oembed
   cache_menu
   cache_metatag
   cache_page
   cache_panels
   cache_path
   cache_search_api_solr
   cache_token
   cache_update
   cache_views
   cache_views_data
   

5. Try running drush updb again and hopefully the update will succeed this time!