Commons 1.5 to 1.6 upgrade notes (and alternatives)

The Release Notes for Drupal Commons version 1.6 describe the essential specifics of what is contained in this release, and the essential information for upgrading.

This page is designed to provide you with broader information on how to proceed with upgrading your Drupal Commons site from version 1.5 to 1.6.

You may have several different goals in handling this upgrade:

• Incorporate all the changes and enhancements provided in version 1.6 as quickly as possible.
• Update your site with the latest security update for Drupal (core) as quickly as possible, and incorporate changes and enhancements over a more gradual time.

Your site will likely be in one of three different states before you begin the process of updating:

1. As-distributed. In this case, you are using Drupal Commons essentially in the same form as it was when you downloaded it. You have not changed the theme, or changed the code. (You may have uploaded a new logo or Favicon via the Theme Configuration page).
2. Modified theme. In this case, you have either modified the Acquia Commons theme to suit your own branding needs, or (less-likely) you have written your own theme from scratch. You may have made changes in the way pages are laid out (by changing panel layouts). However, you have not made any changes to either the actual code implementing the site, or to the functional non-code components, such as views, content types, and features.
3. Modified code (and likely modified theme). In this case, you have made changes to the definitions of Drupal elements such as the views, content types, contexts, user profiles, or any of the features that make up Drupal Commons, or have actually made changes to the code provided in Drupal Commons (most of which is contained in its features). In this scenario, it is also likely that you have modified the theme - or at least possibly changed the panel layouts.

Each of these may dictate a slightly different strategy in handling the upgrade process. Find what is best for you below.

If you encounter any difficulties with your upgrade, Acquia offers commercial support subscriptions to help resolve issues, or you can use the normal Drupal channels to obtain free support from the community.

Using Commons as-distributed

This case is easy; you should be able to update your site as documented in the release notes. And you can do it now; there is no need for you to defer incorporating all the new features contained in 1.6, so you will be able to take advantage of them immediately.

For you, the process is (in summary):

• Backup your code and database, and take your site offline
• Replace your codebase (EXCLUDING the /sites directory) with the new Commons code
  • Do NOT merge the code; replace it Run /update.php
• Disable the Page Manager module, and the obsolete exportables (Contexts, panels, views, etc) listed in the release notes
• Make sure the appropriate theme is enabled. Handle any other errors, and take your site back online

This is just a summary; be sure to follow all the steps listed in the Release Notes. As noted there, it is best to attempt this first on a duplicate of your site (i.e. a test server) to make sure things go smoothly before upgrading your live site

Using a modified version of Commons

If you have made any changes to the theme or code used on your Commons site, you should make your upgrade a multi-step process.

First, apply the security patches as soon as possible. Afterwards, you can begin to integrate the changes you have made into the new Commons version. The only security release that was contained in Commons version 1.6 was for Drupal core (6.22). This new core version does not contain any changes that will affect the operation of your site as-changed.

For this case, you can simply perform a normal Drupal core update process:

• Download either release 6.21 (security fixes only) or 6.22 (security and bug fixes together) from drupal.org and unpack the download
• Backup your code and database, and take your site offline
• Copy the new Drupal release code on top of your existing site code
• Run /update.php
• Handle any errors, and take your site back online

Changed theme

The user interface changes (and they way Commons manages the UX) contained in Commons version 1.6 will require you to pay attention to several aspects of your changed theme:

• Page layout changes
• New and changed views that need styled

How you implement support for the changes in Commons will depend how you changed your theme.

Page layouts - columns

In Commons v1.6, most pages have been reduced from a 3-column to a 2-column layout. If you wish to retain a 3-column layout on some pages, you can do so, but your choice of theme may influence how this looks:

• The Commons Origins theme should adapt easily to 3-column pages, as it is roughly the same theme (with the same abilities & constraints) as Acquia Commons, the theme from version 1.5. It also makes extensive use of the capabilities of the Fusion base theme, and the skinr module, to permit point/click control of page width.
• The Commons Connect theme is strongly oriented around around a 960px width, and has a visual element (upper right corner) that strongly suggests using 2 columns. Three columns are possible (see, for example, /dashboard), but it is sub-optimal to use in a 3 column layout. While it builds on Fusion, it does not perform point/click page width as well as Origins.
• The Commons Elements theme does not have the same visual constraints as Connect, but is also strongly built around a 960px design width, and also does not incorporate the point/click page width capability pefectly.
• A custom theme can, of course, be made to do whatever the themer wants.

Page layouts - control

In previous versions, Drupal Commons used a mixture of Panels and Context to handle page layouts, which caused some confusion. In version 1.6, all layout is handled using Context; Panels has been removed from the distribution.

Certain pages in your Commons distribution are likely to be customized, such as the home page, and these may have built assuming Panels was present. You have two choices on how to proceed:

• Continue using Panels. Simply download the Panels module(s) from drupal.org/project/panels and install them at /sites/all/modules/panels, enable Panels in the modules listing (/admin/build/modules/list), and confirm any needed permissions (/admin/user/permissions).

  Note: In future releases, Commons is likely to become more and more sophisticated in its use of Context; over the long term, you will face a growing difficulty staying up with the latest advancements in Commons if you continue to rely on Panels.

• Switch to using Context. You have probably set up your Panels-driven pages with either blocks containing static content, block views, or custom blocks. If this is the case, you can quickly re-create your pages using Context, with one exception: If your theme does not have named theme regions for locations on a page where you want content to appear, you may need to bring in a themer who can create named regions, since Context requires a named region into which it can place content. (Panels could switch between various layouts within the panels layout editor.)

  There are likely only several places where you need to create new contexts:

  • Home page. Most sites customized their home page, and most used Panels. For a guide, compare the Panel layouts in the default 1.5 release with the Context layouts in the default 1.6 release.
  • Group home page. You may have customized which blocks appear on group home page(s). (Make a similar comparison to see how Commons handles this in v1.5 vs. v1.6.).
  • User profile page.The same logic applies for user profile page where panels was replaced by several contexts. You should compare the way old panels handled several sections to the new contexts. You may find out that you need to create new contexts to handle the same logic in your new profile pages.

New and changed views

Commons 1.6 makes several changes that may need CSS styling. They include:

• Home page: Latest Featured content. This block now adds the graphic for the content type; you may need to float it left of the title, or float the text to the right of the graphic, depending on how you implemented your theme.
• /groups. This page view has been completely changed from a table listing to an HTML list containing different elements. If you have a custom theme, you are likely to need to restyle this completely. The same things apply to the /groups/mine page view.
• All page views for all content types (e.g. /content/blogs, /content/documents, etc.)
• Block views for all content types, as shown on a group home page. Commons switches from having one monolithic block of all recent content to having sidebar blocks for each content type. Note that the views have the user avatar floating to the left of the title & metadata.

If you have made changes to these views or other structures controlled by features and you have not update the features code, you should carefully review which changes were done before doing the upgrade. You should look for features that do not have their status as default on the features admin page (/admin/build/features).

Probably you will need those changes to be done also on the new commons versions and tipically it would not take you much time to redo those changes after the upgrade.

However if you already update your features code to reflect the changes that you made, it would be hard to compare them with the new version. Nevertheless, you can always find the differences in code by executing a simple diff.

Other areas of change

Other places to check your theme are:

• User profile page. This page has changed significantly in order to improve usability. If you have added custom fields to the profile, you may need to make sure they are being displayed where you wish them to be.
• The “Create __” content action. This previously was a set of links, one per content type. It is now a dropdown. Please note that if you create new content types, they should be encapsulated in a Feature, so that they can be enabled / disabled per-group through use of the new og_features module included in version 1.6.
• Speaking of og_features, if you have a custom theme, be sure the list of features, and the checkboxes to enable / disable them, are visible on the Features tab of a Group home page (visible only to group admins or user 1).

Implementing theme changes

The appropriate way to change the look & feel of a theme based on Fusion - as was Acquia Commons - is to encapsulate all desired changes in the local.css file provided in the CSS directory, and simply continue to use the original “Acquia Commons” theme.

If you have done this, you should be able to retain most of your changes by creating a new theme that inherits from a base common theme, Acquia Origins for instance. Doing that guarantees that you keep up to date and import all the changes from the new themes, while you only override the aspects that you want to tweak.

Start by create a new theme that inherits from a base theme, Acquia Origins for instance, setting base theme = commons_origins on your theme info file. So, your theme will inherit from one of the base themes that will also inherit from common_roots. This theme will only override some css or template files.

Next, find your local.css file from your old theme that is likely located at:
/profiles/drupal_commons/themes/acquia_commons/css/local.css

Copy the contents of local.css file into your new theme stylesheet.

Then, set your site to use your new custom theme (/admin/build/themes/select). Depending on what CSS styling you changed (and how you changed it), your new theme may work perfectly. If not, you will need to contact the Drupal themer who created your theme and have them fix any remaining issues.

If, on the other hand, you created a new theme - either based on Acquia Commons or another starter theme - you are likely better off retaining your old theme, converting your Panel-based layouts to Context, adding support in your theme for the new page layouts, and for the new / redefined Views.