Upgrading to 3.1.5

This guide covers how to upgrade a BrowserCMS project from an earlier version to v3.1.5. For additional information, see also: Upgrading-to-3.1.x . If you are upgrading from a 3.1.x to a later version (3.3.x or later), see Upgrading-a-BrowserCMS-project

Preparation

• Upgrade to Rails 2.3.x - As part of this process, its recommended that you upgrade to the latest 2.3.x release of Rails. At the time of this guide, this was 2.3.14. This will minimize the potential testing conflicts.
• Checked in - Make sure your project working directory is clean (all files checked in) in case you need to revert these.
• Database backups - Before running the migrations on a production server, its HIGHLY recommended you back up the database. The migrations for this version are not reversible, so you will have rollback your database in another fashion.
• Production Data locally - It's helpful when you are doing these locally to have a copy of the current production database installed. This way, you can verify the migrations work correctly and the site still works. For example, if you use MySQL you can Backup/Restore, backing up on the server, FTPing the file to your local machine then loading the data into your development database.

1. Install the new gems

$ gem install rails -v 2.3.14
$ gem install browsercms -v 3.1.5

2. Go to your project

$ cd path/to/your/project

3. Edit your environment.rb

Edit your config/environment.rb so it contains the following lines (note some unchanged lines are skipped for brevity):

RAILS_GEM_VERSION = '2.3.14' unless defined? RAILS_GEM_VERSION # Update the Rails version

Rails::Initializer.run do |config|    
    config.gem 'ancestry', :version=>"1.2.4" # New line. Ancestry must be before browsercms
    config.gem 'browsercms', :version=>"3.1.5" # Update the BrowserCMS version

4. Update Rails

$ rake rails:update

This will update any core rails scripts (like boot.rb) that may have changed between the version of rails you were on to the new version.

5. Add the migrations/view files to your project

$ script/generate browser_cms 

Note: This generator will very likely be prompted to overwrite some files (probably .htm or .js files). This can occur if files were altered after they were copied into the project. You should probably accept all these changes, then compare/revert them using your SCM after verifying the changes work in your project.

6. Migrate

$ rake db:migrate

7. Test and Deploy

Things to be sure to check, in addition to your automated tests:

• If you overwrote any files, verify the WYSIWYG editor still works, and that all styles are still present. (You may need to compare this to the live site
• Sitemap - Spotcheck to make sure the order and depth of the sitemap matches the live site
• Menus - Spotcheck to make sure menus works correctly on pages.

Once you have verified all your changes work locally, you can check in, cap deploy and migrate the site.

Troubleshooting

Here are some potential issues you may run into:

Unknown column 'section_nodes.section_id' in 'where clause'

This is probably occuring due to custom code in your project, possible to optimize the existing sitemap. You should review your initializers for class_evals on Section or SectionNode, as well as the app/views/cms/section_nodes directory and probably delete any 'overridden' files you find there.