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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
improve CONTRIBUTING guide (#13959)
Damian Legawiec3002c04f3095
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex be82f19425..054e941561 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -48,7 +48,7 @@ git clone --filter=blob:none https://github.com/spree/spree.gitSpree 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)+- **`packages/`** — TypeScript packages (SDKs, CLI, project scaffolding, docs)- **`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)@@ -210,7 +210,12 @@ pnpm dev| Package | Path | Description ||---|---|---|-| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Storefront API |+| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Store API |+| `@spree/cli` | `packages/cli` | CLI for managing Spree Commerce projects |+| `create-spree-app` | `packages/create-spree-app` | Project scaffolding (`npm create spree-app`) |+| `@spree/docs` | `packages/docs` | Developer documentation for AI agents and local reference |++Internal packages (`@spree/admin-sdk`, `@spree/sdk-core`) are also part of the workspace but are not published to npm.### Common commands@@ -219,7 +224,7 @@ Run from the repository root — [Turborepo](https://turbo.build/) orchestrates| Command | Description ||---|---|| `pnpm dev` | Start Docker backend + watch mode for all packages |-| `pnpm build` | Build all packages (SDK first, then Next.js) |+| `pnpm build` | Build all packages (Turbo resolves dependency order) || `pnpm test` | Run tests in all packages || `pnpm lint` | Lint all packages || `pnpm typecheck` | Type-check all packages |@@ -256,9 +261,10 @@ pnpm --filter @spree/sdk generate:zod### Releasing packages-Packages use [Changesets](https://github.com/changesets/changesets) for version management:+Published packages use [Changesets](https://github.com/changesets/changesets) for version management. Each package owns its own `.changeset/` folder, so changesets must be created from inside the package directory:```bash+cd packages/sdk # or packages/cli, packages/create-spree-apppnpm changeset```@@ -268,7 +274,7 @@ This creates a changeset file describing your changes. Commit it with your PR. WConsistent 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:+**Ruby:** We use [RuboCop](https://rubocop.org/) for Ruby code. The configuration lives in `server/.rubocop.yml` and is shipped with [spree-starter](https://github.com/spree/spree-starter), so it's only available after running `pnpm server:setup`. Run it from the `server/` directory:```bashcd server@@ -330,7 +336,7 @@ To help us review your PR quickly:- **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`.+- **Include a changeset** if your change affects a published TypeScript package (`@spree/sdk`, `@spree/cli`, or `create-spree-app`). Run `pnpm changeset` from inside that package's directory — each package owns its own `.changeset/` folder.- **Ensure CI passes.** PRs with failing CI will not be reviewed.## Reporting Bugs@@ -351,7 +357,7 @@ Issues that are open for 14 days without actionable information or activity will## Using AI Tools for Development-Spree comes with an [AGENTS.md](../../../AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.+Spree comes with an [AGENTS.md](../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.diff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdxindex 98a9befed1..8155cd7d28 100644--- a/docs/developer/contributing/developing-spree.mdx+++ b/docs/developer/contributing/developing-spree.mdx@@ -18,7 +18,7 @@ git clone --filter=blob:none https://github.com/spree/spree.gitSpree 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)+- **`packages/`** — TypeScript packages (SDKs, CLI, project scaffolding, docs)- **`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)@@ -180,7 +180,12 @@ pnpm dev| Package | Path | Description ||---|---|---|-| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Storefront API |+| `@spree/sdk` | `packages/sdk` | TypeScript SDK for the Spree Store API |+| `@spree/cli` | `packages/cli` | CLI for managing Spree Commerce projects |+| `create-spree-app` | `packages/create-spree-app` | Project scaffolding (`npm create spree-app`) |+| `@spree/docs` | `packages/docs` | Developer documentation for AI agents and local reference |++Internal packages (`@spree/admin-sdk`, `@spree/sdk-core`) are also part of the workspace but are not published to npm.### Common commands@@ -189,7 +194,7 @@ Run from the repository root — [Turborepo](https://turbo.build/) orchestrates| Command | Description ||---|---|| `pnpm dev` | Start Docker backend + watch mode for all packages |-| `pnpm build` | Build all packages (SDK first, then Next.js) |+| `pnpm build` | Build all packages (Turbo resolves dependency order) || `pnpm test` | Run tests in all packages || `pnpm lint` | Lint all packages || `pnpm typecheck` | Type-check all packages |@@ -226,9 +231,10 @@ pnpm --filter @spree/sdk generate:zod### Releasing packages-Packages use [Changesets](https://github.com/changesets/changesets) for version management:+Published packages use [Changesets](https://github.com/changesets/changesets) for version management. Each package owns its own `.changeset/` folder, so changesets must be created from inside the package directory:```bash+cd packages/sdk # or packages/cli, packages/create-spree-apppnpm changeset```@@ -238,7 +244,7 @@ This creates a changeset file describing your changes. Commit it with your PR. WConsistent 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:+**Ruby:** We use [RuboCop](https://rubocop.org/) for Ruby code. The configuration lives in `server/.rubocop.yml` and is shipped with [spree-starter](https://github.com/spree/spree-starter), so it's only available after running `pnpm server:setup`. Run it from the `server/` directory:```bashcd server@@ -276,20 +282,6 @@ A few tips:- 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 ChangesWe use [GitHub Actions](https://github.com/spree/spree/actions) to run CI.@@ -314,7 +306,7 @@ To help us review your PR quickly:- **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`.+- **Include a changeset** if your change affects a published TypeScript package (`@spree/sdk`, `@spree/cli`, or `create-spree-app`). Run `pnpm changeset` from inside that package's directory — each package owns its own `.changeset/` folder.- **Ensure CI passes.** PRs with failing CI will not be reviewed.## Reporting Bugs@@ -329,8 +321,24 @@ When reporting a bug, please include:- **Relevant logs or stack traces** (formatted with triple backticks)- **Your environment** (Ruby version, database, OS)+We have an [issue template](https://github.com/spree/spree/blob/main/.github/ISSUE_TEMPLATE.md) that will guide you through this.+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.+## 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.+## That's a wrap!Thank you for participating in Open Source and improving Spree - you're awesome!