Summary

Spree 0.30.0 is the first official release to support Rails 3.x. It has been several months in the making but we’re finally here. Unfortunately we haven’t had the time to write up detailed release notes and the documentation is still a work in progress. We’ll try to mention the highlights here and we’ll continue to update the documentation in the coming weeks.

We’re always looking for more help with the Spree documentation. If you’d like to offer assistance please contact us on the spree-user mailing list and we can give you commit access to the spree-guides documentation project.

Rails Engines

Spree is now heavily reliant upon the concept of Rails Engines. This represents a significant architectural shift from previous versions of Spree. This will likely be the most time consuming upgrade of Spree you’ll ever have to make. The change is the result of a major change in Rails itself so the difficulties are unavoidable. The good news is that Rails has adopted many of the ideas used in Spree (Engines are now equivalent to Spree Extensions and visa versa.) This means that there is very little non-standard Rails behavior left in Spree.

No More Site Extension

Previous versions of Spree required a site extension in order to customize the look and feel of the site. One major improvement in Spree is that this is no longer necessary. All of the content that normally goes in your site extension can now be moved to to Rails.root.

Extensions are Now Gems

Extensions are now installed as Rubygems. They are also no longer deployed to vendor/extensions. You need to add the required extensions to you Gemfile. There is a comprehensive Extension Guide in the online documentation which can assist you.

As of the time of this release there are only a limited number of extensions that are currently compatible with Spree 0.30.x. It is suggested that you check the Extension Registry for more information on which extensions are 0.30.x compatible. Check back often because the Spree core team will be working on updating the more critical ones immediately after the release.

Its relatively easy to convert an existing extension into a gem. Its suggested you find a 0.30.x compatible extension and study the source code for a better idea on how to do this.

Improvements to Payments

Payments have been significantly improved in this version of Spree. One of the most important changes is the addition of a state machine for payments. Payments that are submitted to a payment gateway for processing are in the “processing state.” This will help to prevent additional attempts to process the payment through customer refreshing, etc. Failed payments are also recorded and given a “failed” state.

We have abandoned the concept of payment transactions and now record most of the information directly in the payment record. When in comes time to calculate the payment total, only payments in the “completed” state are counted.

Simplification of Adjustments

Adjustments have also been dramatically simplified. Instead of having the concept of Charge and Credit we just have the single Adjustment. What used to be called a Credit is now just a negative adjustment. Adjustments also now have a mandatory attribute. When this attribute is true the adjustment is always shown when displaying the order total, even if the value is zero. All non-mandatory adjustments are removed from the order if their value is ever equal to zero.

Mandatory adjustments make it easy to show $0 for tax or shipping when those cases apply. The thinking is we don’t want customers to wonder what the shipping cost because its not present - better to show a $0 value explicitly.

New Promotion Functionality

Promotion functionality in Spree has been greatly improved. There is a new spree_promo gem which is included by default when you install Spree.

Creating a Promotion

A new promotion requires a name and code attribute. The code attribute can be used by customers when checking out to “activate” a particular promotion.

This is standard “coupon code” functionality but you’re not required to have customers enter codes in order to utilize promotions.

Promotion Rules

Once a new promotion is created you can create one or more rules for the promotion. You can require that all rules for the promotion be satisfied or just one of the rules.

Each of the rules is based on a Ruby class that extends PromotionRule. There are four built in rule types for Spree but others can be added via extension or directly through your Spree application code.

Item Total: Limit to orders with an item total above a specified amount
Product: Limit to orders containing one or all of the specified products
User: Limit to orders made by specific users
First Order: Limit to the first order by a user

No More “Vendor Mode”

Spree is deployed as a Rubygem now so the previous system of different “boot modes” has been simplified. Spree never needs to be deployed inside of your application, even if you’re using edge or a custom fork. Thanks to Bundler you can reference any version of Spree source directly via Gemfile and either a physical directory location or a git repository location.

See the Source Guide for a complete understanding of all the changes to the organization of the source code.

Upgrading

Before You Upgrade

Upgrade to the Previous Version

It is recommended that you upgrade to Spree 0.11.x (the previous latest stable version) first. The upgrade process should go much smoother if you upgrade incrementally.

Backup Your Database

It is always recommended that you backup your database before upgrading. You should also test the upgrade process locally and/or on a staging server before attempting on your live production system.

The Spree 0.30.0 upgrade will delete any in progress orders which should generally considered to be a safe thing to do since these are typically just abandoned orders. There are also non trivial changes to payments and other tables. Hang on to your database backup until you’re sure the upgrade has gone smoothly.

Create a New Rails Application

It is suggested that you create a brand new Rails 3.x application and then make the necessary changes to that application. We’ll briefly walk you through the steps to do this.

There have been major changes to how Rails applications (and consequently Spree) are configured and initialized. You will have an easier time if you start with a new Rails application and migrate your stuff over to it rather than trying to make changes to an existing Spree application so that its Rails 3 compliant.

Copy Your Legacy Files

Spree no longer requires that you have a “site” extension. This means that you should copy all of the files in vendor/extensions/site into the app directory of your new Rails application. This includes the contents of the public directory.

Add Spree to the Gemfile

So now you have a new Rails 3.x application and you’ve moved over your custom files. Its time to add the Spree gem into the mix. Edit your Gemfile and add the following entry:

gem 'spree', '0.30.0'

Then install the Spree gem using the familiar Bundler approach:

$ bundle install

Upgrade Migrations and Assets

The gems that comprise Spree contain various public assets (images, stylesheets, etc.) as well as database migrations that are needed in order to run Spree. There is a Rake tasks designed to copy over the necessary files.

$ bundle exec rake spree:install

Once the migrations are copied over you can migrate using the familiar Rake task for this.

$ bundle exec rake db:migrate