@spree/docs 0.1.0

package/dist/developer/upgrades/2.3-to-2.4.md

@@ -0,0 +1,42 @@
+---
+title: 2.3 to 2.4
+section: upgrades
+description: 'This guide covers upgrading a 2.3 Spree store, to a 2.4 store.'
+---
+
+This guide has been written from the perspective of a blank Spree 2.3 store with no extensions.
+
+If you have extensions that your store depends on, you will need to manually verify that each of those extensions works within your 2.4 store once this upgrade is complete. Typically, extensions that are compatible with this version of Spree will have a 2-4-stable branch.
+
+## Upgrade Rails
+
+For this Spree release, you will need to upgrade your Rails version to at least 4.1.8.
+
+```ruby
+gem 'rails', '~> 4.1.8'
+```
+
+## Upgrade Spree
+
+```ruby
+gem 'spree', '~> 2.4'
+```
+
+Run `bundle update spree`.
+
+## Copy and run migrations
+
+Copy over the migrations from Spree (and any other engine) and run them using
+these commands:
+
+```bash
+rake railties:install:migrations
+```
+
+```bash
+rake db:migrate
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [2.4.0 Release Notes](https://github.com/spree/spree/releases/tag/v2.4.0).

package/dist/developer/upgrades/3.0-to-3.1.md

@@ -0,0 +1,47 @@
+---
+title: 3.0 to 3.1
+section: upgrades
+order: 9
+description: 'This guide covers upgrading a 3.0 Spree store, to a 3.1 store'
+---
+
+## Update gems
+
+```bash
+bundle update
+```
+
+## Copy and run migrations
+
+Copy over the migrations from Spree and any other engine and run them using these commands:
+
+```bash
+rake railties:install:migrations
+rake db:migrate
+```
+
+## Additional information
+
+### Make sure to v1 namespace custom rabl templates & overrides.
+
+If your rabl templates reference others with extend you'll need to add the v1 namespace.
+
+For example:
+
+```ruby
+extends 'spree/api/zones/show'
+```
+
+Becomes:
+
+```ruby
+extends 'spree/api/v1/zones/show'
+```
+
+### Remove `Spree::Config.check_for_spree_alerts`
+
+If you were disabling the alert checks you'll now want to remove this preference from `config/initializers/spree.rb` as it's no longer used.
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [3.1.0 Release Notes](https://github.com/spree/spree/releases/tag/v3.1.0).

package/dist/developer/upgrades/3.1-to-3.2.md

@@ -0,0 +1,34 @@
+---
+title: 3.1 to 3.2
+section: upgrades
+order: 8
+description: 'This guide covers upgrading a 3.1 Spree store, to a 3.2 store.'
+---
+
+### Update your Rails version to 5.0
+
+Spree 3.1 requires Rails 4.2 at a minimum. Please follow the [official Rails guide](http://edgeguides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-from-rails-4-2-to-rails-5-0) to upgrade your application.
+
+### Update gems
+
+```bash
+bundle update
+```
+
+### Run `bundle update`
+
+### Install missing migrations
+
+```bash
+rake railties:install:migrations
+```
+
+### Run migrations
+
+```bash
+rails db:migrate
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [3.2.0 Release Notes](https://github.com/spree/spree/releases/tag/v3.2.0).

package/dist/developer/upgrades/3.2-to-3.3.md

@@ -0,0 +1,70 @@
+---
+title: 3.2 to 3.3
+section: upgrades
+order: 7
+description: 'This guide covers upgrading a 3.2 Spree store, to a 3.3 store.'
+---
+
+### Update your Rails version to 5.1
+
+Spree 3.3 requires Rails 5.1 at a minimum. Please follow the [official Rails guide](http://edgeguides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-from-rails-5-0-to-rails-5-1) to upgrade your application.
+
+### Update gems
+
+```bash
+bundle update
+```
+
+### Install missing migrations
+
+```bash
+rake railties:install:migrations
+```
+
+### Run migrations
+
+```bash
+rails db:migrate
+```
+
+### Include `UserMethods` in your `User` class
+
+With this release, we're not including this automatically. You need to do it manually if you're not using `spree_auth_devise`.
+
+You need to include `Spree::UserMethods` in your user class, eg.
+
+```ruby
+class User
+  include UserAddress
+  include UserMethods
+  include UserPaymentSource
+end
+```
+
+### Update `aws-sdk` gem to `>= 2.0`
+
+Spree 3.3 comes with paperclip 5.1 support so if you're using Amazon S3 storage you need to change in your Gemfile, from:
+
+```ruby
+gem 'aws-sdk', '< 2.0'
+```
+
+to:
+
+```ruby
+gem 'aws-sdk', '>= 2.0'
+```
+
+and run `bundle update aws-sdk`
+
+In your paperclip configuration, you also need to specify `s3_region` attribute eg. [https://github.com/spree/spree/blame/master/guides/content/developer/customization/s3_storage.md\#L27](https://github.com/spree/spree/blame/master/guides/content/developer/customization/s3_storage#L27)
+
+See also [RubyThursday episode](https://rubythursday.com/episodes/ruby-snack-27-upgrade-paperclip-and-aws-sdk-in-prep-for-rails-5) walkthrough of upgrading paperclip in your project.
+
+### Add jquery.validate to your project if you've used it directly from Spree
+
+If your application.js file includes line `//= require jquery.validate/jquery.validate.min` you will need to add this file manually to your project because this library was [removed from Spree in favor of native HTML5 validation](https://github.com/spree/spree/pull/8173).
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [3.3.0 Release Notes](https://github.com/spree/spree/releases/tag/v3.3.0).

package/dist/developer/upgrades/3.3-to-3.4.md

@@ -0,0 +1,36 @@
+---
+title: 3.3 to 3.4
+section: upgrades
+order: 6
+description: 'This guide covers upgrading a 3.3 Spree store, to a 3.4 store.'
+---
+
+### Update gems
+
+```bash
+bundle update
+```
+
+### Install missing migrations
+
+```bash
+rake railties:install:migrations
+```
+
+### Run migrations
+
+```bash
+rails db:migrate
+```
+
+### Migrate Spree::Taxon icons to Spree Assets
+
+We changed `Spree::Taxon` icon to use `Spree::Asset` to unify attachment usage across all Spree models. If you were using icon images in `Spree::Taxon` please run this to migrate your icons:
+
+```bash
+rails db:migrate_taxon_icons
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [3.4.0 Release Notes](https://github.com/spree/spree/releases/tag/v3.4.0).

package/dist/developer/upgrades/3.4-to-3.5.md

@@ -0,0 +1,44 @@
+---
+title: 3.4 to 3.5
+section: upgrades
+order: 5
+description: 'This guide covers upgrading a 3.4 Spree store, to a 3.5 store.'
+---
+
+### Update gems
+
+```bash
+bundle update
+```
+
+### Install missing migrations
+
+```bash
+rake railties:install:migrations
+```
+
+### Run migrations
+
+```bash
+rails db:migrate
+```
+
+### Install Spree Analytics Trackers extension
+
+If you were previously using Analytics Trackers feature you need to install it as an extension as it was [extracted from the core](https://github.com/spree/spree/pull/8408).
+
+1. Add [Spree Analytics Trackers](https://github.com/spree-contrib/spree_analytics_trackers) to your `Gemfile`:
+
+```bash
+bundle add spree_analytics_trackers
+```
+
+2. Copy and run migrations:
+
+```bash
+bin/rails g spree_analytics_trackers:install
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [3.5.0 Release Notes](https://github.com/spree/spree/releases/tag/v3.5.0).

package/dist/developer/upgrades/3.5-to-3.6.md

@@ -0,0 +1,40 @@
+---
+title: 3.5 to 3.6
+section: upgrades
+order: 4
+description: 'This guide covers upgrading a 3.5 Spree application, to a 3.6 application.'
+---
+
+## Update your Rails version to 5.2
+
+Spree 3.6 requires Rails 5.2 at a minimum. Please follow the [official Rails guide](http://guides.rubyonrails.org/5_2_release_notes.html#upgrading-to-rails-5-2) to upgrade your application.
+
+## Update gems
+
+```bash
+bundle update
+```
+
+### (Optional) Migrate to ActiveStorage (optional)
+
+Please follow the [official paperclip guide](https://github.com/thoughtbot/paperclip/blob/master/MIGRATING) if you want to use ActiveStorage instead of paperclip.
+
+You can still use paperclip for attachment management by setting `SPREE_USE_PAPERCLIP` environment variable to `true`, but keep in mind that paperclip is DEPRECATED and we will remove paperclip support in Spree 4.0.
+
+### Install missing migrations
+
+```bash
+rake railties:install:migrations
+```
+
+### Run migrations
+
+```bash
+rails db:migrate
+```
+
+You're good to go!
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [3.6.0 Release Notes](https://github.com/spree/spree/releases/tag/v3.6.0).

package/dist/developer/upgrades/3.6-to-3.7.md

@@ -0,0 +1,62 @@
+---
+title: 3.6 to 3.7
+section: upgrades
+order: 3
+description: 'This guide covers upgrading a 3.6 Spree application, to version 3.7.'
+---
+
+## Update gems
+
+Run
+
+```bash
+bundle update
+```
+
+## Install missing migrations
+
+```bash
+rake railties:install:migrations
+```
+
+## Run migrations
+
+```bash
+rails db:migrate
+```
+
+## Migrate Taxon icons to Spree Assets
+
+We renamed `TaxonIcon` to `TaxonImage` to clarify usage of this model. If you were using `TaxonIcon` please run this to migrate your icons to images:
+
+```bash
+rails db:migrate_taxon_icons_to_images
+```
+
+## Ensure all Orders associated to Store
+
+Orders needs to be associated to Stores. To ensure all existing `Order` are associated with `Store` please run this:
+
+```bash
+rails db:associate_orders_with_store
+```
+
+This will associate all Orders without Store to the default Store. This can take some time depending on your volume of data.
+
+## Ensure all Orders have currency present
+
+To enhance multi currency capabilities we've made `currency` presence obligatory in `Order` model. To ensure all existing `Orders` have `currency` present please run this command:
+
+```bash
+rails db:ensure_order_currency_presence
+```
+
+This will set `currency` in Orders without currency set to `Spree::Config[:default_currency]` value. This can take some time depending on your volume of data.
+
+## Replace `guest_token` with `token` in your codebase
+
+`Order#guest_token` was renamed to `Order#token` in order to unify the experience for guest checkouts and orders placed by signed in users.
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [3.7.0 Release Notes](https://github.com/spree/spree/releases/tag/v3.7.0).

package/dist/developer/upgrades/3.7-to-4.0.md

@@ -0,0 +1,152 @@
+---
+title: 3.7 to 4.0
+section: upgrades
+order: 2
+description: This guide covers upgrading a 3.7 Spree application to Spree 4.0.
+---
+
+> **NOTE:** If you're on an older version than 3.7 please follow previous upgrade guides and perform those upgrades incrementally**, eg.
+> 
+> 1. [upgrade 3.4 to 3.5](3.4-to-3.5)
+> 2. [upgrade 3.5 to 3.6](3.5-to-3.6)
+> 3. [upgrade 3.6 to 3.7](3.6-to-3.7)
+
+## Update your Ruby version to 2.5 or later
+
+Spree 4.0 requires Ruby 2.5 so you need to change the ruby version in your project's `Gemfile` and `.ruby-version` files. And of course you need to install Ruby 2.5 or later. If you're using RVM you can do it like this:
+
+```bash
+rvm install 2.5
+rvm use 2.5
+```
+
+## Migrate from Paperclip to ActiveStorage
+
+In Spree 3.6 we deprecated [Paperclip support in favor of ActiveStorage](https://guides.spreecommerce.org/release_notes/3_6_0.html#active-storage-support). Paperclip gem itself isn't maintained anymore and it is recommended to move to ActiveStorage as it is the default Rails storage engine since Rails 5.2 release.
+
+In Spree 4.0 we've removed Paperclip support in favor of ActiveStorage.
+
+Please remove also any occurrences of `Rails.application.config.use_paperclip` and `Configuration::Paperclip` from your codebase.
+
+Please follow the [official Paperclip to ActiveStorage migration guide](https://github.com/thoughtbot/paperclip/blob/master/MIGRATING).
+
+## Remove `spree_address_book` extension
+
+If you're using the [Address Book](https://github.com/spree-contrib/spree_address_book) extension you need to remove it as this feature was merged into [core Spree](https://github.com/spree/spree/releases/tag/v4.0.0).
+
+1. Remove this line from `Gemfile`
+
+    ```bash
+    bundle remove spree_address_book
+    ```
+
+2. Remove this line from `vendor/assets/javascripts/spree/frontend/all.js`
+
+   ```text
+    //= require spree/frontend/spree_address_book
+   ```
+
+3. Remove this line from `vendor/assets/stylesheets/spree/frontend/all.css`
+
+   ```text
+    //= require spree/frontend/spree_address_book
+   ```
+
+## Update your `Gemfile`
+
+```ruby
+gem 'spree', '~> 4.0'
+gem 'spree_auth_devise', '~> 4.0'
+gem 'spree_gateway', '~> 3.6'
+```
+
+and run
+
+```bash
+bundle update
+```
+
+## Replace `class_eval` with `Module.prepend` only for Rails 6
+
+Rails 6.0 ships with a [new code autoloader called Zeitwerk](https://medium.com/@fxn/zeitwerk-a-new-code-loader-for-ruby-ae7895977e73) which has some [strict rules in terms of file naming and contents](https://github.com/fxn/zeitwerk#file-structure). If you used `class_eval` to extend and modify Spree classes you will need to rewrite those with `Module.prepend`. Eg.
+
+Old decorator syntax:
+
+```ruby
+Spree::Order.class_eval do
+  has_many :new_custom_model
+
+  def some_method
+     # ...
+  end
+end
+```
+
+Replaced with:
+
+```ruby
+module Spree
+  module OrderDecorator
+    def self.prepended(base)
+      base.has_many :new_custom_model
+    end
+
+    def some_method
+      # ...
+    end
+  end
+
+  Order.prepend(OrderDecorator)
+end
+```
+
+When migrating a class method to the new [autoloader](https://medium.com/@fxn/zeitwerk-a-new-code-loader-for-ruby-ae7895977e73) things are a little different because you will have to prepend to the Singleton class as shown in this example:
+
+```ruby
+module Spree::BaseDecorator
+  def spree_base_scopes
+    # custom implementation
+  end
+end
+
+Spree::Base.singleton_class.send :prepend, Spree::BaseDecorator
+```
+
+Please also consider other options for [Logic Customization](/developer/customization).
+
+We recommend also reading through [Ruby modules: Include vs Prepend vs Extend](https://medium.com/@leo_hetsch/ruby-modules-include-vs-prepend-vs-extend-f09837a5b073)
+
+## Update Bootstrap 3 to 4 or stay at Bootstrap 3
+
+Spree 4 uses Bootstrap 4 for both Storefront and Admin Panel. You have two options:
+
+### Stay at Bootstrap 3
+
+As we know this is a big portion of work you can still use Bootstrap 3 for your Storefront.
+
+1. Copy all remaining views by running `bundle exec spree:frontend:copy_views`
+2. Add `bootstrap-sass` gem to your `Gemfile`
+
+   ```ruby
+    gem 'bootstrap-sass', '~> 3.4.1'
+   ```
+
+### Move to Bootstrap 4
+
+[Follow the official Bootstrap 3 to 4 migration guide](https://getbootstrap.com/docs/4.0/migration/)
+
+## Install missing migrations
+
+```bash
+rake railties:install:migrations
+```
+
+## Run migrations
+
+```bash
+rails db:migrate
+```
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [4.0.0 Release Notes](https://github.com/spree/spree/releases/tag/v4.0.0)

package/dist/developer/upgrades/4.0-to-4.1.md

@@ -0,0 +1,92 @@
+---
+title: 4.0 to 4.1
+section: upgrades
+order: 1
+description: This guide covers upgrading a 4.0 Spree application to Spree 4.1.
+---
+
+> **NOTE:** If you're on an older version than 4.0 please follow previous upgrade guides and perform those upgrades incrementally**, eg.
+> 
+> 1. [upgrade 3.5 to 3.6](3.5-to-3.6)
+> 2. [upgrade 3.6 to 3.7](3.6-to-3.7)
+> 3. [upgrade 3.7 to 4.0](3.7-to-4.0)
+
+## Update gems
+
+Run the following command to update your gems to 4.1:
+
+```bash
+bundle update
+```
+
+## Install missing migrations
+
+```bash
+rake railties:install:migrations
+```
+
+## Run migrations
+
+```bash
+rails db:migrate
+```
+
+## Storefront upgrade
+
+You have two options:
+
+1. Migrate to the new Storefront UI
+2. Stay at the current UI
+
+## Migrate to the new Storefront UI
+
+Spree 4.1 comes with a completely new mobile-first ultra-fast Storefront powered by Turbolinks.
+
+To replace your current frontend with the new Spree UI follow these steps:
+
+1. In your project root directory run:
+
+   ```bash
+    rails g spree:frontend:copy_storefront
+   ```
+
+   **WARNING** this will overwrite your current project templates, it's required for the new UI, so if you'll be asked by the generator what to do please choose **A** to proceed
+
+3. Next, you will need to copy over two files:
+   * [spree_storefront.rb](https://raw.githubusercontent.com/spree/spree/main/core/lib/generators/spree/install/templates/config/initializers/spree_storefront.rb) to `config/initializers/spree_storefront.rb`
+   * [spree_storefront.yml](https://raw.githubusercontent.com/spree/spree/main/core/lib/generators/spree/install/templates/config/spree_storefront.yml) to `config/spree_storefront.yml`
+4. If you overwrote any `spree_frontend` [controllers](https://github.com/spree/spree/tree/master/frontend/app/controllers) you will need to either remove your local copies or move your custom logic to [decorators](/developer/customization#extending-controllers)
+5. The same goes for [helpers](https://github.com/spree/spree/tree/master/frontend/app/helpers/spree)
+6. You will also need to remove this line:
+
+   ```javascript
+    //= require spree/frontend/spree_auth
+   ```
+
+   from `vendor/assets/javascripts/spree/frontend.all.js` file
+
+## Stay at the current UI
+
+If you wish to not move to the new Storefront UI it's still an option. Just proceed with the steps described below.
+
+1. Copy over all views from Spree 4.0
+
+   Copy overviews from: [https://github.com/spree/spree/tree/4-0-stable/frontend/app/views](https://github.com/spree/spree/tree/4-0-stable/frontend/app/views) to your application views directory: `app/views`
+
+   **WARNING** remember to not overwrite your customizations!
+
+2. Copy over all Stylesheets from Spree 4.0
+
+   Copy over stylesheets from: [https://github.com/spree/spree/tree/4-0-stable/frontend/app/assets/stylesheets](https://github.com/spree/spree/tree/4-0-stable/frontend/app/assets/stylesheets) to `app/stylesheets`
+
+   **WARNING** remember to not overwrite your customizations!
+
+3. Copy over all JavaScript from Spree 4.0
+
+   Copy over stylesheets from: [https://github.com/spree/spree/tree/4-0-stable/frontend/app/assets/javascripts](https://github.com/spree/spree/tree/4-0-stable/frontend/app/assets/javascripts) to `app/javascripts`
+
+   **WARNING** remember to not overwrite your customizations!
+
+## Read the release notes
+
+For information about changes contained within this release, please read the [4.1.0 Release Notes](https://github.com/spree/spree/releases/tag/v4.1.0).