Draft
Conversation
Contributor
|
Jonas Elfering (@keulinho) ready to review already, or should we wait till it's out of draft? |
|
|
||
| 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 |
There was a problem hiding this comment.
It's also worth mentioning both keeping up with updates (ie. update once a quarter) and also to make use of the backwards compatability that is added to new features - these allow a cross-over period when new feature is available but behind a feature flag -> these times should be used to do the upgrade without it being on the critical path.
Contributor
|
Heads up: With approval from Jonas Elfering (@keulinho) I'll fold this content into other docs changes I'm making, as this info will serve as valuable "anchoring" context in our upcoming, new "Development" docs section. |
| ## 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. |
Member
There was a problem hiding this comment.
mention those system:check thingy?
Contributor
Will it be part of #2111 ? |
Comment on lines
+10
to
+12
| 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| 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. | |
| Shopware is designed to support a wide range of business requirements through its flexible, extensible architecture. This flexibility allows teams to choose between different implementation approaches depending on their project goals and constraints. | |
| Across many successful implementations, however, certain architectural patterns and engineering practices have consistently produced more maintainable, scalable, and reliable systems. The recommendations in this section reflect these proven approaches and should be understood as guardrails and sensible defaults rather than strict rules. | |
| When building Shopware-based projects, you should be familiar with these practices and treat them as the starting point for your decisions. Deviating from them can be entirely valid, but should be done consciously, with a clear understanding of the associated trade-offs. |
|
|
||
| # 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| 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. |
| - **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. |
There was a problem hiding this comment.
please can we also mention, that if the extension is only template and/or JS, they should also do it in an app?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First draft to collect good practices for external devs to follow
mostly intended to give guidance and link out to the correct existing section in the docs