@spree/docs 0.1.0

package/dist/developer/contributing/developing-spree.md

@@ -0,0 +1,339 @@
+---
+title: Developing Spree
+description: >-
+  This guide covers all the necessary steps to contributing to Spree source
+  code. We're happy you're here!
+---
+
+## Cloning the repository
+
+Spree is a big monorepo. For a faster clone, use a **partial clone** which downloads file contents on demand while keeping full commit history for `git log` and `git blame`:
+
+```bash
+git clone --filter=blob:none https://github.com/spree/spree.git
+```
+
+## Spree codebase
+
+Spree is a monorepo with three main areas:
+
+- **`spree/`** — Ruby gems (core, api, admin, emails) distributed as separate packages via RubyGems
+- **`packages/`** — TypeScript packages (SDK, Next.js helpers)
+- **`server/`** — A Rails application cloned from [spree-starter](https://github.com/spree/spree-starter) that mounts the Spree gems (not checked in — run `pnpm server:setup` to create it)
+
+## Backend Development (Ruby)
+
+### Engines overview
+
+The Spree [Rails engines](https://guides.rubyonrails.org/engines.html) live inside `spree/` and are distributed as separate gems (Ruby packages installed via Bundler):
+
+| Engine | Gem | Description |
+|---|---|---|
+| `core` | `spree_core` | Models, services, business logic |
+| `api` | `spree_api` | REST APIs |
+| `admin` | `spree_admin` | Admin dashboard |
+| `emails` | `spree_emails` | Transactional emails |
+
+### Spree namespace
+
+All Spree models, controllers and other Ruby classes are namespaced by the `Spree` keyword, eg. `Spree::Product`. This means that those files are also located in `spree` sub-directories eg. [app/models/spree/product.rb](https://github.com/spree/spree/blob/main/spree/core/app/models/spree/product.rb).
+
+### Setup
+
+The server app is not checked into the monorepo. It's cloned from [spree-starter](https://github.com/spree/spree-starter) on first setup, with `SPREE_PATH=..` automatically configured so it uses your local Spree gems.
+
+**Step 1: Start infrastructure**
+
+```bash
+docker compose up -d     # starts Postgres, Redis, Mailpit
+```
+
+Or install PostgreSQL and Redis locally if you prefer.
+
+**Step 2: Clone the server app**
+
+```bash
+pnpm server:setup
+```
+
+This clones [spree-starter](https://github.com/spree/spree-starter) into `server/` and sets `SPREE_PATH=..` in `server/.env` so it uses your local Spree gems.
+
+**Step 3: Configure and run**
+
+```bash
+cd server
+# Edit .env if needed (e.g. DATABASE_USERNAME, DATABASE_HOST, DATABASE_PORT)
+bin/setup        # installs Ruby (via mise), system packages, gems, prepares database
+bin/dev          # starts Rails + Sidekiq + CSS watchers via overmind
+```
+
+Use `bin/setup --reset` to drop and recreate the database.
+
+The app runs at [http://localhost:3000](http://localhost:3000). Admin Panel is at [http://localhost:3000/admin](http://localhost:3000/admin).
+
+**Emails in local dev:** When using `docker compose up -d`, Mailpit is included automatically. All outgoing emails are caught and viewable at [http://localhost:8025](http://localhost:8025).
+
+### Running engine tests
+
+Each engine has its own test suite. First install the shared dependencies at the `spree/` level, then navigate into the specific engine to set up and run its tests:
+
+```bash
+# 1. Install shared dependencies
+cd spree
+bundle install
+
+# 2. Set up and run tests for a specific engine (e.g. core)
+cd core
+bundle install
+bundle exec rake test_app
+bundle exec rspec
+```
+
+Replace `core` with `api`, `admin`, or `emails` to test other engines.
+
+By default engine tests run against SQLite3. To run against PostgreSQL, set the `DB` environment variable:
+
+```bash
+DB=postgres DB_USERNAME=postgres DB_PASSWORD=password DB_HOST=localhost bundle exec rake test_app
+```
+
+Run a single spec file:
+
+```bash
+cd spree/core
+bundle exec rspec spec/models/spree/state_spec.rb
+```
+
+Run a specific test by line number:
+
+```bash
+cd spree/core
+bundle exec rspec spec/models/spree/state_spec.rb:7
+```
+
+### Running tests in parallel
+
+For faster test runs on multi-core machines, you can use the `parallel_tests` gem to distribute spec files across multiple CPU cores.
+
+After setting up the test app, create databases for parallel workers:
+
+```bash
+cd spree/core
+bundle exec rake parallel_setup
+```
+
+Then run specs in parallel:
+
+```bash
+bundle exec parallel_rspec spec
+```
+
+You can also specify the number of workers:
+
+```bash
+bundle exec rake "parallel_setup[4]"
+bundle exec parallel_rspec -n 4 spec
+```
+
+After schema changes, re-run `bundle exec rake parallel_setup` to update the worker databases.
+
+### Integration tests (Admin Panel)
+
+The Admin Panel uses feature specs that run in a real browser via chromedriver. You only need this if you're working on admin UI changes.
+
+Install chromedriver on macOS:
+
+```bash
+brew install chromedriver
+```
+
+### Performance in development mode
+
+You may notice that your Spree store runs slower in development environment. This is caused by disabled caching and automatic reloading of code after each change.
+
+Caching is disabled by default. To turn on caching please run:
+
+```bash
+cd server && bin/rails dev:cache
+```
+
+You will need to restart rails server after this change.
+
+## TypeScript Development
+
+### Setup
+
+TypeScript developers don't need Ruby installed. Docker Compose from the repository root starts the backend using a prebuilt image:
+
+```bash
+docker compose up -d
+```
+
+This boots PostgreSQL, Redis, Mailpit, and the Spree backend automatically (no `pnpm server:setup` needed). The API is available at `http://localhost:3000`. All outgoing emails are caught by Mailpit and viewable at `http://localhost:8025`.
+
+Then install dependencies and start all packages in watch mode:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+### Packages
+
+| Package | Path | Description |
+|---|---|---|
+| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Storefront API |
+| `@spree/next` | `packages/next` | Next.js integration (server actions, caching, cookie-based auth) |
+
+### Common commands
+
+Run from the repository root — [Turborepo](https://turbo.build/) orchestrates tasks across all packages:
+
+| Command | Description |
+|---|---|
+| `pnpm dev` | Start Docker backend + watch mode for all packages |
+| `pnpm build` | Build all packages (SDK first, then Next.js) |
+| `pnpm test` | Run tests in all packages |
+| `pnpm lint` | Lint all packages |
+| `pnpm typecheck` | Type-check all packages |
+| `pnpm clean` | Remove build artifacts |
+
+### Package-specific commands
+
+You can also run commands in a single package:
+
+```bash
+pnpm --filter @spree/sdk test:watch
+pnpm --filter @spree/sdk console
+pnpm --filter @spree/sdk generate:zod
+```
+
+Tests use [Vitest](https://vitest.dev/) with [MSW](https://mswjs.io/) for API mocking at the network level.
+
+### Type generation
+
+TypeScript types in `packages/sdk/src/types/generated/` are auto-generated from the Rails API serializers using [typelizer](https://github.com/skryukov/typelizer). To regenerate after changing serializers:
+
+```bash
+cd spree/api
+mise install --yes # to install Ruby if you don't have it already
+bundle install # to install dependencies
+bundle exec rake typelizer:generate
+```
+
+After regenerating types, update the Zod schemas:
+
+```bash
+pnpm --filter @spree/sdk generate:zod
+```
+
+### Releasing packages
+
+Packages use [Changesets](https://github.com/changesets/changesets) for version management:
+
+```bash
+pnpm changeset
+```
+
+This creates a changeset file describing your changes. Commit it with your PR. When merged to `main`, a GitHub Action creates a "Version Packages" PR that bumps the version and publishes to npm.
+
+## Code Style
+
+Consistent code style is enforced via automated linters. Please make sure your changes pass linting before submitting a PR.
+
+**Ruby:** We use [RuboCop](https://rubocop.org/) for Ruby code. Configuration lives in `server/.rubocop.yml`. Run it from the `server/` directory:
+
+```bash
+cd server
+bundle exec rubocop
+```
+
+To auto-fix correctable offenses:
+
+```bash
+bundle exec rubocop -a
+```
+
+**TypeScript:** We use [Biome](https://biomejs.dev/) for linting and formatting TypeScript code. Run it from the repository root:
+
+```bash
+pnpm lint
+```
+
+## Making Changes
+
+### Branch naming
+
+Create a new branch for your changes. Do not push changes to the main branch. Branch names should be human-readable and informative:
+
+- Bug fixes: `fix/order-recalculation-total-bug`
+- Features: `feature/my-new-amazing-feature`
+
+### Commit messages
+
+Keep your commit history meaningful and clear. Each commit should represent a logical unit of work. [This guide](https://about.gitlab.com/blog/2018/06/07/keeping-git-commit-history-clean/) covers this well.
+
+A few tips:
+
+- Write commit messages in the imperative mood (e.g. "Add feature" not "Added feature")
+- Keep the first line under 72 characters
+- If your change references a GitHub issue, include `Fixes #<number>` in the commit message or PR description to auto-close it on merge
+
+### Using AI tools for development
+
+Spree comes with an [AGENTS.md](https://github.com/spree/spree/blob/main/AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.
+
+We also have an MCP server built on top of our Documentation website to help you with your development.
+
+Add this URL to your AI tools:
+
+```
+https://spreecommerce.org/docs/mcp
+```
+
+In Claude Code you need to go to [Connectors](https://claude.ai/settings/connectors) settings and add the URL.
+
+## Submitting Changes
+
+We use [GitHub Actions](https://github.com/spree/spree/actions) to run CI.
+
+1. Push your changes to a topic branch in your fork of the repository.
+
+    ```bash
+    git push origin fix/order-recalculation-total-bug
+    ```
+
+2. [Create a Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) against the `main` branch.
+
+3. Wait for CI to pass.
+
+4. Wait for Spree Core team code review. We aim to review and leave feedback as soon as possible.
+
+### Pull request guidelines
+
+To help us review your PR quickly:
+
+- **Keep PRs focused.** One feature or fix per PR. Smaller PRs are easier to review and merge.
+- **Describe your changes.** Explain what you changed and why. Include screenshots for UI changes.
+- **Add tests.** All new features and bug fixes should include appropriate test coverage.
+- **Update documentation.** If your change affects user-facing behavior, update the relevant docs.
+- **Include a changeset** (TypeScript packages only). Run `pnpm changeset` if your change affects `@spree/sdk` or `@spree/next`.
+- **Ensure CI passes.** PRs with failing CI will not be reviewed.
+
+## Reporting Bugs
+
+We use [GitHub Issues](https://github.com/spree/spree/issues) to track bugs. Before filing a new issue, please search existing issues to avoid duplicates.
+
+When reporting a bug, please include:
+
+- **Spree version** you're using
+- **Steps to reproduce** the problem
+- **Expected behavior** vs **actual behavior**
+- **Relevant logs or stack traces** (formatted with triple backticks)
+- **Your environment** (Ruby version, database, OS)
+
+Issues that are open for 14 days without actionable information or activity will be marked as stale and then closed. They can be re-opened if the requested information is provided.
+
+## That's a wrap!
+
+Thank you for participating in Open Source and improving Spree - you're awesome!

package/dist/developer/contributing/quickstart.md

@@ -0,0 +1,32 @@
+---
+title: Quickstart
+description: How to get started contributing to Spree
+---
+
+Spree is an open, community-powered project that anyone can contribute to. There are several ways you can help us improve Spree:
+
+* fixing a bug or creating a new feature
+* creating a Spree extension
+* upgrading old extensions to recent Spree versions
+* helping others on Spree slack
+* submitting an issue describing a bug or a feature request
+
+## Fixing a bug or creating a new feature
+
+Before diving into the Spree codebase we recommend you spend some time reviewing the [Core Concepts section](/core-concepts) which will help you understand how Spree works under the hood.
+
+After you're done with that please follow to [Developing Spree guide](developing-spree)
+
+To find issues you can tackle on we recommend visiting [Spree Contribute page](https://github.com/spree/spree/contribute) which lists issues tagged with [Good First Issue label](https://github.com/spree/spree/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22). Those bugs or features are great starting points into Open Source development.
+
+## Creating a Spree extension
+
+Extensions provide additional features and integrations for your Spree store. You can create your own and share with the rest of the community. Before doing so please check our [Extension directory](/developer/customization/extensions) if your desired extension does not exist already. If not [follow Extensions tutorial](../contributing/extensions_tutorial) to learn how to create one.
+
+## Helping others on Spree slack
+
+Last but not least, you're invited to [join our slack](http://slack.spreecommerce.org) to help and receive guidance from fellow Spree developers including Spree Core Team.
+
+## Submitting issues
+
+You can [submit an issue](https://github.com/spree/spree/issues/new/choose) on our [Github Issues tracker](https://github.com/spree/spree/issues)

package/dist/developer/contributing/updating-extensions.md

@@ -0,0 +1,67 @@
+---
+title: Updating Extensions
+description: How to upgrade your Spree extension to work with Spree 4
+version: v4
+---
+
+## Zeitwerk compatibility
+
+Zeitwerk is the [new default code autoloader in Rails 6](https://weblog.rubyonrails.org/2019/2/22/zeitwerk-integration-in-rails-6-beta-2/).
+
+This doesn't work well with the old approach to decorators files that name ends with decorator.rb, eg. `app/models/spree/order_decorator.rb` using [class_eval](https://www.jimmycuadra.com/posts/metaprogramming-ruby-class-eval-and-instance-eval/).
+
+To fix this we need to convert all `class_eval` decorators to modules and use [Module.prepend](https://medium.com/@leo_hetsch/ruby-modules-include-vs-prepend-vs-extend-f09837a5b073). Also we need to name them properly according to [Zeitwerk naming rules](https://github.com/fxn/zeitwerk#file-structure)
+
+Example of an old decorator:
+
+```ruby app/models/spree/order_decorator.rb
+Spree::Order.class_eval do
+  has_many :new_custom_model
+
+  def some_method
+     # ...
+  end
+end
+```
+
+the same decorator in the new notation:
+
+```ruby app/models/your_extension_name/order_decorator.rb
+module YourExtensionName::OrderDecorator
+  def self.prepended(base)
+    base.has_many :new_custom_model
+  end
+
+  def some_method
+    # ...
+  end
+end
+
+Spree::Order.prepend(YourExtensionName::OrderDecorator)
+```
+
+## Fixing Deface Overrides
+
+Please remember to prepare versioned overrides for both Spree 3.x and 4.x, eg. [https://github.com/spree-contrib/spree_static_content/commit/e4b9e4900024235158d0ec1a48a100b4732348ef](https://github.com/spree-contrib/spree_static_content/commit/e4b9e4900024235158d0ec1a48a100b4732348ef)
+
+Spree 4 uses Bootstrap 4 and many partials and HTML structure changed compared to Spree 3.x.
+
+Also - **remember to add deface gem to gemspec** as deface itself was removed as a dependency of Spree. eg. [https://github.com/spree/spree_auth_devise/commit/d729689ca87d8586e541ffcc865ef1e0a5a79fe4](https://github.com/spree/spree_auth_devise/commit/d729689ca87d8586e541ffcc865ef1e0a5a79fe4)
+
+## Migrate to Spree Dev Tools
+
+Replace all development dependencies with:
+
+```ruby
+s.add_development_dependency 'spree_dev_tools'
+```
+
+Replace `spec_helper.rb` contents with:
+
+[https://github.com/spree/spree/blob/777a284b4c70e69d32a05ffa61bbe3905d8f1297/cmd/lib/spree_cmd/templates/extension/spec/spec_helper.rb](https://github.com/spree/spree/blob/777a284b4c70e69d32a05ffa61bbe3905d8f1297/cmd/lib/spree_cmd/templates/extension/spec/spec_helper.rb)
+
+Example migrations:
+
+* [https://github.com/spree/spree_gateway/pull/357](https://github.com/spree/spree_gateway/pull/357)
+* [https://github.com/spree-contrib/spree-product-assembly/pull/200](https://github.com/spree-contrib/spree-product-assembly/pull/200)
+* [https://github.com/spree/spree_auth_devise/pull/487](https://github.com/spree/spree_auth_devise/pull/487)