Upgrading AlchemyCMS
This guide describes how to upgrade AlchemyCMS to a new version.
Upgrading Alchemy is mostly three steps.
- Update the gem
- Run the upgrade task
- Follow ups
Update the gem
If you use Alchemy from a git branch, point it to the next stable release.
...
-gem 'alchemy_cms', github: 'AlchemyCMS/alchemy_cms', branch: '5.2-stable'
+gem 'alchemy_cms', github: 'AlchemyCMS/alchemy_cms', branch: '5.3-stable'
...
If you use Alchemy from rubygems, point it to the next stable release.
...
-gem 'alchemy_cms', '~> 5.2'
+gem 'alchemy_cms', '~> 5.3'
...
If you are using alchemy-devise
for authentication, then update the gem as well. The major and minor versions of the alchemy_cms
and the alchemy-devise
gems match.
...
-gem 'alchemy_cms', '~> 5.2'
+gem 'alchemy_cms', '~> 5.3'
-gem 'alchemy-devise', '~> 5.2'
+gem 'alchemy-devise', '~> 5.3'
...
Now update via bundler
bundle update
Run the Alchemy Upgrader
Now you can run the upgrade task. While upgrading, you will get informations about the process on your screen.
bin/rake alchemy:upgrade
and follow the on screen instructions.
Update the default config
If new configuration options have been introduced you see them in the config/alchemy/config.yml.defaults
file. Simply copy them over and have a look at the git diff
. Keep your changes remove or add new keys as necessary.
If you have also alchemy-devise
installed you need to .
bin/rails g alchemy_devise:install
Follow ups
Most of the time the upgrader does all the work for you. Biut sometimes the upgrade needs some manual work. This will be noted as TODOs at the end of the upgrade task.
Please follow them carefully.
Finished
Please always verify the upgrade by looking through the git diff
and running your test suite.