Upgrading a BrowserCMS project to 4.0

Prerequisites

Projects must first be upgrade to 3.5.4 or later. Owing to how migrations are handled, its isn't possible to upgrade directly to 4.0.

(Note: Work in progress)

Preparation

1. Create a directory called config/broken_initializers. During the upgrade, move any initializers that throw errors from config/initializers to this directory temporarily.

Steps

1. Update the Gemfile

Use the correct version of BrowserCMS, remove any version # references to Rails and Rails related dependencies (i.e. sass-rails, coffee-rails, etc)

gem "browsercms", "4.0.0.alpha"
# gem "rails", "3.2.5" # Use BrowserCMS dependency.
gem 'sass-rails' #, '~> 3.2.3' 
gem 'uglifier', #, '~> 3.2.2'

You may want to comment out all existing BrowserCMS modules initially, since they may not have CMS 4.0 versions availalble yet Then run bundle update.

2. Add migrations

1. Record the timestamp for the existing 3_0_0 migration (i.e. 20080815014337).
2. Delete all the BrowserCMS migrations (3_0_0, 314, etc) from the project.
3. Add the migrations by running rake cms:install:migrations
4. Rename the newly generated browsercms300.cms.rb so so it matches the old timestamp of browsercms3_0_0. This will prevent the new migration from running.

Then run rake db:migrate, then start debugging:

3. Debugging

Running rake db:migrate is likely to expose a number of errors related to Rails 4, BrowserCMS 4 or issues with modules. The steps to be taken for each project are different, but here are some possible resoluations:

1. Issue: An initializer throws an error. Resolution: Move that file to config/broken_initializers. Carry on.
2. Issue: Application.rb throws an error. Resolution: Comment out that block off code with an @upgrade tag so you can find it later. Carry on.
3. Issue: Error: attr_accessible is extracted out of Rails into a gem. Resolution: Remove attr_accessible calls in models.
4. Issue: uninitialized constant Cms::SomeModelName from routes.rb Resolution: See 'Namespacing Application Models below'

4. Namespacing Application Models

Edit your config/routes.rb to put all custom blocks under the application namespace. For example, for a project named 'Petstore' here's how it should look:

# Old
namespace :cms do content_blocks :events end
namespace :cms do content_blocks :people end

# New
namespace :petstore do 
  content_blocks :events
  content_blocks :people
end