Upgrading to 3.3.x from 3.1.x

This page covers how to upgrade from BrowserCMS 3.1.x to 3.3.x. If you are trying to upgrade from and/or to another version, please see Upgrading a BrowserCMS project to find the appropriate instructions.

Background

Moving from 3.1.x to 3.3.x also involves upgrading your project from Rails 2.3.x to Rails 3.0.x, so its a bit more involved. This means there are two main things you need to get done.

• Upgrading your project's code to Rails 3.
• Upgrading the CMS itself

Ruby 1.9.2 is also required, so you will need that installed as well. If you are upgrading from a 3.0.x project to 3.3.x, we recommend completing Upgrading to 3.1.x before starting this one.

A. 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.

B. Upgrading Rails

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.

B.1. 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.

C. Upgrading the CMS

Aside from the changes due to Rails 3, there are two main changes specific to BrowserCMS 3.3.

1. Removing BrowserCMS public files from the project, since they are now served from gems. Ticket #382
2. Getting the new migrations

C.1. Removing public assets

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 updated, so older any jquery files included in the project (i.e. jquery.js, jquery-ui.js, etc) 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.

C.2. Upgrading

• 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.
• Run rake db:migrate then start your tests.
• Since Rails 3 no longer automatically adds files in /lib directory to your project, you may need to add the following to your config/application.rb

config.autoload_paths += %W(#{config.root}/lib)