Add good practice guides

guides/good-practices/ci.md

@@ -0,0 +1,29 @@
+---
+nav:
+  title: CI
+  position: 2
+
+---
+
+# CI
+
+CI should, at minimum, run static analysis and coding standards checks alongside the project or extension build to keep artifacts reproducible. Add sanity checks such as smoke tests and lightweight integration tests to catch regressions early. Automated tests—from unit to integration and e2e where feasible—make refactors, upgrades, and dependency changes safer.
+
+## Cross-cutting practices
+
+- Fail fast on coding standards and static analysis before slower e2e tests.
+- Use the shopware-cli formatter to keep code style consistent ([Shopware CLI formatter](../../products/cli/formatter.md)) and run the bundled validation tools in CI ([Shopware CLI validation tools](../../products/cli/validation.md)).
+- Produce artifacts once per commit (ZIP for plugins, deployable image/package for apps, built assets for projects) and promote the same artifact through stages.
+
+## Custom projects
+
+- Reuse the project build command ([Project build command](../../products/cli/project-commands/build.md)) to compile storefront/administration assets and warm caches. Run it in CI so deployments do not rebuild.
+- Use environment-specific config only in deployment, not in CI. See [setup patterns](../installation/setups/index.md) you can mirror in pipelines.
+- Add smoke tests against the HTTP layer plus DAL-level integration tests for custom entities.
+- Cache Composer/NPM dependencies but keep lockfiles committed for deterministic builds.
+
+## Custom/Store plugins
+
+- Build and validate with `shopware-cli extension build` ([Extension build command](../../products/cli/extension-commands/build.md)) to ensure the ZIP is reproducible.
+- Run unit/integration tests with the Shopware test environment; keep fixtures inside the plugin to avoid coupling to project data.
+- For Store plugins, add the Shopware Store validations early (linting, metadata, PHPStan) to catch review issues before submission ([Store submission via CLI](../../products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md)).

guides/good-practices/code-structure.md

@@ -0,0 +1,40 @@
+---
+nav:
+  title: Code structure
+  position: 1
+
+---
+
+# Code structure
+
+## Shared patterns
+
+- **Namespaces and autoloading**: Match PSR-4 to folder names; avoid deep nesting that hides ownership.
+- **Configuration**: Centralize defaults; document override points. Use environment variables only in the project layer, not in Store plugins.
+- **Documentation**: Each extension should ship a brief README with purpose, install/update steps, and known constraints.
+
+## Choose the right extension type
+
+- **Custom project/bundle**: Fit for bespoke installations you fully control. See the [bundle guide](../plugins/plugins/bundle.md) for the bundle layout and when to embed project-specific logic.
+- **Private/custom plugin**: Use the standard plugin skeleton for reusable features across a few projects. Start from the [plugin base guide](../plugins/plugins/plugin-base-guide.md) and keep project overrides thin.
+- **Store plugin**: Same plugin layout, but harden for Store review: strict metadata, no project-only hacks, testability, and BC guarantees.
+- **App**: Prefer when you cannot host PHP in the shop or need SaaS-style isolation. Follow the [app base guide](../plugins/apps/app-base-guide.md) for manifest and server structure.
+
+## Project/bundle structure
+
+- Keep domain logic in bundles, not in templates or controllers; expose services via dependency injection (see the [bundle guide](../plugins/plugins/bundle.md)).
+- Use Composer `type: shopware-platform-plugin` or `shopware-bundle` consistently; align namespaces with the bundle name.
+- Isolate integration points (events, DAL extensions) behind service classes so upgrades only touch narrow surfaces.
+
+## Plugin structure (custom and Store)
+
+- Start from the default plugin skeleton ([plugin base guide](../plugins/plugins/plugin-base-guide.md)); avoid bespoke autoloaders or custom entrypoints.
+- Keep configuration, migrations, administration, and storefront assets in their default folders; avoid cross-wiring plugins.
+- Encapsulate database schema changes with migrations; ship idempotent install/update code.
+- For Store plugins, avoid hard project assumptions (hostnames, queues, cron timing, file access); document requirements and provide safe fallbacks.
+
+## App structure
+
+- Keep the manifest minimal and explicit: permissions, webhooks, actions, and extensions should match the documented entrypoints ([app base guide](../plugins/apps/app-base-guide.md)).
+- Separate app backend (API/webhook handlers) from UI assets.
+- Avoid stateful coupling to shop runtime; design for multi-tenant hosting.

guides/good-practices/deployments.md

@@ -0,0 +1,33 @@
+---
+nav:
+  title: Deployments
+  position: 3
+
+---
+
+# Deployments
+
+Deploy with the same artifacts you built in CI, keep configuration outside the codebase, and make database changes predictable. Separate build from runtime wherever possible so releases stay repeatable and reversible.
+
+## Cross-cutting practices
+
+- Roll forward by default; keep rollbacks minimal (DB-aware and version-pinned) and practice them.
+- Use maintenance mode for schema-changing releases; add health checks and smoke tests post-deploy before exiting maintenance.
+- Tag releases consistently across code, artifacts, and Store metadata; keep build logs and deploy reports for audits.
+
+## Custom projects
+
+- Follow the deployment helper flow ([Deployment helper](../hosting/installation-updates/deployments/deployment-helper.md)) to keep steps ordered and reversible.
+- Use a repeatable deploy strategy (e.g. via the [Deployment helper](../hosting/installation-updates/deployments/deployment-helper.md)); keep environment config and secrets outside the repo.
+
+## Custom/Store plugins
+
+- Ship plugins as versioned ZIPs from CI ([Extension build command](../../products/cli/extension-commands/build.md)); install/activate via CLI or deployment automation.
+- Apply plugin migrations during deploy and keep update steps idempotent so retries are safe.
+- For Store plugins, avoid post-deploy manual tweaks.
+
+## Apps
+
+- Deploy app backends like any web service; use blue/green or canary so webhook handling is uninterrupted.
+- Keep manifest versions in sync with deployed code; register new webhooks before emitting new events to avoid gaps.
+- Externalize credentials and endpoints; design for multi-tenant hosting and retry-safe handlers.

guides/good-practices/index.md

@@ -0,0 +1,12 @@
+---
+nav:
+  title: Good Practices
+  position: 15
+
+---
+
+# Good Practices
+
+Flexibility and openness are at shopware's heart; we believe that software and frameworks specifically should work for you and your business case, rather than the other way around.
+Therefore, we don't believe in one size fits all solutions and absolutism. But with that in mind, we have seen a ton of projects succeeding by following the same principles, as well as a host of projects failing because of not following them.
+We consider the following guardrails to be generally `good practices` and `best defaults`. When you build shopware-based projects, you definitely should know about those practices and default to following them. Not adhering to those guidelines should always be an explicit decision, where you actively acknowledge the tradeoffs that come with it.

guides/good-practices/upgrades.md

@@ -0,0 +1,39 @@
+---
+nav:
+  title: Upgrades
+  position: 4
+
+---
+
+# Upgrades
+
+Upgrade plans should protect customer data and keep extensions compatible. Rehearse upgrades on staging with production-like data before touching production, and keep recovery steps ready.
+
+## Cross-cutting practices
+
+- Automate pre-upgrade checks (PHP/DB versions, extensions, disk space) and post-upgrade smoke tests.
+- Keep database backups and a recovery plan; practice on staging with production-like data.
+- Track deprecations early and use official tooling (e.g. Rector/Admin codemods referenced in [Performing updates](../hosting/installation-updates/performing-updates.md)) to reduce manual work.
+
+## Custom projects
+
+- Follow the update guide ([Performing updates](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order.
+- Review changelogs/UPGRADE files per release; script data migrations and cache warmups.
+- Use feature toggles or maintenance mode to decouple risky changes from the deploy moment.
+
+## Custom plugins
+
+- Provide migration code for schema/config changes; ship defaults that work on older core versions until you deliberately drop support.
+- Test against the target Shopware version matrix before rollout; note breaking changes in the plugin README.
+
+## Store plugins
+
+- Align Store metadata (compatibility range, changelog) with the tested core versions; refuse installation on unsupported versions.
+- Run Shopware Store validation on the new build before submission ([Store submission via CLI](../../products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md)).
+- Communicate BC breaks explicitly; prefer additive changes and feature flags to keep existing shops stable.
+
+## Apps
+
+- Version manifests carefully: broaden compatibility only after testing; narrow it when deprecations apply.
+- Keep webhook/action handlers tolerant to new fields and events; avoid hard coupling to specific core patch behavior.
+- Document required scopes/permissions per version and avoid removing scopes without a migration path.