Upgrade Instructions (from v. 0.2.0 to 0.3.0)
It is strongly recommended that you backup your database before upgrading.
IMPORTANT: These instructions are for upgrading an existing Spree deployment only. If you are starting a new Spree deployment or using Spree for the first time you will not need to do any of this.
Database Migrations
Since the 0.3.0 release uses Rails 2.1 migrations there are some added complications to upgrading an existing Spree application. You will need to backup the data from your current database so that you can reapply it after the migrations. It is also highly recommended that you backup the entire database (structure and data) in case anything goes wrong.
If you have added any new database migrations for your extensions (beyond the standard core extensions) then you will also need to modify the extension filenames before upgrading. Rails 2.1 now records every migration number that has been applied and so it no longer allows for extensions to have the same migration number as other extensions or the main application migrations. All that is required in this case is to rename your extension migration files using the new UTC timestamp notation (YYYYMMDDHHMMSS) supported by Rails 2.1.
For example:
$ mv 001_create_foo_table.rb 20080622170500_create_foo_table.rb
You don’t technically need to use UTC time, and the actual timestamp value is not terribly important (Rails uses UTC to ensure that the migrations will be unique across multiple simultaneous developers working together.) The key is to simply rename these extensions so that the numbers no longer clash with other migrations.
Once you have backed everything up and renamed any of your non standard migrations you are ready to migrate.
rake db:migrate
This should rebuild the database. Other then a few new tables introduced since 0.2.0 the structure should look very similar to what you had before the upgrade. The migrations should also have been performed for all of your custom extensions. If the table structure looks good then you can go ahead and restore the data to your tables from the backup. Note: Other then the now defunct extension_meta table, your data should import cleanly into the new database structure.
These changes are a hassle but they are unavoidable in order to remain compatible with Rails 2.1. The upside is that migrations will be dramatically simplified going forward.
Other Database Considerations
Prior to version 0.3.0 the bootstrap process was previously responsible for setting up the country data and only included the united states. A complete list of countries is now added through the migrations. Your existing addresses that point to the United States with an id = 1 probably need to updated to point to the new country id (214).
Configurations
You’ll need to replace the config/boot.rb and config/environment.rb with the 0.3.0 source versions. Just grab them from inside your gem installation or create a temporary Spree application with spree foo and copy them over. Most likely your existing boot.rb will not have any issues with it but its possible you have some custom code in your environment.rb. Feel free to modify the new environment.rb to suit your needs.
Going forward we will likely automate this with a rake task. It is also suggested that you use a custom initializer instead of modifying environment.rb in order to prevent your changes from being overwritten during future upgrades.
Permissions
You will need to move your permissions file from #{SPRE_ROOT}/lib/easy_role_permissions.yml to #{SPRE_ROOT}/config/easy_role_permissions.yml. There are several permission changes so the easiest thing to do is to replace your permissions file outright with the one in the 0.3.0 release. Otherwise it is suggested that you manually examine the new file with your existing file and patch accordingly.
Stylesheets
You will need to manually copy over the new spree.css and spree-admin.css from the gem or a temporary Spree application. Again, this will likely be automated by rake task going forward.
Rails Version 2.1
Spree 0.3.0 now uses Rails 2.1. It also no longer ships with Rails as part of the vendor/rails directory. The Rails gems will be installed automatically when installing the Spree gem. If any of you Spree applications are using a frozen version of Rails you will need to unfreeze the older version of Rails
rake rails:unfreeze
You can free Rails 2.1 to your application if you wish
rake rails:freeze:gems
If you do not freeze Rails 2.1 to your deployment then you can simply use the Rails 2.1 gem