Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Update documentation on Spree 3 to 4 migration

Damian Legawieccdedda23af45
diff --git a/guides/src/content/developer/4_advanced/existing_app_tutorial.md b/guides/src/content/developer/4_advanced/existing_app_tutorial.md
index 687c89923d..412eddc8cb 100644
--- a/guides/src/content/developer/4_advanced/existing_app_tutorial.md
+++ b/guides/src/content/developer/4_advanced/existing_app_tutorial.md
@@ -18,7 +18,7 @@ in your project root directory.
1. Add Spree gems to your `Gemfile`
- **Rails 6.0 and 6.1**
+ **Rails 5.2, 6.0 and 6.1**
```ruby
gem 'spree', '~> 4.2'
@@ -28,14 +28,6 @@ in your project root directory.
gem 'sassc', github: 'sass/sassc-ruby', branch: 'master' # only needed for MacOS and Ruby 3.0
```
- **Rails 5.2**
-
- ```ruby
- gem 'spree', '~> 3.7.0'
- gem 'spree_auth_devise', '~> 3.5'
- gem 'spree_gateway', '~> 3.4'
- ```
-
**Rails 5.1**
```ruby
diff --git a/guides/src/content/developer/upgrades/four-dot-oh-to-four-dot-one.md b/guides/src/content/developer/upgrades/four-dot-oh-to-four-dot-one.md
index 9b1921cac3..20a118ee18 100644
--- a/guides/src/content/developer/upgrades/four-dot-oh-to-four-dot-one.md
+++ b/guides/src/content/developer/upgrades/four-dot-oh-to-four-dot-one.md
@@ -41,10 +41,10 @@ rails db:migrate
## Decide what to do next
-Now you have two options:
+You have two options:
1. Migrate to the new Storefront UI
- 1. Stay at the current UI
+ 2. Stay at the current UI
## Migrate to the new Storefront UI
@@ -99,19 +99,19 @@ If you wish to not move to the new Storefront UI it's still an option. Just proc
Copy over views from: 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 custom changes!
+ **WARNING** remember to not overwrite your customizations!
3. 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 to `app/stylesheets`
- **WARNING** remember to not overwrite your custom changes!
+ **WARNING** remember to not overwrite your customizations!
4. 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 to `app/javascripts`
- **WARNING** remember to not overwrite your custom changes!
+ **WARNING** remember to not overwrite your customizations!
## Read the release notes
diff --git a/guides/src/content/developer/upgrades/three-dot-seven-to-four-dot-oh.md b/guides/src/content/developer/upgrades/three-dot-seven-to-four-dot-oh.md
index abe97bcffe..dd729cce7b 100644
--- a/guides/src/content/developer/upgrades/three-dot-seven-to-four-dot-oh.md
+++ b/guides/src/content/developer/upgrades/three-dot-seven-to-four-dot-oh.md
@@ -20,75 +20,17 @@ This is the safest and recommended method.
## Update your Ruby version to 2.5.0 at least
-Spree 4.0 and Rails 6.0 require Ruby 2.5.0 at least so you need to bump the ruby version in your project's `Gemfile` and `.ruby-version` files.
-
-## Update your Rails version to 6.0
-
-Please follow the
-[official Rails guide](https://edgeguides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-from-rails-5-2-to-rails-6-0)
-to upgrade your store.
+Spree 4.0 requires Ruby 2.5.0 at least so you need to bump the ruby version in your project's `Gemfile` and `.ruby-version` files.
## Migrate from Paperclip to ActiveStorage
In Spree 3.6 we deprecated [Paperclip support in favour of ActiveStorage](/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 defualt Rails storage engine since Rails 5.2 release.
-In Spree 4.0 we completely removed Paperclip support in favour of ActiveStorage.
-
-Also please remove any occurances of `Rails.application.config.use_paperclip` and `Configuration::Paperclip` in your codebase.
-
-Please follow the [official Paperclip to ActiveStorage migration guide](https://github.com/thoughtbot/paperclip/blob/master/MIGRATING.md)
-
-## Replace `class_eval` with `Module.prepend`
-
-Rails 6.0 ships with [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 - `app/models/spree/order_decorator.rb`
-
-```ruby
-Spree::Order.class_eval do
- has_many :new_custom_model
-
- def some_method
- # ...
- end
-end
-```
-
-New decorator - `app/models/my_store/spree/order_decorator.rb`
-
-```ruby
-module MyStore
- module Spree
- module OrderDecorator
- def self.prepended(base)
- base.has_many :new_custom_model
- end
-
- def some_method
- # ...
- end
- end
- end
-end
-
-::Spree::Order.prepend(MyStore::Spree::OrderDecorator)
-```
-
-When migrating 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
+In Spree 4.0 we've removed Paperclip support in favour of ActiveStorage.
-Spree::Base.singleton_class.send :prepend, Spree::BaseDecorator
-```
-
-Please also consider other options for [Logic Customization](/developer/customization/logic.html).
+Please remove also any occurances of `Rails.application.config.use_paperclip` and `Configuration::Paperclip` from your codebase.
-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)
+Please follow the [official Paperclip to ActiveStorage migration guide](https://github.com/thoughtbot/paperclip/blob/master/MIGRATING.md).
## Replace OrderContents with services in your codebase
@@ -188,29 +130,94 @@ Spree::Checkout::RemoveStoreCredit.call(order: order)
If you're using [Address Book](https://github.com/spree-contrib/spree_address_book) extension you need to remove as this feature was [merged into core Spree](/release_notes/4_0_0.html#address-book-support).
-### Remove it from Gemfile
+1. Remove this line from `Gemfile`
+
+ ```ruby
+ gem 'spree_address_book', github: 'spree-contrib/spree_address_book'
+ ```
-Remove this line:
+2. Remove this line from `vendor/assets/javascripts/spree/frontend/all.js`
+
+ ```
+ //= require spree/frontend/spree_address_book
+ ```
+
+3. Remove this line from `vendor/assets/stylesheets/spree/frontend/all.css`
+
+ ```
+ //= require spree/frontend/spree_address_book
+ ```
+
+## Replace `class_eval` with `Module.prepend` (only for Rails 6)
+
+Rails 6.0 ships with [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 - `app/models/spree/order_decorator.rb`
```ruby
-gem 'spree_address_book', github: 'spree-contrib/spree_address_book'
+Spree::Order.class_eval do
+ has_many :new_custom_model
+
+ def some_method
+ # ...
+ end
+end
```
-### Remove it from `vendor/assets/javascripts/spree/frontend/all.js`
+New decorator syntax - `app/models/my_store/spree/order_decorator.rb`
-Remove this line if your're using `spree_frontend`:
+```ruby
+module MyStore
+ module Spree
+ module OrderDecorator
+ def self.prepended(base)
+ base.has_many :new_custom_model
+ end
-```
-//= require spree/frontend/spree_address_book
+ def some_method
+ # ...
+ end
+ end
+ end
+end
+
+::Spree::Order.prepend(MyStore::Spree::OrderDecorator)
```
-### Remove it from `vendor/assets/stylesheets/spree/frontend/all.css`
+When migrating 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:
-Remove this line if your're using `spree_frontend`:
+```ruby
+module Spree::BaseDecorator
+ def spree_base_scopes
+ # custom implementation
+ end
+end
+Spree::Base.singleton_class.send :prepend, Spree::BaseDecorator
```
-//= require spree/frontend/spree_address_book
-```
+
+Please also consider other options for [Logic Customization](/developer/customization/logic.html).
+
+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/)
## Update Gemfile
diff --git a/guides/src/content/release_notes/4_0_0.md b/guides/src/content/release_notes/4_0_0.md
index 3f97a79d8e..877f841990 100644
--- a/guides/src/content/release_notes/4_0_0.md
+++ b/guides/src/content/release_notes/4_0_0.md
@@ -10,7 +10,7 @@ order: 2
### Rails 6.0 support
-Spree 4.0 is fully compatible with [Rails 6.0](https://edgeguides.rubyonrails.org/6_0_release_notes.html)
+Spree 4.0 is fully compatible with both Rails 5.2 and [Rails 6.0](https://edgeguides.rubyonrails.org/6_0_release_notes.html)
and the new default [Zeitwerk code autoloader](https://weblog.rubyonrails.org/2019/2/22/zeitwerk-integration-in-rails-6-beta-2/).
### Storefront and Admin Panel moved to Bootstrap 4.2
diff --git a/guides/src/content/release_notes/4_2_0.md b/guides/src/content/release_notes/4_2_0.md
index 7568d19d8e..e1e9a53c70 100644
--- a/guides/src/content/release_notes/4_2_0.md
+++ b/guides/src/content/release_notes/4_2_0.md
@@ -14,7 +14,7 @@ This release was intended to make Spree **accessible to everyone** in **every co
### Ruby 3.0 and Rails 6.1 support
-Spree 4.2 can be run on Ruby 2.5, 2.6, 2.7, and recently released 3.0. Spree 4.2 supports **both Rails 6.0 and 6.1** out of the box, so you don't need to upgrade to Rails 6.1 straight away, you can first move to Spree 4.2 and later perform the Rails upgrade, minimizing the risk of any issues. Please see [Rails 6.1 announcement](https://weblog.rubyonrails.org/2020/12/9/Rails-6-1-0-release/) to check out the new amazing features that are packed in that release.
+Spree 4.2 can be run on Ruby 2.5, 2.6, 2.7, and recently released 3.0. Spree 4.2 supports **Rails 5.2, 6.0 and 6.1** out of the box, so you don't need to upgrade to Rails 6.1 straight away, you can first move to Spree 4.2 and later perform the Rails upgrade independently, minimizing the risk of any issues. Please see [Rails 6.1 announcement](https://weblog.rubyonrails.org/2020/12/9/Rails-6-1-0-release/) to check out the new amazing features that are packed in that release.
### New responsive Admin Panel UI