Upgrading a BrowserCMS project

This page covers how to upgrade from BrowserCMS 3.1.x to 3.3.x, which also involves upgrading to Rails 3, so its a bit more involved. For info on upgrading from 3.0.x to 3.1.x, see this page Upgrading to 3.1.x

Overview

Upgrading to v3.3 involves two main tasks.

• Upgrading your project's code to Rails 3.
• Removing BrowserCMS public files from the project, since they are now served from gems. Ticket #382

Ruby 1.9.2 is also required, so you will need that installed as well.

Getting Ready

Ensure your project clean working directory (since reverting may be needed). Make sure your data is backed up. Doing this is in a branch is advised as well. RVM is helpful for this as well, since you need to have both Rails 2.x and Rails 3.x and be able to switch between them. Using RVM gemsets will be helpful.

This document currently tacitly assumes an SVN project with regard to commands to revert files, etc.

Upgrade custom code

In your Rails 2 gemset, install the rails-upgrade plugin. See http://omgbloglol.com/post/364624593/rails-upgrade-is-now-an-official-plugin for more details. Run rake rails:upgrade:check to see what you might need to change. The difficultly will depending on how many custom code you have.

Steps:

• Generate the new Gemfile using the rails upgrade gem.

rake rails:upgrade:gems >> Gemfile

• Edit Gemfile to remove invalid lines and update the version of rails.
• Set browsercms version to 3.3.0
• Edit the config/routes.rb to use the new syntax.

# Before:
ActionController::Routing::Routes.draw do |map|
  map.namespace('cms') {|cms| cms.content_blocks :some_block }
  map.routes_for_bcms_blog
  map.routes_for_browser_cms
end

# After:
AppName::Application.routes.draw do
  namespace('cms') { content_blocks :some_block }
  routes_for_bcms_blog
  routes_for_browser_cms
end

• Check the above changes in.
• Switch to your rails 3 gemset (rvm @rails3)
• From inside the project, run rails new . -f to force generate a skeleton rails 3 application on top of your existing app.
• Revert the following files:

svn revert config/database.yml
svn revert config/routes.rb

• Delete the following files:

rm public/index.html

At this point, you should have all the Rails 3 specific upgrade complete. So check your changes in. Next, we will handle the actual CMS upgrade itself.

Upgrading the CMS

Pre 3.3, BrowserCMS would copy any files that it needed to render the UI into the public/ directory of the project. As of 3.3, this is no longer needed, and these files should be removed, or they will 'mask' files from the core CMS. If you have made alterations to these files, you can keep them, but you may need to merge the changes. Here's the basic list of files that can be removed:

• public/bcms/ckeditor
• public/images/cms
• public/stylesheets/cms
• public/javascripts/cms
• public/javascript/jquery* - JQuery has been update, so older files should be removed.

You may also wish to remove the prototype/scriptacolous files from the project, unless you are using those as part of your project.

Steps

• Run bcms-upgrade v3_3_0. This will remove all BrowserCMS 3.1.x specific files from the project, and copy migrations into your project.
• Depending on your VCS, you may need to also explicitly delete these files.