adds upgrade guide and apidocs#2134
adds upgrade guide and apidocs#2134somethings (lasomethingsomething) wants to merge 30 commits intomainfrom
Conversation
|
|
somethings (lasomethingsomething)
requested review from
Micha Hobert (Isengo1989) and
Su (sushmangupta)
|
Just quickly skimmed over it, and there is an issue with the files used in some MD files (rel paths are not working anymore) 
The language 'script' is not loaded, falling back to 'txt' for syntax highlighting. |
|
somethings (@lasomethingsomething) - Should we consider adding foundational Core concepts to the Architecture section https://developer.shopware.com/docs/concepts/framework/architecture/ ? |
Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com>
Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com>
Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com>
|
Su (@sushmangupta) Regarding arch concepts, go ahead or someone else can add -- no bandwidth for additional changes like that given the other dev changes forthcoming. |
added here : 2bef043 |
|
|
||
| # Administration | ||
|
|
||
| These guides cover upcoming architectural changes and migration paths affecting Administration extensions. Use them to prepare plugins for major system transitions: |
There was a problem hiding this comment.
depending on the version not all of them are upcoming, vue3, pinia & vite for example are already completed
There was a problem hiding this comment.
Jonas Elfering (@keulinho) How's this? => "These guides cover architectural changes and migration paths affecting Administration extensions, helping you prepare plugins for major system transitions. Depending on the version, some changes (for example, Vue 3, Pinia, and Vite) may have already been completed."
|
|
||
| * **Core**: Framework-level changes, data abstraction layer (DAL) updates, APIs, feature removals, and backend behavior. | ||
| * **[Administration](administration/index.md)**: frontend framework upgrades, Vue upgrades, breaking changes. | ||
| * **Translations**: [Extension translation](extension-translation), [Language pack migration](./language-pack-migration). |
There was a problem hiding this comment.
what's meant by this and the extensions point?
Or rather by this whole paragraph?
When we have a major upgrade and you wanna make your extension compatible there are defiently changes in the core, admin and storefront that you need to look at 🤔
There was a problem hiding this comment.
Jonas Elfering (@keulinho) As the section title aims to suggest, it's meant to serve as a round-up of the section's contents. Wondering if this is better:
Upgrades can affect different parts of the platform. A major release can include changes across several of these areas at the same time:
- Core: Framework-level changes, data abstraction layer (DAL) updates, APIs, feature removals, and backend behavior.
- Administration: Frontend framework updates, Vue upgrades, and other breaking changes in the admin.
- Translations: Extension translation changes and language pack migrations.
- Extensions: Version compatibility requirements and potential refactorings that extension developers may need to apply when upgrading.
Extensions may be affected by changes in Core, Administration, or Storefront
and should be reviewed accordingly.
| To reduce long-term upgrade cost: | ||
|
|
||
| * Avoid internal APIs and undocumented features | ||
| * Avoid unstable Admin patterns (`this.$parent`, prop mutation, Vue internals) |
There was a problem hiding this comment.
this looks super concrete compared to the others, not sure if it fits in, IMHO it's an extension to the first point
There was a problem hiding this comment.
Jonas Elfering (@keulinho) How about this? ==> "Avoid relying on internal or undocumented APIs (e.g., unstable Admin patterns like this.$parent, direct prop mutation, or Vue internals)"
|
|
||
| * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. | ||
| * Review [changelogs](https://github.com/shopware/shopware/tree/trunk/changelog) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. | ||
| * Script data migrations and cache warm-ups. |
There was a problem hiding this comment.
what does this mean? you would you do that?
There was a problem hiding this comment.
Jonas Elfering (@keulinho) Text taken from https://github.com/shopware/docs/blob/6d15c147afaba496ec8819b2ab1ab3bdb8b1fa98/guides/good-practices/upgrades.md#custom-projects ("Custom Projects" section => "Review changelogs/UPGRADE files per release; script data migrations and cache warmups"
| * Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. | ||
| * Review [changelogs](https://github.com/shopware/shopware/tree/trunk/changelog) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. | ||
| * Script data migrations and cache warm-ups. | ||
| * Use feature toggles or maintenance mode to decouple risky changes from the deployment. |
There was a problem hiding this comment.
How does this fit into the upgrade guide? 🤔
How does maintenance mode decouple risky changes from the deployment?
There was a problem hiding this comment.
| * Script data migrations and cache warm-ups. | ||
| * Use feature toggles or maintenance mode to decouple risky changes from the deployment. | ||
|
|
||
| ### Custom plugins |
There was a problem hiding this comment.
aren't we mixing things here? First we talk about how to upgrade shopware
here we talk about how to version your extensions 🤔
There was a problem hiding this comment.
I took this section from your unmerged PR/file "upgrades.md": https://github.com/shopware/docs/blob/6d15c147afaba496ec8819b2ab1ab3bdb8b1fa98/guides/good-practices/upgrades.md
|
|
||
| * Version manifests carefully. Broaden compatibility only after testing, and 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. |
There was a problem hiding this comment.
How/Why?
We already have a permission system built directly into the app system, what should be done in addition to that? And why should i avoid removing scopes? IMHO it should be good practice to not request permissions you don't need anymore
There was a problem hiding this comment.
Got the text from here => https://github.com/shopware/docs/blob/6d15c147afaba496ec8819b2ab1ab3bdb8b1fa98/guides/good-practices/upgrades.md (Apps => "Document required scopes/permissions per version and avoid removing scopes without a migration path.")
| nav: | ||
| title: Store API | ||
| position: 10 | ||
| position: 41 |
There was a problem hiding this comment.
We always use 10 count steps. Let´s stick with that format for the sake of universal usage, maybe it also has backdraws that Bojan Rajh (@bojanrajh) might know or why we used 10 count steps in the first place
4 participants
This moves upgrade-related files previously stored near the bottom of the left sidebar into a dedicated folder. It also consolidates API-related concepts information into a page that replaces one-paragraph pages and renames the folder "APIs" as we have more than one.
The pages in the guides > upgrades-migrations > admin folder will require some review at a later stage; for now I've just moved them.