From 05272d33bbd8af9836ac350c29c2e905407e774c Mon Sep 17 00:00:00 2001 From: Micha Date: Thu, 18 Dec 2025 11:24:32 +0100 Subject: [PATCH 01/11] chore/add-agents-md --- AGENTS.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..5a45aae23 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,155 @@ +# AGENTS.md + +This file provides guidance to coding agents like CursorAI or Claude Code. + +## Repository Overview + +This is the **Shopware Developer Documentation** repository (`shopware/docs`) that contains comprehensive developer documentation for Shopware 6, served at [developer.shopware.com/docs](https://developer.shopware.com/docs/). The documentation is integrated with the main [developer portal](https://github.com/shopware/developer-portal) repository. + +> **Note:** +> This documentation covers **Shopware 6** and is intended for use with the [shopware/shopware](https://github.com/shopware/shopware) open-source e-commerce framework. +> +> For contributing to or understanding Shopware core, see the [shopware/shopware GitHub repository](https://github.com/shopware/shopware) for source code and core platform issues. + + +## Documentation Structure + +The repository follows a 4-tier hierarchical organization: + +- **`/concepts/`** - High-level architectural concepts (API, commerce, extensions, framework) +- **`/guides/`** - Step-by-step tutorials (hosting, installation, integrations, plugins) +- **`/products/`** - Product-specific documentation (CLI, PaaS, extensions, Digital Sales Rooms) +- **`/resources/`** - References, guidelines, ADRs, and tooling documentation + +## Common Development Commands + +### Documentation Development + +```bash +# Setup developer portal environment +pnpm run docs:env + +# Link documentation content to developer portal +pnpm run docs:link + +# Preview documentation locally +pnpm run docs:preview +``` + +### Quality Control + +```bash +# Run spellcheck via docker +make spellcheck-local + +# Run spellcheck with installed sources (aspell and pyspelling) +make spellcheck + +# Auto-fix markdown issues (be aware that it can only fix certain issues) +make fix + +# Sort spellcheck wordlist +LC_ALL=C sort .wordlist.txt -o .wordlist.txt +``` + +## Key Architecture Patterns + +### Dual Repository System + +- **Content Repository**: `shopware/docs` (this repo) - contains all markdown content +- **Presentation Layer**: `shopware/developer-portal` - handles building and serving +- **Integration**: Content is linked via symlinks using `docs-cli.cjs` + +### Automated Content Synchronization + +Critical content auto-syncs from main `shopware/shopware` repository every 3 hours: + +- `/adr/*.md` → `/resources/references/adr/*.md` (Architecture Decision Records) +- `/adr/assets/*` → `/assets/adr/*` (ADR assets) +- `/coding-guidelines/core` → `/resources/guidelines/code/core` (Coding standards) + +### Extension Documentation Architecture + +- **Apps**: Server-based external integrations with JWT validation, SDK integration +- **Plugins**: Internal Shopware core extensions with DAL, services, events +- **Themes**: Asset management, SCSS variables, inheritance system + +## Quality Assurance Workflows + +The repository has extensive automated quality control: + +- **Markdown linting**: Validates formatting and style consistency +- **Spell checking**: Uses custom wordlist (`.wordlist.txt`) with pyspelling +- **Grammar checking**: Reviewdog integration for language validation +- **External link validation**: Lychee tool checks for broken links +- **Asset naming validation**: Enforces strict naming conventions +- **PageRef validation**: Custom Deno script checks internal cross-references + +## Development Environment + +- **Node.js**: 18.x with pnpm package manager +- **Nix**: Uses `devenv.nix` for consistent development environments +- **Build System**: VitePress managed through developer portal +- **CI/CD**: 11+ GitHub Actions workflows for quality control and synchronization + +## File Conventions + +### Markdown Style + +- Configuration in `markdown-style-config.yml` +- 40+ linting rules enabled +- Consistent formatting enforced via CI/CD + +### Asset Management + +- All assets in `/assets/` directory +- Strict naming conventions enforced +- Images, diagrams, and media files (40,000+ characters worth) +- Extensive use of Mermaid diagrams, SVGs, and screenshots + +### Code Snippets + +- Reusable examples in `/snippets/` directory +- Multi-format support (PHP, JavaScript, Vue, Twig, XML, YAML, JSON) +- Configuration examples for apps, plugins, and system setup + +## Cross-linking System + +- Uses PageRef components for consistent internal linking +- Hierarchical navigation with clear parent-child relationships +- Context-aware references between Concepts ↔ Guides + +## Version Management + +- Branch-based versioning (`main`, `v6.5`, `v6.4`) +- Feature flag documentation for experimental features +- Clear deprecation notices and upgrade paths +- Automated format migration (Gitbook → VitePress) + +## Redirects + +.gitbook.yaml is used to manage redirects from old URLs to new ones, ensuring users find the correct content even after structural changes. + +This can be done by the following prompt: + +```shell +Check the current branch against main. There should be two files be moved. Create a redirect in the .gitbook.yaml in the pattern that already exists. +``` + +## Dos and Don'ts for AI agents + +### Do + +- **Follow repository conventions**: Adhere to the existing documentation structure, markdown style rules, and asset naming conventions. +- **Respect synced content**: When changes are needed in synced areas (`/resources/references/adr/`, `/assets/adr/`, `/resources/guidelines/code/core/`), propose edits against the `shopware/shopware` repository instead of changing them here. +- **Keep redirects consistent**: When pages are moved or removed, compare your branch against `main`, identify changed paths, and add redirects to `.gitbook.yaml` following the existing patterns. +- **Use quality checks when appropriate**: Run `make lint`, `make fix`, or the configured spellcheck tasks when you make non-trivial documentation changes, especially if CI feedback suggests issues. +- **Prefer incremental, focused changes**: Keep pull requests small and well-scoped so they are easy to review and reason about. + +### Don't + +- **Don't edit synced files directly**: Avoid modifying files that are automatically synchronized from `shopware/shopware`, as those changes will be overwritten. +- **Don't break existing URLs**: Avoid renaming or moving pages without adding a corresponding redirect entry in `.gitbook.yaml`. +- **Don't bypass style and spelling rules**: Do not introduce markdown formatting that conflicts with `markdown-style-config.yml`, or ignore repeated spelling issues that should be added to `.wordlist.txt`. +- **Don't change repository tooling lightly**: Avoid editing CI workflows, configuration files, or build tooling unless explicitly requested, and always keep changes minimal and well-documented. +- **Don't mix unrelated changes**: Do not bundle large, unrelated modifications (for example, structural moves plus extensive content rewrites) into a single change set. From d117402a65cb14bfe2a60bd58bc564a2d7256844 Mon Sep 17 00:00:00 2001 From: Micha Date: Thu, 18 Dec 2025 11:27:27 +0100 Subject: [PATCH 02/11] fix/markdown --- AGENTS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5a45aae23..5764a9f63 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,6 @@ This is the **Shopware Developer Documentation** repository (`shopware/docs`) th > > For contributing to or understanding Shopware core, see the [shopware/shopware GitHub repository](https://github.com/shopware/shopware) for source code and core platform issues. - ## Documentation Structure The repository follows a 4-tier hierarchical organization: From 505b3d65138ab466b379418f2ea5f004d3041a4f Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 18 Dec 2025 17:57:52 +0100 Subject: [PATCH 03/11] Update AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5764a9f63..16309116e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -127,7 +127,7 @@ The repository has extensive automated quality control: ## Redirects -.gitbook.yaml is used to manage redirects from old URLs to new ones, ensuring users find the correct content even after structural changes. +`.gitbook.yaml` is used to manage redirects from old URLs to new ones, ensuring users find the correct content even after structural changes. This can be done by the following prompt: From eb86318797cfd5936d3ef13b7ff263804d23760c Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 18 Dec 2025 17:58:47 +0100 Subject: [PATCH 04/11] Update AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 16309116e..9d612b130 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -132,7 +132,7 @@ The repository has extensive automated quality control: This can be done by the following prompt: ```shell -Check the current branch against main. There should be two files be moved. Create a redirect in the .gitbook.yaml in the pattern that already exists. +Check the current branch against main. There should be two files to be moved. Create a redirect in the `.gitbook.yaml` in the pattern that already exists. ``` ## Dos and Don'ts for AI agents From 09a0677546efca172db01ba70f2b7f2530ec45ca Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 18 Dec 2025 17:59:06 +0100 Subject: [PATCH 05/11] Update AGENTS.md --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9d612b130..d6ed45286 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -135,9 +135,9 @@ This can be done by the following prompt: Check the current branch against main. There should be two files to be moved. Create a redirect in the `.gitbook.yaml` in the pattern that already exists. ``` -## Dos and Don'ts for AI agents +## Do's and Don'ts for AI agents -### Do +### Do's - **Follow repository conventions**: Adhere to the existing documentation structure, markdown style rules, and asset naming conventions. - **Respect synced content**: When changes are needed in synced areas (`/resources/references/adr/`, `/assets/adr/`, `/resources/guidelines/code/core/`), propose edits against the `shopware/shopware` repository instead of changing them here. From 7f1ca6ba20c928f2a56560b28b8cbfc4a917f5ea Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 18 Dec 2025 17:59:19 +0100 Subject: [PATCH 06/11] Update AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d6ed45286..80426517f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -139,7 +139,7 @@ Check the current branch against main. There should be two files to be moved. Cr ### Do's -- **Follow repository conventions**: Adhere to the existing documentation structure, markdown style rules, and asset naming conventions. +- **Follow repository conventions**: Adhere to the existing documentation structure, markdown style rules, and asset naming conventions as covered in the [documentation guidelines](https://developer.shopware.com/docs/resources/guidelines/documentation-guidelines/) - **Respect synced content**: When changes are needed in synced areas (`/resources/references/adr/`, `/assets/adr/`, `/resources/guidelines/code/core/`), propose edits against the `shopware/shopware` repository instead of changing them here. - **Keep redirects consistent**: When pages are moved or removed, compare your branch against `main`, identify changed paths, and add redirects to `.gitbook.yaml` following the existing patterns. - **Use quality checks when appropriate**: Run `make lint`, `make fix`, or the configured spellcheck tasks when you make non-trivial documentation changes, especially if CI feedback suggests issues. From c58830b7452aa715b1b44750356e40f98d35a9c7 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 18 Dec 2025 17:59:38 +0100 Subject: [PATCH 07/11] Update AGENTS.md --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 80426517f..2dfb70368 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,10 +6,11 @@ This file provides guidance to coding agents like CursorAI or Claude Code. This is the **Shopware Developer Documentation** repository (`shopware/docs`) that contains comprehensive developer documentation for Shopware 6, served at [developer.shopware.com/docs](https://developer.shopware.com/docs/). The documentation is integrated with the main [developer portal](https://github.com/shopware/developer-portal) repository. -> **Note:** +:::info > This documentation covers **Shopware 6** and is intended for use with the [shopware/shopware](https://github.com/shopware/shopware) open-source e-commerce framework. > > For contributing to or understanding Shopware core, see the [shopware/shopware GitHub repository](https://github.com/shopware/shopware) for source code and core platform issues. +::: ## Documentation Structure From 27ba7f38e5175620e942f6536301de29daa16f5f Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 18 Dec 2025 17:59:50 +0100 Subject: [PATCH 08/11] Update AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2dfb70368..238bdd8a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -141,7 +141,7 @@ Check the current branch against main. There should be two files to be moved. Cr ### Do's - **Follow repository conventions**: Adhere to the existing documentation structure, markdown style rules, and asset naming conventions as covered in the [documentation guidelines](https://developer.shopware.com/docs/resources/guidelines/documentation-guidelines/) -- **Respect synced content**: When changes are needed in synced areas (`/resources/references/adr/`, `/assets/adr/`, `/resources/guidelines/code/core/`), propose edits against the `shopware/shopware` repository instead of changing them here. +- **Maintain synced content**: When changes are needed in synced areas (`/resources/references/adr/`, `/assets/adr/`, `/resources/guidelines/code/core/`), propose edits against the `shopware/shopware` repository instead of changing them here. - **Keep redirects consistent**: When pages are moved or removed, compare your branch against `main`, identify changed paths, and add redirects to `.gitbook.yaml` following the existing patterns. - **Use quality checks when appropriate**: Run `make lint`, `make fix`, or the configured spellcheck tasks when you make non-trivial documentation changes, especially if CI feedback suggests issues. - **Prefer incremental, focused changes**: Keep pull requests small and well-scoped so they are easy to review and reason about. From 8e4ad2d41c95f5c595daf6bcff44a9416759421a Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Thu, 18 Dec 2025 18:29:08 +0100 Subject: [PATCH 09/11] Add new terms to .wordlist.txt --- .wordlist.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 59cb52d5b..ab5872d0d 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -253,6 +253,7 @@ CustomerRecoveryAware CustomerRecoveryStorer CustomerStorer CustomerTagRule +CursorAI DAL DBAL DDL @@ -414,6 +415,7 @@ FroshTools Fullstack GBP GDPR +Gitbook GIFs GenericPage GenericPageLoader @@ -655,6 +657,7 @@ OrderTransactionCaptureRefundPositionCollection OrderTransactionEntity OrderTransactionRefundCollection OrderTransactionStorer +PageRef PCOV PEM PHPStan @@ -1013,6 +1016,7 @@ VersionDataPayloadField VersionField VirtualHosts Vite +VitePress Vitepress Vitest VoiceOver @@ -1676,6 +1680,7 @@ profilers programmatically pseudocode psh +pyspelling pwa px py @@ -1945,6 +1950,7 @@ whitespaces whoami wil wishlist +wordlist www xasjkyld xhost's From 7eab6f34945939cb797aba17cf42c0e89e424533 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 18 Dec 2025 17:29:19 +0000 Subject: [PATCH 10/11] chore: sort .wordlist.txt --- .wordlist.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index ab5872d0d..8f691c8db 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -236,6 +236,7 @@ CrossSellingDataSet Crowdin Ctrl CurrencyRule +CursorAI CustomAppAware CustomAppEvent CustomAppStorer @@ -253,7 +254,6 @@ CustomerRecoveryAware CustomerRecoveryStorer CustomerStorer CustomerTagRule -CursorAI DAL DBAL DDL @@ -415,11 +415,11 @@ FroshTools Fullstack GBP GDPR -Gitbook GIFs GenericPage GenericPageLoader GitLab +Gitbook Github GlobFileLoader GmbH @@ -657,7 +657,6 @@ OrderTransactionCaptureRefundPositionCollection OrderTransactionEntity OrderTransactionRefundCollection OrderTransactionStorer -PageRef PCOV PEM PHPStan @@ -681,6 +680,7 @@ PageLoadedEvent PageLoadedEvents PageLoader PageLoader structs +PageRef PageType Pagelet PageletLoader @@ -1680,10 +1680,10 @@ profilers programmatically pseudocode psh -pyspelling pwa px py +pyspelling qa qa@shopware.com qty's From 209beaa004ccf5899b8946db28e074b5e02ddff7 Mon Sep 17 00:00:00 2001 From: Micha Date: Fri, 19 Dec 2025 10:41:31 +0100 Subject: [PATCH 11/11] revert/some-changes --- AGENTS.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 238bdd8a9..fc5b55a87 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,11 +6,10 @@ This file provides guidance to coding agents like CursorAI or Claude Code. This is the **Shopware Developer Documentation** repository (`shopware/docs`) that contains comprehensive developer documentation for Shopware 6, served at [developer.shopware.com/docs](https://developer.shopware.com/docs/). The documentation is integrated with the main [developer portal](https://github.com/shopware/developer-portal) repository. -:::info -> This documentation covers **Shopware 6** and is intended for use with the [shopware/shopware](https://github.com/shopware/shopware) open-source e-commerce framework. -> +> **Note:** +> This documentation covers **Shopware 6** and is intended for use with the [shopware/shopware](https://github.com/shopware/shopware) open-source e-commerce framework. +> > For contributing to or understanding Shopware core, see the [shopware/shopware GitHub repository](https://github.com/shopware/shopware) for source code and core platform issues. -::: ## Documentation Structure @@ -56,7 +55,7 @@ LC_ALL=C sort .wordlist.txt -o .wordlist.txt ### Dual Repository System -- **Content Repository**: `shopware/docs` (this repo) - contains all markdown content +- **Content Repository**: `shopware/docs` (this repo) - contains all Markdown content - **Presentation Layer**: `shopware/developer-portal` - handles building and serving - **Integration**: Content is linked via symlinks using `docs-cli.cjs` @@ -83,13 +82,13 @@ The repository has extensive automated quality control: - **Grammar checking**: Reviewdog integration for language validation - **External link validation**: Lychee tool checks for broken links - **Asset naming validation**: Enforces strict naming conventions -- **PageRef validation**: Custom Deno script checks internal cross-references +- **PageRef validation**: A custom Deno script checks internal cross-references ## Development Environment - **Node.js**: 18.x with pnpm package manager - **Nix**: Uses `devenv.nix` for consistent development environments -- **Build System**: VitePress managed through developer portal +- **Build System**: VitePress managed through the developer portal - **CI/CD**: 11+ GitHub Actions workflows for quality control and synchronization ## File Conventions @@ -103,7 +102,7 @@ The repository has extensive automated quality control: ### Asset Management - All assets in `/assets/` directory -- Strict naming conventions enforced +- Strict naming conventions are enforced - Images, diagrams, and media files (40,000+ characters worth) - Extensive use of Mermaid diagrams, SVGs, and screenshots @@ -140,8 +139,8 @@ Check the current branch against main. There should be two files to be moved. Cr ### Do's -- **Follow repository conventions**: Adhere to the existing documentation structure, markdown style rules, and asset naming conventions as covered in the [documentation guidelines](https://developer.shopware.com/docs/resources/guidelines/documentation-guidelines/) -- **Maintain synced content**: When changes are needed in synced areas (`/resources/references/adr/`, `/assets/adr/`, `/resources/guidelines/code/core/`), propose edits against the `shopware/shopware` repository instead of changing them here. +- **Follow repository conventions**: Adhere to the existing documentation structure, markdown style rules, and asset naming conventions. +- **Respect synced content**: When changes are needed in synced areas (`/resources/references/adr/`, `/assets/adr/`, `/resources/guidelines/code/core/`), propose edits against the `shopware/shopware` repository instead of changing them here. - **Keep redirects consistent**: When pages are moved or removed, compare your branch against `main`, identify changed paths, and add redirects to `.gitbook.yaml` following the existing patterns. - **Use quality checks when appropriate**: Run `make lint`, `make fix`, or the configured spellcheck tasks when you make non-trivial documentation changes, especially if CI feedback suggests issues. - **Prefer incremental, focused changes**: Keep pull requests small and well-scoped so they are easy to review and reason about. @@ -150,6 +149,6 @@ Check the current branch against main. There should be two files to be moved. Cr - **Don't edit synced files directly**: Avoid modifying files that are automatically synchronized from `shopware/shopware`, as those changes will be overwritten. - **Don't break existing URLs**: Avoid renaming or moving pages without adding a corresponding redirect entry in `.gitbook.yaml`. -- **Don't bypass style and spelling rules**: Do not introduce markdown formatting that conflicts with `markdown-style-config.yml`, or ignore repeated spelling issues that should be added to `.wordlist.txt`. +- **Don't bypass style and spelling rules**: Do not introduce Markdown formatting that conflicts with `markdown-style-config.yml`, or ignore repeated spelling issues that should be added to `.wordlist.txt`. - **Don't change repository tooling lightly**: Avoid editing CI workflows, configuration files, or build tooling unless explicitly requested, and always keep changes minimal and well-documented. - **Don't mix unrelated changes**: Do not bundle large, unrelated modifications (for example, structural moves plus extensive content rewrites) into a single change set.