### Start Development Environment with Docker

Source: https://github.com/solidusio/solidus/blob/main/README.md

Starts the Solidus development environment using Docker Compose. Monitor logs for gem installation progress.

```bash
docker-compose up -d
```

--------------------------------

### Run Solidus Promotions Installation Generator

Source: https://github.com/solidusio/solidus/blob/main/promotions/README.md

Execute the installation generator to set up the necessary database tables and configuration for Solidus Promotions.

```shell
bin/rails generate solidus_promotions:install
```

--------------------------------

### Start Rails Server

Source: https://github.com/solidusio/solidus/blob/main/README.md

Starts the Rails development server to access the Solidus storefront and admin panel.

```bash
bin/rails s
```

--------------------------------

### Perform Solidus Installation Steps Manually

Source: https://github.com/solidusio/solidus/blob/main/README.md

Commands to manually run migrations, seed data, and load sample data after disabling them during the initial installation.

```bash
bin/rails railties:install:migrations
bin/rails db:migrate
bin/rails db:seed
bin/rails spree_sample:load
```

--------------------------------

### Example API Key Authentication with cURL

Source: https://github.com/solidusio/solidus/blob/main/api/openapi/authentication.md

This example demonstrates how to make an API request using an API key with the cURL command-line tool. Replace `API_KEY` with your actual API key.

```bash
curl --header "Authorization: Bearer 1a6a9936ad150a2ee345c65331da7a3ccc2de" http://www.my-solidus-site.com/api/stores
```

--------------------------------

### Generate and Push Example App

Source: https://github.com/solidusio/solidus/wiki/[Legacy]-manual-Solidus-release-instructions

Generate a new Solidus example application for the Heroku button, enabling automatic pushes to GitHub. This script ensures a clean generation process.

```shell
cd ..                               # Go up one dir relative to the solidus repo.
export UPDATE_EXAMPLE_APP_REPO=true # Enable the automatic push to GitHub.
test -d solidus-example-app && \    # If it's not the first time the app is generated
  rm -rf solidus-example-app        # we should remove it to start clean.

# Start the generator script that will generate the app 
# inside ./solidus-example-app and push it to GitHub.
solidus/bin/rails-application-template
```

--------------------------------

### Install Solidus Admin

Source: https://github.com/solidusio/solidus/blob/main/admin/README.md

Add Solidus Admin to your Gemfile and run the installer generator. Manual configuration may be needed for authentication systems other than solidus_auth_devise.

```bash
bundle add solidus_admin
bin/rails g solidus_admin:install
```

--------------------------------

### Initial Configuration for Migration

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

Keep these lines commented out initially to ensure the current promotion system's behavior does not change during the setup phase.

```ruby
# Make sure we use Spree::SimpleOrderContents
# Spree::Config.order_contents_class = "Spree::SimpleOrderContents"
# Set the promotion configuration to ours
# Spree::Config.promotions = SolidusPromotions.configuration
```

--------------------------------

### Install Solidus Gem and Generator

Source: https://github.com/solidusio/solidus/blob/main/README.md

Adds the Solidus gem to your application and runs the installation generator. Ensure the sprockets manifest is generated first.

```bash
bundle add solidus
bin/rails g solidus:install
```

--------------------------------

### Build Solidus Docker Image

Source: https://github.com/solidusio/solidus/blob/main/lib/demo/README.md

Builds a Docker image for Solidus demo purposes. Ensure Docker is installed locally before running.

```shell
docker build -t solidusio/solidus-demo:latest -f lib/demo/Dockerfile .
```

--------------------------------

### Start Rails Server and Services

Source: https://github.com/solidusio/solidus/blob/main/README.md

Run the development server and associated services for Solidus. This command should be executed from the Solidus project root or the sandbox directory.

```bash
bin/dev
```

--------------------------------

### Install Gem Dependencies Locally

Source: https://github.com/solidusio/solidus/blob/main/README.md

Installs gem dependencies for developing Solidus locally. Supports specifying database adapters via the DB environment variable.

```bash
bin/setup
```

--------------------------------

### Install Gem Dependencies with PostgreSQL

Source: https://github.com/solidusio/solidus/blob/main/README.md

Installs gem dependencies for developing Solidus locally, specifically configuring for PostgreSQL.

```bash
export DB=postgresql
bin/setup
```

--------------------------------

### Create New Rails Application

Source: https://github.com/solidusio/solidus/blob/main/README.md

Initializes a new Rails application. Ensure ImageMagick is installed beforehand for Paperclip.

```bash
rails new my_store
```

--------------------------------

### Install Tailwind Configuration Files

Source: https://github.com/solidusio/solidus/blob/main/admin/docs/tailwindcss.md

Run this command to add Tailwind configuration files to your application. This includes a default configuration file and a CSS file for your customizations.

```shell
bin/rails solidus_admin:tailwindcss:install
```

--------------------------------

### Install Gem Dependencies with MySQL/MariaDB

Source: https://github.com/solidusio/solidus/blob/main/README.md

Installs gem dependencies for developing Solidus locally, specifically configuring for MySQL or MariaDB using the mysql2 adapter.

```bash
export DB=mysql
bin/setup
```

--------------------------------

### Implement a Custom Promotion Handler

Source: https://github.com/solidusio/solidus/blob/main/legacy_promotions/README.md

Example of implementing a custom promotion handler. This plain old Ruby object is called at specific points in the checkout flow. Take inspiration from existing handlers for format.

```ruby
module AmazingStore
  module PromotionHandler
    class Payment < Spree::PromotionHandler::Base
      def activate
        promotion = Spree::Promotion.find_by(name: "Special Payment Discount")
        if promotion && eligible_for_payment_promotion?(promotion)
          order.promotions << promotion
        end
      end

      private

      def eligible_for_payment_promotion?(promotion)
        # Replace with your actual eligibility logic
        # For example, check if the order uses a specific payment method
        order.payments.last&.payment_method&.name == "Special Payment Platform"
      end
    end
  end
end
```

--------------------------------

### Run API Tests

Source: https://github.com/solidusio/solidus/blob/main/api/README.md

Execute the API tests using Bundler and RSpec. Ensure you have the necessary dependencies installed.

```bash
bundle exec rspec
```

--------------------------------

### Load Sample Data

Source: https://github.com/solidusio/solidus/blob/main/sample/README.md

Use this rake task to load sample data into your Solidus store for testing purposes. Ensure you have the solidus_sample gem installed.

```bash
bundle exec rake spree_sample:load
```

--------------------------------

### Disable Migrations, Samples, and Seeds During Install

Source: https://github.com/solidusio/solidus/blob/main/README.md

Runs the Solidus installation generator without performing migrations, adding sample data, or seeding the database. These can be performed later.

```bash
bin/rails g solidus:install --migrate=false --sample=false --seed=false
```

--------------------------------

### Run Sandbox Application with Custom Port

Source: https://github.com/solidusio/solidus/blob/main/README.md

Start the sandbox application and expose it on a custom port using the SANDBOX_PORT environment variable. This is useful for running multiple Solidus instances or avoiding port conflicts.

```bash
SANDBOX_PORT=4000 docker-compose up -d
```

```bash
docker-compose exec app bin/sandbox
```

```bash
docker-compose exec app bin/rails server --binding 0.0.0.0 --port 4000
```

--------------------------------

### Run Dockerized Application with Custom Rails Version

Source: https://github.com/solidusio/solidus/blob/main/README.md

Starts the Solidus Dockerized application, allowing runtime customization of the Rails version.

```bash
RAILS_VERSION='~> 5.0' docker-compose up -d
```

--------------------------------

### Backend Stylesheet Manifest

Source: https://github.com/solidusio/solidus/wiki/Customizing-the-Admin-(backend)-Panel

This is an example of a typical `all.css` manifest file. It automatically includes all stylesheets in its directory and subdirectories, along with specific requirements like `spree/backend`.

```css
/*
 * This is a manifest file that'll automatically include all the stylesheets available in this directory
 * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
 * the top of the compiled file, but it's generally better to create a new file per style scope.
 * 
 *= require spree/backend
 *= require_self
 *= require_tree .
 *= require spree/backend/solidus_trackers
*/

```

--------------------------------

### Run All Tests with PostgreSQL

Source: https://github.com/solidusio/solidus/blob/main/README.md

Execute all test specs for Solidus using the `bin/build` script. This script defaults to PostgreSQL but can be configured for other databases. Ensure ChromeDriver is installed.

```bash
createuser --superuser --echo postgres # only the first time
bin/build
```

--------------------------------

### Mount Solidus Admin Engine with Route Constraint

Source: https://github.com/solidusio/solidus/blob/main/admin/README.md

Configure your application's routes to mount the SolidusAdmin engine. This example shows how to use a route constraint to conditionally enable SolidusAdmin, allowing easy switching between admin interfaces.

```ruby
# config/routes.rb
mount SolidusAdmin::Engine, at: '/admin', constraints: ->(req) {
  $redis.get('solidus_admin') == 'true' # or any other logic
}
```

--------------------------------

### Run JavaScript Tests

Source: https://github.com/solidusio/solidus/blob/main/backend/README.md

Execute the JavaScript tests using Teaspoon. Requires ChromeDriver to be installed and accessible.

```bash
bundle exec teaspoon
```

--------------------------------

### Generate CHANGELOG.md for a New Minor Version

Source: https://github.com/solidusio/solidus/wiki/[Legacy]-manual-Solidus-release-instructions

Use github_fast_changelog to generate a preliminary changelog file for the upcoming minor release. Ensure you have the tool installed and a GitHub access token exported.

```shell
gem install github_fast_changelog
export GITHUB_ACCESS_TOKEN=...
git rev-list v2.8...master | github_fast_changelog solidusio/solidus > CHANGELOG_2.9.md
```

--------------------------------

### Check Bourbon Version

Source: https://github.com/solidusio/solidus/wiki/FAQ

Use this command to check the installed version of the Bourbon gem in your application. This is useful for diagnosing issues related to Bourbon mixins.

```bash
bundle show bourbon
```

--------------------------------

### Configure Paperclip for CDN Integration

Source: https://github.com/solidusio/solidus/wiki/Storing-images-on-S3-and-CDN's

Configure Paperclip to use S3 with a CDN host alias. This setup includes cache control headers, S3 protocol, and custom URL generation.

```ruby
# config/initializers/aws.rb

attachment_config = {
  s3_credentials: {
    access_key_id:     Rails.application.secrets.aws_access_key_id,
    secret_access_key: Rails.application.secrets.aws_secret_access_key,
    bucket:            Rails.application.secrets.s3_bucket_name
  },

  storage:        :s3,
  s3_headers:     { 'Cache-Control' => 'max-age=31557600' },
  s3_protocol:    'https',
  s3_region:      Rails.application.secrets.s3_region,
  url:            ':s3_alias_url',
  s3_host_alias:  Rails.application.secrets.cdn_host,
  bucket:         Rails.application.secrets.s3_bucket_name,

  styles: {
    mini:     '48x48>',
    small:    '100x100>',
    product:  '240x240>',
    large:    '600x600>'
  },

  path:          '/products/:id/:style/:basename.:extension',
  default_url:   'noimage/:style.png',
  default_style: 'product',
}

attachment_config.each do |key, value|
   Spree::Image.attachment_definitions[:attachment][key.to_sym] = value
end unless Rails.env.test?
```

--------------------------------

### Create Sandbox Application

Source: https://github.com/solidusio/solidus/blob/main/README.md

Generate a local sandbox application for testing Solidus. This command sets up the necessary environment and loads seed data.

```bash
bin/sandbox
```

--------------------------------

### Update Store Behavior to Use SolidusPromotions

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

Modify the initializer to use the new promotion configuration and enable syncing of order promotions.

```ruby
# Make sure we use Spree::SimpleOrderContents
Spree::Config.order_contents_class = "Spree::SimpleOrderContents"
# Set the promotion configuration to ours
Spree::Config.promotions = SolidusPromotions.configuration

# Sync legacy order promotions with the new promotion system
SolidusPromotions.config.sync_order_promotions = true
```

--------------------------------

### Automated release with solidus_dev_support

Source: https://github.com/solidusio/solidus/wiki/How-to-release-extensions

Use `solidus_dev_support` for automated version bumping, changelog generation, committing, tagging, and releasing.

```bash
export new_version="1.6.0"
bundle exec gem bump -v $new_version --no-commit
bin/rake changelog # A $CHANGELOG_GITHUB_TOKEN is required, generate one via https://github.com/settings/tokens
git add CHANGELOG.md lib/**/version.rb
git commit -m "Release v$new_version"
git tag -m "Release v$new_version" v$new_version
git push --follow-tags # <remote>
bundle exec gem release
```

--------------------------------

### Load Solidus and Promotions Factories for Development

Source: https://github.com/solidusio/solidus/blob/main/promotions/README.md

Load Solidus core factories along with the extension's factories for testing and development purposes.

```ruby
SolidusDevSupport::TestingSupport::Factories.load_for(SolidusPromotions::Engine)
```

--------------------------------

### Create Sandbox with Specific Database

Source: https://github.com/solidusio/solidus/blob/main/README.md

Create a sandbox application configured to use a specific database (PostgreSQL or MySQL/MariaDB). Set the DB environment variable before running the sandbox command.

```bash
# PostgreSQL
export DB=postgresql
bin/sandbox
```

```bash
# MySQL or MariaDB (mysql2 adapter)
export DB=mysql
bin/sandbox
```

--------------------------------

### Migrate Existing Promotions

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

Run the provided Rails task to create equivalents of legacy promotion configurations within the new SolidusPromotions system.

```sh
bundle exec rails solidus_promotions:migrate_existing_promotions
```

--------------------------------

### Register Promotion Rule Initializer

Source: https://github.com/solidusio/solidus/blob/main/legacy_promotions/README.md

This Ruby code snippet adds the custom payment promotion rule to Solidus's list of available promotion rules in an initializer file.

```ruby
# ...
Rails.application.config.spree.promotions.rules << 'AmazingStore::Promotion::Rules::Payment'
```

--------------------------------

### Disable Order Recalculation

Source: https://github.com/solidusio/solidus/blob/main/promotions/README.md

Optionally disable automatic promotion recalculation for completed orders. This can be useful if promotions are managed carefully with start and end dates, reducing the need for constant recalculation.

```ruby
SolidusPromotions.configure do |config|
  config.recalculate_complete_orders = false
end
```

--------------------------------

### Run All Tests with MySQL/MariaDB

Source: https://github.com/solidusio/solidus/blob/main/README.md

Execute all test specs for Solidus using the `bin/build` script, overriding the default PostgreSQL database with MySQL or MariaDB. Set the DB environment variable accordingly.

```bash
env DB=mysql bin/build
```

--------------------------------

### Dispatch Prepare Release Workflow via GitHub CLI

Source: https://github.com/solidusio/solidus/wiki/Release-pipeline-automation

Use the GitHub CLI to manually trigger the 'prepare_release.yml' workflow. This is useful for automating release preparation tasks from the command line.

```bash
gh workflow run prepare_release.yml
```

```bash
gh workflow run prepare_release.yml -F last_minor=true
```

```bash
gh workflow run prepare_release.yml --ref v3.2
```

--------------------------------

### Filter Products by Name Containing 'Watch'

Source: https://github.com/solidusio/solidus/blob/main/api/openapi/pagination-and-filtering.md

Use the `q` parameter with Ransack matchers like `name_cont` to filter collections. This example retrieves products whose titles contain 'Watch'.

```http
GET /products?q[name_cont]=Watch
```

--------------------------------

### Configure Promotion Lanes

Source: https://github.com/solidusio/solidus/blob/main/promotions/README.md

Customize the order of promotion application by defining custom lanes and their priorities. This is done via the SolidusPromotions initializer.

```ruby
SolidusPromotions.configure do |config|
  config.preferred_lanes = {
    pre: 0,
    default: 1,
    grogu: 2,
    post: 3
  }
end
```

--------------------------------

### Prepare Release Branch and Tag

Source: https://github.com/solidusio/solidus/wiki/[Legacy]-manual-Solidus-release-instructions

After merging the release PR, pull the latest changes, create a new branch for the release, tag it, and push the tag to the upstream repository.

```shell
git pull upstream master
git checkout -b v2.9

# Point the Solidus Installer to the right Starter Frontend version (as done in [#4898](https://github.com/solidusio/solidus/pull/4898)).
# and create a commit 

git tag v2.9
git push --follow-tags --set-upstream upstream v2.9
```

--------------------------------

### StimulusJS Controller Separating State from DOM

Source: https://github.com/solidusio/solidus/blob/main/admin/docs/stimulusjs.md

A StimulusJS controller example that separates application state from DOM manipulation using a `render()` method. It manages a 'details' target and toggles its visibility based on an internal 'open' state.

```javascript
import { Controller } from "stimulus"

export default class extends Controller {
  static targets = [ "details" ]

  connect() {
    this.render()
  }

  show() {
    this.open = true
  }

  render() {
    this.detailsTarget.hidden = !this.open
  }
}
```

--------------------------------

### Human-Friendly Description for Promotion Action

Source: https://github.com/solidusio/solidus/blob/main/legacy_promotions/README.md

Provides a human-readable description for the custom promotion action, which will be displayed in the Solidus admin interface. This helps users understand the action's purpose.

```yaml
en:
  # ...
  activerecord:
    attributes:
      amazing_store/promotion/actions/half_shipping:
        description: Applies 50% discount in shipping
```

--------------------------------

### Empty ERB View Partial for Promotion Action

Source: https://github.com/solidusio/solidus/blob/main/legacy_promotions/README.md

An empty ERB file is required for Solidus to recognize the promotion action, even if it has no UI preferences. This file serves as a placeholder.

```erb
<!-- Intentionally empty -->
```

--------------------------------

### Blog Post Release Announcement Template

Source: https://github.com/solidusio/solidus/wiki/Templates-for-Release-Messages

A comprehensive template for Solidus release announcements on the blog. Includes front matter, release links, and sections for new features and future plans.

```markdown
---
title: Solidus vX.Y
date: YYYY-MM-DD
tags: Solidus
author: Solidus Core Team
cover_image: /blog/YYYY/MM/DD/solidus-vX.Y/cover.jpg #<- Ask Michela for this!
---

- <a class="button" href="https://github.com/solidusio/solidus/releases/tag/vX.Y.0">3.3.0 on GitHub</a>
- <a class="button button-secondary" href="https://rubygems.org/gems/solidus/versions/X.Y.0">X.Y.0 on RubyGems</a>

We've just released Solidus `vX.Y.0`!

Thanks to all contributors, testers, and users who made this release possible.

This version's support will end in 18 months: YYYY-MM-DD + 18 months.

## What's new?
[What's new in this version]

## What's next?
[What we plan to build in the next version(s)]

If you have any questions or experience issues, you can open a [GitHub discussion](https://guides.solidus.io/upgrading-solidus/vX.Y) or contact us on [Slack](https://solidusio.slack.com/). We're here to help!
```

--------------------------------

### Running the Promotion Migrator

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

Execute the Solidus Promotions migrator using a custom promotion map. This command converts existing promotions based on the defined mappings.

```ruby
require 'solidus_promotions/promotion_migrator'
require 'my_promotion_map'

SolidusPromotions::PromotionMigrator.new(MY_PROMOTION_MAP).call
```

--------------------------------

### Index Action with Search

Source: https://github.com/solidusio/solidus/blob/main/admin/docs/index_pages.md

Implement the index action in a controller to support search functionality by including SolidusAdmin::ControllerHelpers::Search and calling apply_search_to.

```ruby
class SolidusAdmin::UsersController < SolidusAdmin::BaseController
  include SolidusAdmin::ControllerHelpers::Search

  def index
    users = apply_search_to(Spree.user_class.order(id: :desc), param: :q)
    # ...
  end
```

--------------------------------

### Component initializer best practices

Source: https://github.com/solidusio/solidus/blob/main/admin/docs/components.md

Prefer simple Ruby values in initializers and use alternative constructors for complex objects to improve usability and testability.

```ruby
# bad

class SolidusAdmin::UI::OrderStatus::Component < ViewComponent::Base
  def initialize(order:)
    @order = order
  end
end

# good

class SolidusAdmin::UI::OrderStatus::Component < ViewComponent::Base
  def initialize(status:)
    @status = status
  end

  def self.for_order(order)
    new(status: order.status)
  end
end
```

--------------------------------

### Run Solidus Docker Image

Source: https://github.com/solidusio/solidus/blob/main/lib/demo/README.md

Runs a Solidus demo Docker container, mapping port 3000. This command can be used for both locally built and official Dockerhub images.

```shell
docker run --rm -it -p 3000:3000 solidusio/solidus-demo:latest
```

--------------------------------

### Use SolidusSupport::Migration for Migrations

Source: https://github.com/solidusio/solidus/wiki/Testing-extensions-against-multiple-Solidus-versions

Replace ActiveRecord::Migration with SolidusSupport::Migration[version] to support multiple Rails versions.

```ruby
class MyAwesomeMigration < SolidusSupport::Migration[4.2]
  # ...
end
```

--------------------------------

### Enable Turbolinks in Solidus Admin

Source: https://github.com/solidusio/solidus/blob/main/README.md

Adds Turbolinks to the Gemfile and modifies the backend JavaScript file to integrate Turbolinks for faster navigation in the Solidus admin panel. Use with caution as it may affect extensions.

```js
//= require turbolinks
//
// ... current file content
//
//= require spree/backend/turbolinks-integration.js
```

--------------------------------

### Update Coupon Promotion Handler

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

For custom frontends like the Solidus starter frontend, update references from `Spree::PromotionHandler::Coupon` to `Spree::Config.promotions.coupon_code_handler_class`.

```ruby
Spree::Config.promotions.coupon_code_handler_class
```

--------------------------------

### Automate Migration Class Replacement

Source: https://github.com/solidusio/solidus/wiki/Testing-extensions-against-multiple-Solidus-versions

Use sed to automatically replace ActiveRecord::Migration with SolidusSupport::Migration[4.2] in migration files.

```bash
sed -i 's/ActiveRecord::Migration/SolidusSupport::Migration[4.2]/' db/migrate/*.rb
```

--------------------------------

### Build Docker Image with Specific Ruby Version

Source: https://github.com/solidusio/solidus/blob/main/README.md

Builds the Solidus Docker image, allowing customization of the Ruby version used.

```bash
docker-compose build --build-arg RUBY_VERSION=3.0 app
docker-compose up -d
```

--------------------------------

### Manually Build Tailwind CSS

Source: https://github.com/solidusio/solidus/blob/main/admin/docs/tailwindcss.md

Execute this command to manually compile the Tailwind CSS file. This is useful for one-time builds or when automated watching is not needed.

```shell
bin/rails solidus_admin:tailwindcss:build
```

--------------------------------

### Migrate Adjustments and Order Promotions

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

Run these tasks to migrate adjustments and order promotions in the database. Verify the spree_adjustments table for correctness afterward.

```sh
bundle exec rails solidus_promotions:migrate_adjustments:up
bundle exec rails solidus_promotions:migrate_order_promotions:up
```

--------------------------------

### Access SQLite Database with Docker

Source: https://github.com/solidusio/solidus/blob/main/README.md

Connects to the SQLite database within the Dockerized Solidus environment.

```bash
docker-compose exec app sqlite3 /path/to/db
```

--------------------------------

### Run Core Project Tests with PostgreSQL

Source: https://github.com/solidusio/solidus/blob/main/README.md

Execute the RSpec tests for the core Solidus project against a PostgreSQL database. Specify the database using the DB environment variable.

```bash
env DB=postgresql bundle exec rspec
```

--------------------------------

### Add Solidus Promotions to Gemfile

Source: https://github.com/solidusio/solidus/blob/main/promotions/README.md

Include the solidus_promotions gem in your application's Gemfile to add promotion functionality.

```ruby
gem 'solidus_promotions'
```

--------------------------------

### Slack Release Announcement Template

Source: https://github.com/solidusio/solidus/wiki/Templates-for-Release-Messages

Use this template for announcing Solidus releases on Slack. It includes placeholders for version, new features, upgrade instructions, and support channels.

```text
Hello commuinity! 

We're thrilled to announce that Solidus vX.Y is now available! :tada: 

[Add here some content related to what has been introduced in the new version]

If you are upgrading from vX.(Y-1), please check out the upgrade instructions at https://guides.solidus.io/upgrading-solidus/vX.Y. 

If you have any questions or experience issues, please post a message on the [#support](https://solidusio.slack.com/archives/C0JBKDF35) channel or create a [GitHub discussion](https://github.com/solidusio/solidus/discussions/new?category=troubleshooting). We're here to help you out!

Thanks to anyone contributing to the project, we are building together the future of Solidus!
```

--------------------------------

### TravisCI Build Matrix Configuration

Source: https://github.com/solidusio/solidus/wiki/Testing-extensions-against-multiple-Solidus-versions

Configure TravisCI to test against multiple Solidus branches and databases using a build matrix.

```yaml
language: ruby
rvm:
  - 2.3.1
env:
  matrix:
    - SOLIDUS_BRANCH=v1.4 DB=postgres
    - SOLIDUS_BRANCH=v2.0 DB=postgres
    - SOLIDUS_BRANCH=v2.1 DB=postgres
    - SOLIDUS_BRANCH=master DB=postgres
    - SOLIDUS_BRANCH=v1.4 DB=mysql
    - SOLIDUS_BRANCH=v2.0 DB=mysql
    - SOLIDUS_BRANCH=v2.1 DB=mysql
    - SOLIDUS_BRANCH=master DB=mysql
```

--------------------------------

### Access PostgreSQL Database with Docker

Source: https://github.com/solidusio/solidus/blob/main/README.md

Connects to the PostgreSQL database within the Dockerized Solidus environment.

```bash
docker-compose exec app env PGPASSWORD=password psql -U root -h postgres
```

--------------------------------

### Run Core Project Tests

Source: https://github.com/solidusio/solidus/blob/main/README.md

Execute the RSpec tests specifically for the core Solidus project. This command assumes you are in the 'core' directory and uses SQLite by default.

```bash
cd core
bundle exec rspec
```

--------------------------------

### Create MySQL User for Testing

Source: https://github.com/solidusio/solidus/blob/main/README.md

Create a MySQL user with the same name as the current system user and grant all privileges. This command can help resolve MySQL-related errors during testing.

```bash
# Creates a user with the same name as the current user and no restrictions.
mysql --user="root" --execute="CREATE USER '$USER'@'localhost'; GRANT ALL PRIVILEGES ON * . * TO '$USER'@'localhost';"
```

--------------------------------

### Load Payment Promotion Handler Callback

Source: https://github.com/solidusio/solidus/blob/main/legacy_promotions/README.md

This code prepends behavior to the Spree::Order class to activate the custom payment promotion handler after the order transitions from the :payment state.

```ruby
# frozen_string_literal: true

module AmazingStore
  module LoadPaymentPromotionHandler
    def self.prepended(base)
      base.state_machine.after_transition(from: :payment) do |order|
        AmazingStore::PromotionHandler::Payment.new(order).activate
      end
    end

    ::Spree::Order.prepend(self)
  end
end
```

--------------------------------

### Push Solidus Docker Image

Source: https://github.com/solidusio/solidus/blob/main/lib/demo/README.md

Pushes a built Solidus Docker image to the official Solidus Dockerhub account. Use this command after building your image locally.

```shell
docker push solidusio/solidus-demo:latest
```

--------------------------------

### Replace a Component

Source: https://github.com/solidusio/solidus/blob/main/admin/docs/customizing_components.md

Replace an entire component by creating a new component with a matching path in your application. Ensure compatibility with the original component's `#initialize` method if other components depend on it.

```ruby
class MyAdmin::MenuItem::Component < SolidusAdmin::BaseComponent
  # Here goes your code
end
```

--------------------------------

### Updating Gemfile for Solidus Suite

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

Replace the `solidus` gem with individual Solidus component gems in the Gemfile. This is done after successfully migrating to `solidus_promotions` and removing `solidus_legacy_promotions`.

```diff
# Gemfile
- gem 'solidus', '~> 4,4'
+ gem 'solidus_core', '~> 4.4'
+ gem 'solidus_api', '~> 4.4'
+ gem 'solidus_backend', '~> 4.4'
+ gem 'solidus_admin', '~> 4.4'
+ gem 'solidus_promotions', '~> 4.4'
```

--------------------------------

### Generate a new component

Source: https://github.com/solidusio/solidus/blob/main/admin/docs/components.md

Use the `solidus_admin:component` generator with `bin/rails` to create new component files.

```shell
bin/rails admin g solidus_admin:component foo
     create  app/components/solidus_admin/foo/component.rb
     create  app/components/solidus_admin/foo/component.html.erb
     create  app/components/solidus_admin/foo/component.yml
     create  app/components/solidus_admin/foo/component.js
```

--------------------------------

### Half Shipping Promotion Action

Source: https://github.com/solidusio/solidus/blob/main/legacy_promotions/README.md

Implements a promotion action to apply a 50% discount to order shipments. It handles applying the discount and removing it if the promotion becomes ineligible. Ensure the `perform` method returns true if any adjustments were made.

```ruby
# frozen_string_literal: true

module AmazingStore
  module Promotion
    module Actions
      class HalfShipping < ::Spree::PromotionAction
        # The `perform` method is called when an action is applied to an order or line
        # item. The payload contains a lot of useful context:
        # https://github.com/solidusio/solidus/blob/64b6b6eaf902337983c487cf10dfada8dbfc5160/core/app/models/spree/promotion.rb#L129
        def perform(payload = {})
          order = payload[:order]
          promotion_code = payload[:promotion_code]

          results = order.shipments.map do |shipment|
            # If the shipment has already been discounted by this promotion action,
            # we skip it.
            next false if shipment.adjustments.where(source: self).exists?

            # If not, we create an adjustment to apply a 50% discount on the shipment.
            shipment.adjustments.create!(
              order: shipment.order,
              amount: compute_amount(shipment),
              source: self,
              promotion_code: promotion_code,
              label: promotion.name,
            )

            # We return true here to mark that the shipment has been discounted.
            true
          end

          # `perform` needs to return true if any adjustments have been applied by
          # the promotion action. Otherwise, it should return false.
          results.any? { |result| result == true }
        end

        def compute_amount(shipment)
          shipment.cost * -0.5
        end

        # The `remove_from` method should undo any actions done by `perform`. It is
        # used when an order becomes ineligible for a given promotion and the promotion
        # needs to be removed.
        def remove_from(order)
          order.shipments.each do |shipment|
            shipment.adjustments.each do |adjustment|
              if adjustment.source == self
                # Here, we simply remove any adjustments on the order's shipments
                # created by this promotion action.
                shipment.adjustments.destroy!(adjustment)
              end
            end
          end
        end
      end
    end
  end
end
```

--------------------------------

### Importing a Custom Theme

Source: https://github.com/solidusio/solidus/wiki/Customizing-the-Admin-(backend)-Panel

Add this to your `_variables_override.scss` file to import a pre-defined color theme.

```scss
@import 'spree/backend/themes/blue_steel/globals/_variables_override';
```

--------------------------------

### Creating a Promotion Conversion Map with a Callable

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

Use a callable (lambda) within the promotion map to dynamically create new condition instances from old promotion rules. This allows for custom initialization of the new condition.

```ruby
require 'solidus_promotions/promotion_map'

MY_PROMOTION_MAP = SolidusPromotions::PROMOTION_MAP.deep_merge(
  rules: {
    MyRule => ->(old_promotion_rule) {
      MyCondition.new(preferred_quantity: old_promotion_rule.preferred_count)
    }
  }
)
```

--------------------------------

### Creating a Promotion Conversion Map with a New Condition Class

Source: https://github.com/solidusio/solidus/blob/main/promotions/MIGRATING.md

Define a promotion map to associate old promotion rules with new condition classes. This map is used by the migrator to perform the conversion.

```ruby
require 'solidus_promotions/promotion_map'

MY_PROMOTION_MAP = SolidusPromotions::PROMOTION_MAP.deep_merge(
  rules: {
    MyRule => MyCondition
  }
)
```

--------------------------------

### Clone Solidus Repository

Source: https://github.com/solidusio/solidus/blob/main/README.md

Clones the Solidus Git repository locally for development purposes.

```bash
git clone git://github.com/solidusio/solidus.git
cd solidus
```

--------------------------------

### Registering Custom Promotion Action

Source: https://github.com/solidusio/solidus/blob/main/legacy_promotions/README.md

Registers the custom promotion action class with Solidus by adding its string name to the `spree.promotions.actions` configuration. This makes the action available for use in the Solidus admin interface.

```ruby
# ...
Rails.application.config.spree.promotions.actions << 'AmazingStore::Promotion::Actions::HalfShipping'
```

--------------------------------

### Pin Bourbon Version

Source: https://github.com/solidusio/solidus/wiki/FAQ

If you encounter 'undefined mixin \'display\'' errors, explicitly set your application's Bourbon gem version to less than 5.0.0 in your Gemfile. This resolves compatibility issues with older Solidus versions.

```ruby
gem 'bourbon', '< 5.0.0'
```

--------------------------------

### Gemfile for Dynamic Solidus Version

Source: https://github.com/solidusio/solidus/wiki/Testing-extensions-against-multiple-Solidus-versions

Dynamically set the Solidus version in the Gemfile based on the SOLIDUS_BRANCH environment variable for testing.

```ruby
source "https://rubygems.org"

branch = ENV.fetch('SOLIDUS_BRANCH', 'master')
gem "solidus", github: "solidusio/solidus", branch: branch

if branch == 'master' || branch >= "v2.0"
  gem "rails-controller-testing", group: :test
else
  gem "rails", '~> 4.2.7' # workaround for bundler resolution issue
  gem "rails_test_params_backport", group: :test
end

gem 'pg'
gem 'mysql2'

gemspec
```

--------------------------------

### Configure .gem_release.yml for gem-release

Source: https://github.com/solidusio/solidus/wiki/How-to-release-extensions

Manually configure the .gem_release.yml file for the `gem-release` gem, specifying the version file and commit message format.

```yaml
# .gem_release.yml

bump:
  recurse: false
  file: 'lib/solidus_stripe/version.rb'
  message: Bump Solidus Stripe to %{version}
  tag: false
```

--------------------------------

### Require Solidus Support in Gem File

Source: https://github.com/solidusio/solidus/wiki/Testing-extensions-against-multiple-Solidus-versions

Ensure solidus_support is required in the extension's main Ruby file.

```ruby
require 'solidus_core'
require 'solidus_support'
```

--------------------------------

### Create Sandbox with Specific Rails Version

Source: https://github.com/solidusio/solidus/blob/main/README.md

Generate a sandbox application using a specific Rails version, controlled by the RAILS_VERSION environment variable. This is useful for compatibility testing with older Ruby versions.

```bash
export RAILS_VERSION='~> 5.2.0'
bin/setup
bin/sandbox
```

--------------------------------

### Generate a New Solidus Admin Component

Source: https://github.com/solidusio/solidus/blob/main/admin/README.md

Use the `solidus_admin:component` generator to create new components for Solidus Admin. The namespace `solidus_admin/` is added by default. Running this within the admin folder generates the component in the library instead of the sandbox application.

```bash
# the `solidus_admin/` namespace is added by default
bin/rails admin g solidus_admin:component foo
      create  app/components/solidus_admin/foo/component.rb
      create  app/components/solidus_admin/foo/component.html.erb
      create  app/components/solidus_admin/foo/component.yml
      create  app/components/solidus_admin/foo/component.js
      create  spec/components/solidus_admin/foo/component_spec.rb
```

--------------------------------

### Use Bleeding Edge Solidus Version

Source: https://github.com/solidusio/solidus/blob/main/README.md

Adds the Solidus gem from the GitHub repository for the latest development version. Note: The master branch may not be stable.

```ruby
gem 'solidus', github: 'solidusio/solidus'
```

--------------------------------

### Configure Paperclip for S3 Storage

Source: https://github.com/solidusio/solidus/wiki/Storing-images-on-S3-and-CDN's

Configure Paperclip's default options to use S3 storage via fog-aws. This involves setting up storage, fog credentials, and the fog directory.

```ruby
# config/initializers/paperclip.rb

if Rails.application.secrets.aws_access_key_id
  Paperclip::Attachment.default_options.merge!(
    storage: :fog,
    fog_credentials: {
      provider: 'AWS',
      aws_access_key_id: Rails.application.secrets.aws_access_key_id,
      aws_secret_access_key: Rails.application.secrets.aws_secret_access_key,
      region: Rails.application.secrets.s3_region_name,
    },
    fog_directory: Rails.application.secrets.s3_bucket_name
  )

  Spree::Image.attachment_definitions[:attachment].delete(:url)
  Spree::Image.attachment_definitions[:attachment].delete(:path)
end
```

--------------------------------

### Run RSpec Tests with Docker (SQLite)

Source: https://github.com/solidusio/solidus/blob/main/README.md

Executes RSpec tests within the Dockerized Solidus environment using the default SQLite database.

```bash
docker-compose exec app bin/rspec
```

--------------------------------

### Index Action with Pagination

Source: https://github.com/solidusio/solidus/blob/main/admin/docs/index_pages.md

Add pagination support to the index action by calling set_page_and_extract_portion_from to paginate the collection.

```ruby
def index
  users = apply_search_to(Spree.user_class.order(id: :desc), param: :q)
  set_page_and_extract_portion_from(users)
  # ...
end
```

--------------------------------

### Locale for Promotion Rule Description

Source: https://github.com/solidusio/solidus/blob/main/legacy_promotions/README.md

This YAML snippet defines a user-friendly description for the payment promotion rule in the application's English locale file.

```yaml
en:
  # ...
  activerecord:
    attributes:
      amazing_store/promotion/rules/payment:
        description: Must use the specified payment method
```

--------------------------------

### Access MySQL Database

Source: https://github.com/solidusio/solidus/blob/main/README.md

Connect to the MySQL database within the Docker Compose environment. Ensure the application container is running.

```bash
docker-compose exec app mysql -u root -h mysql -ppassword
```