A new version of the engine is out and you want to try it out in your existing LocomotiveCMS application. Here is the procedure to achieve that.

1. Change the version of the engine.

Open your favorite editor and edit the Gemfile of your application. All you need to do is to tell which version of the engine you want.

gem 'locomotive_cms', '~> <last_stable_version>', require: 'locomotive/engine'

If you want to live on the edge, just set the id of the last commit from Github.

gem 'locomotive_cms', git: 'git@github.com:locomotivecms/engine.git', ref: '<last_commit_id>', require: 'locomotive/engine'

Once it is done, update your gems.

bundle install

2. Run the database migrations

Copy the migrations of the LocomotiveCMS engine to your main application.

bundle exec rake db:mongoid:migration:install

Run them.

bundle exec rake db:mongoid:migrate

3. Re-compile the assets for production

A new version of the engine comes often with changes in the Javascript or CSS code. Thus, you have to update your compiled assets as well.

bundle exec rake assets:clean
bundle exec rake assets:precompile

Upgrading from from 2.4.x to 2.5.6

Once your application has been upgraded to the 2.5.6 version and the command bundle install has been executed.

New dragonfly config file

Move your config/initializers/dragonfly.rb file outside your application. Then, re-generate it:

bundle exec rails g locomotive:install

If you modified the default settings, apply them again with the new version of the file.

New liquid config file

Mongoid 3.x uses a new format to describe the database sessions.

Keep your current config/mongoid.yml file safe because you will have to reflect your changes to the new file generated by that command:

bundle exec rails g mongoid:config

Tips for upgrading from 2.0.0.rcX to 2.0.X

Here are several tips to help you upgrade from a the release candidate version of LocomotiveCMS to the 2.0.x series release. Do these steps after upgrading and migrating your LocomotiveCMS engine.

• If your models are not showing up correctly, you probably need to rebuild the page templates

   bundle exec rake locomotive:rebuild_serialized_page_templates
  

  If this command fails, you may have underscores in your template names. Try renaming your template from two_columns.liquid to two-columns.liquid and updating the pages that reference that template. Finally, run the command again and it should succeed.

• The syntax for overriding nested blocks has changed. Consider the following template:

    {% block 'main' %}
        {% block 'nested' %}{% endblock %}
    {% endblock %}
  

  In previous versions, you could override the nested block with the following code:

    {% block 'nested' %}Hello World{% endblock %}
  

  However in version 2.0.x, you now need to include the hierarchy of the blocks you want to override:

    {% block 'main/nested' %}Hello World{% endblock %}
  

  If you use nested templates, you will need to make these updates immediately after upgrading.