How shopware/docs works
Project Type and Purpose
• This repository holds the developer documentation for Shopware 6. It organizes “Concepts”, “Guides”, “Products”, and “Resources” into clearly defined sections.
• Its primary function is to provide a central location where developers can access high-quality, maintained documentation about Shopware concepts and integration details.
• The README and file structure emphasize automation (through GitHub workflows) for content validation and build processes before deployment.
Analyzing the File Structure
• Key top-level folders include:
• “concepts” – containing theory and API explanations
• “guides” – step-by-step instructions related to hosting, installation, and integrations
• “products” – documentation on various Shopware products and extensions (CLI commands, digital sales rooms, etc.)
• “resources” – guidelines, references for code, testing, and configuration details
• “.github/workflows” – YAML files for automating checks such as markdown style, spellcheck, grammar, external links, file formatting, and updating ADRs.
• There are also multiple scripts under “.github/scripts”, which are used for migrations, formatting rules, updating ADRs, etc.
• Configuration files (like .editorconfig, .gitignore, and others) indicate standard practices to ensure consistency in developer contributions.
Main Components
a. Documentation Content Modules:
• “Concepts”, “Guides”, “Products”, “Resources” folders (each representing a major content module).
• “Assets” – containing images, ADR files, and other media that support the documents.
b. CI/CD & Automation Workflows:
• GitHub Actions Workflows (e.g., file-format-check, markdown-style-check, spellcheck, external link check).
• Scripts in “.github/scripts” that help keep certain files in sync with the Shopware core repository.
• These workflows are triggered by events (push, pull_request, schedule) to validate and deploy the documentation.
c. Version Control & Repository:
• The repository itself (hosted on GitHub) is the source for the documentation and workflow definitions.
d. External Dependencies and Tooling:
• Tools such as Reviewdog (for grammar/language check), markdown-lint, py-spelling, and lychee are integrated into the CI pipelines.
• There is also reference to deployment mechanisms (via GitHub Pages or a similar hosting mechanism pointing to developer.shopware.com).
Relationships and Interactions
• The content (markdown files and assets) is stored and maintained in the repository.
• GitHub Action workflows continuously test and build the repository whenever changes occur.
• The workflows perform “Linting”, “Spellchecking”, “Link Validation”, etc.
• Once validated, the documentation is deployed (or updated) on the developer portal (https://developer.shopware.com/docs).
• Synchronization scripts keep selected parts (e.g., ADRs, code guidelines) in sync with the main Shopware repository.
Architectural Patterns and Design Principles
• Separation of Concerns: Different folders for documentation content vs. CI/CD & automation.
• Continuous Integration: Automated workflows ensure quality and correctness before changes are merged.
• Modularity: The documentation itself is modularized into distinct sections (Concepts, Guides, Products, Resources) to support ease of navigation and contribution.
• Extensibility: Numerous guides and reference documents indicate that the system is built for extensibility and collaboration via community contributions.
• Branch it to show the major categories of documentation content (“Concepts”, “Guides”, “Products”, “Resources”, “Assets”).
• CI/CD branch to the “Deployment Server/Developer Portal” that hosts developer.shopware.com.
• Clearly label synchronization flows (e.g., from our “Shopware Core ADR” nodes to the documentation ADR folder) as well as feedback loops (like failure notifications if a workflow fails).