Upgrade instructions for v3.3

We're now going to host the upgrade instructions for new Solidus
releases in our guides. We start with v3.3.

Author: waiting-for-dev

docs/upgrading-solidus/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Upgrading Solidus",
+  "position": 7,
+  "collapsible": false,
+  "collapsed": false
+}

docs/upgrading-solidus/v3.3.mdx

@@ -0,0 +1,144 @@
+---
+sidebar_position: 1
+---
+
+import PRLink from '@site/src/theme/PRLink';
+
+# Solidus v3.3 (2022-01-15)
+
+New year, new Solidus release! This time, we acknowledge our [new policy around Ruby & Rails support](https://solidus.io/release_policy/). It also comes with new features, bug fixes, as well as some deprecations that will be removed in the next major release. Take the time to upgrade. We've committed with the community to release more often, so keeping up to date will help you when Solidus v4.0 is out, which will happen sooner than later.
+
+Before getting hands-on, please review our generic [upgrade guides](/getting-started/upgrading-solidus.mdx). You can also check the complete [Changelog](https://github.com/solidusio/solidus/blob/v3.3/CHANGELOG.md) in our repository.
+
+## <PRLink description="Added support for Ruby v3.2" number="4817" />
+
+Solidus v3.3 comes with support for the recently released v3.2 of Ruby. You can safely upgrade to it without Solidus getting in your way.
+
+## <PRLink description="Removed support for Ruby v2.5" number="4845" />
+
+With v3.3, Solidus performs a long-due cleanup of its codebase, removing support for EOL's Ruby versions v2.5 & v2.6. If you're on Solidus v3.2 and you want to upgrade to v3.3:
+
+- Update your Solidus v3.2 store to Ruby v2.6.
+- Update your Solidus v3.2 store to Ruby v2.7.
+- Update your Solidus v3.2 store to v3.3.
+
+## <PRLink description="Removed support for Ruby v2.6" number="4848" />
+
+Solidus v3.3 no longer supports Ruby v2.6, which reached the EOL status. You'll need to:
+
+- Update your Solidus v3.2 store to Ruby v2.7.
+- Update your Solidus v3.2 store to v3.3.
+
+## <PRLink description="Removed support for Rails v5.2" number="4850" />
+
+Rails v5.2 (EOL) support has been removed from Solidus v3.3:
+
+- Update your Solidus v3.2 store to Rails v6.0.
+- Update your Solidus v3.2 store to v3.3.
+
+## <PRLink description="Support for the new Colorado delivery fee" number="4491" />
+
+We've updated our taxation system to support the new [Colorado retail delivery fee](https://tax.colorado.gov/retail-delivery-fee):
+
+- Create a new `Spree::Zone` for the state of Colorado.
+- Create a new `Spree::TaxRate` within that zone, with:
+  - The new `Spree::Calculator::FlatFee` as its base calculator.
+  - An amount of 0.27$.
+  - The new `Spree::TaxRate#level` enum to `:order`
+
+We also provide a task to help with the process (it'll add the new tax to the default category if it exists):
+
+```bash
+bundle exec rake taxes:colorado_delivery_fee
+```
+
+## <PRLink description="Deprecated #redirect_back_or_default" number="4533" />
+
+We've deprecated the `#redirect_back_or_default` method. Instead, you should use:
+
+- [`#stored_spree_user_location_or`](https://www.rubydoc.info/github/plataformatec/devise/Devise/Controllers/StoreLocation) when using solidus_auth_devise.
+- [Rails' `#redirect_back`](https://api.rubyonrails.org/classes/ActionController/Redirecting.html#method-i-redirect_back) method for Rails < v7.0.
+- [Rails' `#redirect_back_or_to`](https://api.rubyonrails.org/classes/ActionController/Redirecting.html#method-i-redirect_back_or_to) method for Rails >= v7.0.
+
+## <PRLink description="Version upgraded for packaged underscore.js" number="4660" />
+
+We've upgraded the packaged version of [underscore.js](https://underscorejs.org/) from v1.8.3 to v1.13.6. In case you were using it, check compatibility.
+
+## <PRLink description="Deprecated #mails_from preference" number="4712" />
+
+We've deprecated the `#mails_from` preference, as it wasn't used in the Solidus codebase anymore. Make sure you aren't using it for anything else. Otherwise, the expected way to handle the default `From:` field for transactional emails is the `Spree::Store#mail_from_address` attribute.
+
+## <PRLink description="Configurable promotion adjuster" number="4460" />
+
+You can now change what the default promotion adjuster does. Configure the `Spree::Config.promotion_adjuster_class` preference with a class that takes the order on initialization and responds to the `#adjust!` method.
+
+```ruby title="config/initializers/spree.rb"
+Spree.config do |config|
+  # ...
+  config.promotion_adjuster_class = 'MyStore::PromotionAdjuster'
+end
+```
+
+```ruby title="app/models/my_store/promotion_adjuster.rb"
+module MyStore
+  class PromotionAdjuster
+    def initialize(order)
+      @order = order
+    end
+
+    def adjust!
+      # ...
+    end
+  end
+end
+```
+
+## <PRLink description="Configurable algorithm to prioritize store credits" number="4677" />
+
+Before v3.3, store credits were always sorted by the priority of their type. Now you can change that behavior by configuring the `Spree::Config.store_credit_prioritizer_class` preference with a class that takes the store credits and the order on initialization and responds to the `#call` method.
+
+```ruby title="config/initializers/spree.rb"
+Spree.config do |config|
+  # ...
+  config.store_credit_prioritizer_class = 'MyStore::StoreCreditPrioritizer'
+end
+```
+
+```ruby title="app/models/my_store/store_credit_prioritizer.rb"
+module MyStore
+  class StoreCreditPrioritizer
+    def initialize(store_credits, order)
+      @store_credits = store_credits
+      @order = order
+    end
+
+    def call
+      # ...
+    end
+  end
+end
+```
+
+## <PRLink description="Allow shipping category on variants" number="4739" />
+
+It was already possible for a variant to have a different tax category than its product. Now, that's also true for the shipping category.
+
+## <PRLink description="Default implementation for PaymentMethod#try_void" number="4843" />
+
+When adding a new payment integration, it was required to implement the `PaymentMethod#try_void` method. However, it turned out that the logic was always very similar. We now provide a default implementation that would be enough in most situations.
+
+## <PRLink description="Variant and product autocomplete functions flexibility with Ransack" number="4767" />
+
+It's now possible to customize the autocompletion for variants and products on the backend via a callback returning a Ransack query. E.x.:
+
+```javascript
+$('#product-dropdown').productAutocomplete({
+  multiple: false,
+  searchCallback: (searchString) => ({
+    q: {
+      name_cont: searchString,
+      available_on_not_null: true
+    })
+  }
+})
+```

src/css/custom.css

@@ -19,3 +19,14 @@
     --ifm-color-primary-lightest: #ffffff;
     --ifm-background-color: #242830;
 }
+
+.pull_request {
+  background: url('/static/img/pr.png') center left/1em no-repeat;
+  display: inline-block;
+  padding-left: 1.1em;
+}
+
+h2 a.pull_request {
+  color: #000;
+  font-size: 90%;
+}

src/theme/PRLink.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import PRIcon from '@site/static/img/pr.png';
+
+export default function PRLink(props) {
+  return (
+    <a class="pull_request" href={ `https://github.com/solidusio/solidus/pull/${ props.number }` }>
+      { props.description }
+    </a>
+  );
+};