Add 2.3 release notes + upgrade guide

guides/content/developer/upgrades/index.md

@@ -17,3 +17,4 @@ If there are any issues with these guides, please let us know by [filing an issu
 * [1.3.x to 2.0.x](/developer/upgrades/one-dot-three-to-two-dot-oh)
 * [2.0.x to 2.1.x](/developer/upgrades/two-dot-oh-to-two-dot-one)
 * [2.1.x to 2.2.x](/developer/upgrades/two-dot-one-to-two-dot-two)
+* [2.2.x to 2.3.x](/developer/upgrades/two-dot-two-to-two-dot-three)

guides/content/developer/upgrades/two-dot-two-to-two-dot-three.md

@@ -0,0 +1,48 @@
+---
+title: Upgrading Spree from 2.2.x to 2.3.x
+section: upgrades
+---
+
+This guide covers upgrading a 2.2.x Spree store, to a 2.3.x store. This
+guide has been written from the perspective of a blank Spree 2.2.x store with
+no extensions.
+
+If you have extensions that your store depends on, you will need to manually
+verify that each of those extensions work within your 2.3.x store once this
+upgrade is complete. Typically, extensions that are compatible with this
+version of Spree will have a 2-3-stable branch.
+
+This is the first Spree release which supports Rails 4.1.
+
+## Upgrade Rails
+
+For this Spree release, you will need to upgrade your Rails version to at least 4.1.2.
+
+```ruby
+gem 'rails', '~> 4.1.2'
+```
+
+## Upgrade Spree
+
+For best results, use the 2-3-stable branch from GitHub:
+
+```ruby
+gem 'spree', :github => 'spree/spree', :branch => '2-3-stable'```
+
+Run `bundle update spree`.
+
+## Copy and run migrations
+
+Copy over the migrations from Spree (and any other engine) and run them using
+these commands:
+
+ rake railties:install:migrations
+ rake db:migrate
+
+## Read the release notes
+
+For information about changes contained with this release, please read the [2.3.0 Release Notes](http:https://guides.spreecommerce.com/release_notes/spree_2_3_0.html).
+
+## Verify that everything is OK
+
+Click around in your store and make sure it's performing as normal. Fix any deprecation warnings you see.

guides/content/release_notes/2_3_0.md

@@ -0,0 +1,246 @@
+---
+title: Spree 2.2.0
+section: version
+---
+
+## Major/new features
+
+### Rails 4.1 support
+
+Rails 4.1 is now supported by Spree 2.3. If you wish to use Rails 4.1, Spree 2.3 is the release for you.
+
+### Preferences serialized on records
+
+Preferences are now stored on their records, rather than being stored in `spree_preferences`. This means that to fetch a preference for say, a calculator, one query needs to be done to the database for that row, as that row has the `preferences` column which contains all preferences. 
+
+Previously, there would be a single DB call for the record itself, and then any number of database calls thereafter to fetch the required preference values for that record. What happens now is that there's only one database call, which means there should be some minor speedups.
+
+### Better multi-store support
+
+A `Spree::Store` model for basic multi-store/multi-domain support has been added.
+
+This provides a basic framework for multi-store/multi-domain, based on the
+spree-multi-domain extension. Some existing configuration has been moved to
+this model, so that they can have different values depending on the site
+being served:
+
+* `Spree::Config[:site_name]` is moved to `name`
+* `Spree::Config[:site_url]` is moved to `url`
+* `Spree::Config[:default_meta_description]` is moved to `meta_description`
+* `Spree::Config[:default_meta_keywords]` is moved to `meta_keywords`
+* `Spree::Config[:default_seo_title]` is moved to `seo_title`
+
+A migration will move existing configuration onto a new default store.
+
+A new `ControllerHelpers::Store` concern provides a `current_store` helper
+to fetch a helper based on the request's domain.
+
+### Better guest user tracking
+
+Now we are using a signed cookie to store the guests unique token
+in the browser. This allows customers who close their browser to
+continue their shopping when they visit again. More importantly
+it allows you as a store owner to uniquely identify your guests orders.
+Since we set `cookies.signed[:guest_token]` whenever a vistor comes
+you may also use this cookie token on other objects than just orders.
+For instance if a guest user wants to favorite a product you can
+assign the `cookies.signed[:guest_token]` value to a token field on your
+favorites model. Which will then allow you to analyze the orders and
+favorites this user has placed before which is useful for recommendations.
+
+## Core
+
+* Drop first_name and last_name fields from spree_credit_cards. Add
+ first_name & last_name methods for now to keep ActiveMerchant happy.
+
+ Jordan Brough
+
+* Replaced cookies.signed[:order_id] with cookies.signed[:guest_token].
+
+ Now we are using a signed cookie to store the guests unique token
+ in the browser. This allows customers who close their browser to
+ continue their shopping when they visit again. More importantly
+ it allows you as a store owner to uniquely identify your guests orders.
+ Since we set cookies.signed[:guest_token] whenever a vistor comes
+ you may also use this cookie token on other objects than just orders.
+ For instance if a guest user wants to favorite a product you can
+ assign the cookies.signed[:guest_token] value to a token field on your
+ favorites model. Which will then allow you to analyze the orders and
+ favorites this user has placed before which is useful for recommendations.
+
+ Jeff Dutil
+
+* Order#token is no longer fetched from another table.
+
+ Both Spree::Core::TokeResource and Spree::TokenizedPersmission are deprecated.
+ Order#token value is now persisted into spree_orders.guest_token. Main motivation
+ here is save a few extra queries when creating an order. The TokenResource
+ module was being of no use in spree core.
+
+ NOTE: Watch out for the possible expensive migration that come along with this
+
+ Washington L Braga Jr
+
+* Replaced session[:order_id] usage with cookies.signed[:order_id].
+
+ Now we are using a signed cookie to store the order id on a guests
+ browser client. This allows customers who close their browser to
+ continue their shopping when they visit again.
+ Fixes #4319
+
+ Jeff Dutil
+
+
+* Order#process_payments! no longer raises. Gateways must raise on failing authorizations.
+
+ Now it's a Gateway or PaymentMethod responsability to raise a custom
+ exception any time an authorization fails so that it can be rescued
+ during checkout and proper action taken.
+
+* Assign request headers env to Payment when creating it via checkout.
+
+ This might come in handy for some gateways, e.g. Adyen, actions that require
+ data such as user agent and accept header to create user profiles. Previously
+ we had no way to access the request headers from within a gateway class
+
+* More accurate and simpler Order#payment_state options.
+
+ Balance Due. Paid. Credit Owed. Failed. These are the only possible values
+ for order payment_state now. The previous `pending` state has been dropped
+ and order updater logic greatly improved as it now mostly consider total
+ values rather than doing last payment state checks.
+
+ Huge thanks to dan-ding. See https://github.com/spree/spree/issues/4605
+
+* Config settings related to mail have been removed. This includes
+ `enable_mail_delivery`, `mail_bcc`, `intercept_email`,
+ `override_actionmailer_config`, `mail_host`, `mail_domain`, `mail_port`,
+ `secure_connection_type`, `mail_auth_type`, `smtp_username`, and
+ `smtp_password`.
+
+ These should instead be [configured on actionmailer directly](http:https://api.rubyonrails.org/classes/ActionMailer/Base.html#class-ActionMailer::Base-label-Configuration+options).
+ The existing functionality can also be used by including the [spree_mail_settings](https://github.com/spree-contrib/spree_mail_settings) gem.
+
+ John Hawthorn
+
+* refactor the api to use a general importer in `lib/spree/importer/order.rb`
+
+ Peter Berkenbosch
+
+* Ensure transition to payment processing state happens outside transaction.
+
+ Chris Salzberg
+
+* Increase the precision of the amount/price columns in order for support other currencies. See https://github.com/spree/spree/issues/4657
+
+ Gonzalo Moreno
+
+* Preferences on models are now stored in a serialized `preferences` column instead of the `Spree::Preferences` table.
+
+ `Spree::Preferences` are still used for configuration (like `Spree::Config`).
+ For models with preferences (`Calculator`, `PromotionRule`, and
+ `PaymentMethod` in spree core) they are now serialized using
+ `ActiveRecord::Base.serialize`, storing the preferences as YAML in the
+ `preferences` column.
+
+ ```
+ > c = Spree::Calculator.first
+ => #<Spree::Calculator::Shipping::FlatRate id: 1, type: "Spree::Calculator::Shipping::FlatRate",
+ calculable_id: 1, calculable_type: "Spree::ShippingMethod", created_at: "2014-06-29 21:56:59",
+ updated_at: "2014-06-29 21:57:00", preferences: {:amount=>5, :currency=>"USD"}>
+ > c.preferred_amount
+ => 5
+ > c.preferred_amount = 10
+ => 10
+ > c
+ => #<Spree::Calculator::Shipping::FlatRate id: 1, type: "Spree::Calculator::Shipping::FlatRate",
+ calculable_id: 1, calculable_type: "Spree::ShippingMethod", created_at: "2014-06-29 21:56:59",
+ updated_at: "2014-06-29 21:57:00", preferences: {:amount=>10, :currency=>"USD"}>
+ ```
+
+ John Hawthorn
+
+* Add Spree::Store model for basic multi-store/multi-domain support
+
+ This provides a basic framework for multi-store/multi-domain, based on the
+ spree-multi-domain extension. Some existing configuration has been moved to
+ this model, so that they can have different values depending on the site
+ being served:
+
+ * `Spree::Config[:site_name]` is moved to `name`
+ * `Spree::Config[:site_url]` is moved to `url`
+ * `Spree::Config[:default_meta_description]` is moved to `meta_description`
+ * `Spree::Config[:default_meta_keywords]` is moved to `meta_keywords`
+ * `Spree::Config[:default_seo_title]` is moved to `seo_title`
+
+ A migration will move existing configuration onto a new default store.
+
+ A new `ControllerHelpers::Store` concern provides a `current_store` helper
+ to fetch a helper based on the request's domain.
+
+ Jeff Dutil, Clarke Brunsdon, and John Hawthorn
+
+## API
+
+* Support existing credit card feature on checkout.
+
+ Checkouts_controller#update now uses the same Order::Checkout#update_from_params
+ from spree frontend which help us to remove a lot of duplicated logic. As a
+ result of that `payment_source` params must be sent now outsite the `order` key.
+
+ Before you'd send a request like this:
+
+ ```ruby
+ api_put :update, :id => order.to_param, :order_token => order.guest_token,
+  :order => {
+  :payments_attributes => [{ :payment_method_id => @payment_method.id.to_s }],
+  :payment_source => { @payment_method.id.to_s => { name: "Spree" } }
+  }
+ ```
+
+ Now it should look like this:
+
+ ```ruby
+ api_put :update, :id => order.to_param, :order_token => order.guest_token,
+  :order => {
+  :payments_attributes => [{ :payment_method_id => @payment_method.id.to_s }]
+  },
+  :payment_source => {
+  @payment_method.id.to_s => { name: "Spree" }
+  }
+ ```
+
+ Josh Hepworth and Washington
+
+* api/orders/show now display credit cards as source under payment
+
+ Washington Luiz
+
+* refactor the api to use a general importer in core gem.
+
+ Peter Berkenbosch
+
+* Shipment manifests viewed within the context of an order no longer return variant info. The line items for the order already contains this information. #4498
+
+ * Ryan Bigg
+
+## Frontend
+
+* The api key that was previously placed in the dom for ajax requests has been
+ removed since the api now uses the session to authenticate the user.
+
+* Mostly inspired by Jeff Squires extension spree_reuse_credit card, checkout
+ now can remember user credit card info. Make sure your user model responds
+ to a `payment_sources` method and customers will be able to reuse their
+ credit card info.
+
+ Washington Luiz
+
+* Use settings from current_store instead of Spree::Config
+
+ Jeff Dutil, John Hawthorn, and Washington Luiz
+
+## Backend
+
+* The api key that was previously placed in the dom for ajax requests has been
+ removed since the api now uses the session to authenticate the user.

guides/layouts/developer/_sidebar.html

@@ -109,6 +109,8 @@ <h3>
  class="toc"></div></li>
  <li><i class="icon-dot"></i><%= link_to "2.1.x to 2.2.x", '/developer/upgrades/two-dot-one-to-two-dot-two' %> <div 
  class="toc"></div></li>
+ <li><i class="icon-dot"></i><%= link_to "2.2.x to 2.3.x", '/developer/upgrades/two-dot-two-to-two-dot-three' %> <div 
+ class="toc"></div></li>
  </ul>
  </li>
  </ul>

guides/layouts/release_notes/_sidebar.html

@@ -7,6 +7,7 @@ <h3>
  <%= link_to 'Versions', '#' %>
  </h3>
  <ul class="js-guides">
+ <li><i class="icon-dot"></i><%= link_to "2.3.0", 'spree_2_3_0' %></li>
  <li><i class="icon-dot"></i><%= link_to "2.2.0", 'spree_2_2_0' %></li>
  <li><i class="icon-dot"></i><%= link_to "2.1.0", 'spree_2_1_0' %></li>
  <li><i class="icon-dot"></i><%= link_to "2.0.0", 'spree_2_0_0' %></li>