docs: explain plugin scaffolding and generator troubleshooting - #2473
Merged
Micha Hobert (Isengo1989) merged 26 commits intoAug 26, 2026
Merged
Conversation
Developer Docs healthcheckStatus: Completed with |
Copilot started work on behalf of
somethings (lasomethingsomething)
August 21, 2026 16:31
View session
somethings (lasomethingsomething)
marked this pull request as ready for review
August 24, 2026 14:18
Contributor
📢 Developer Announcement RecommendationRecommendation: ❌ No Announcement Recommended No developer announcement signals were detected.
|
Copilot started reviewing on behalf of
somethings (lasomethingsomething)
August 24, 2026 14:18
View session
somethings (lasomethingsomething)
requested review from
a team,
Anne (Ant1gua),
Micha Hobert (Isengo1989),
Malte Janz (MalteJanz),
Soner (shyim) and
Tomasz Turkowski (tturkowski)
and removed request for
a team
August 24, 2026 14:19
Contributor
There was a problem hiding this comment.
Pull request overview
This PR strengthens the Shopware plugin documentation by explaining how generator output typically represents coordinated framework wiring (registration, discovery, build/runtime), helping readers interpret scaffolded files as connected parts rather than isolated artifacts.
Changes:
- Adds short “generator output is a connected chain” explanations across Storefront JS, controllers, scheduled tasks, Store API routes, and Administration modules.
- Extends the “Creating Plugins” guide with troubleshooting context emphasizing wiring/discovery/build boundaries.
- Refines a few in-guide code comments to better align with the narrative (e.g., “Register your custom Storefront plugin”).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| guides/plugins/plugins/storefront/javascript/add-custom-javascript.md | Adds generator-chain context for main.js/plugin class/selector and updates code comment wording. |
| guides/plugins/plugins/storefront/controllers/add-custom-controller.md | Adds info callouts explaining how controllers relate to service registration and route discovery. |
| guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md | Adds explanation of scheduled task vs handler roles and generator wiring implications. |
| guides/plugins/plugins/plugin-base-guide.md | Adds a generator-output framing paragraph to connect the base guide to focused feature guides. |
| guides/plugins/plugins/framework/store-api/add-store-api-route.md | Adds info callouts clarifying route/service/routes.php responsibilities and debugging interpretation. |
| guides/plugins/plugins/creating-plugins.md | Adds troubleshooting guidance about generated output and reinforces version/adaptation context. |
| guides/plugins/plugins/administration/module-component-management/add-custom-module.md | Adds info callouts explaining how module entrypoints, registration, snippets, and build relate. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Tomasz Turkowski (tturkowski)
approved these changes
Aug 25, 2026
Contributor
|
lgtm, but it's worth mentioning that I do not have deep knowledge about frontend parts so far. |
Soner (shyim)
approved these changes
Aug 25, 2026
somethings (lasomethingsomething)
removed request for
Anne (Ant1gua) and
Malte Janz (MalteJanz)
August 25, 2026 10:44
Contributor
Author
|
Micha Hobert (@Isengo1989) Approved from DX Tools side, now over to you :) |
Adds Storefront controller lifecycle guide explaining how controller class, route attributes, routing import, service registration, and cache connect. Warns about generated plugin base class name mismatches when plugin name does not follow UpperCamelCase, which can cause PluginBaseClassNotFoundException during installation even when plugin:refresh succeeds. Links lifecycle guides from index pages and remaining documentation. Aligns all lifecycle pages with repo formatting conventions (frontmatter blank lines, consistent command formatting, improved phrasing). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Co-authored-by: lasomethingsomething <2453640+lasomethingsomething@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Micha Hobert (Isengo1989)
force-pushed
the
docs/scaffolding-q-and-a-findings
branch
from
August 26, 2026 07:01
ed7cc5d to
1332a0d
Compare
Micha Hobert (Isengo1989)
approved these changes
Aug 26, 2026
Micha Hobert (Isengo1989)
left a comment
Micha Hobert (Isengo1989)
left a comment
Contributor
There was a problem hiding this comment.
Thanks for the PR somethings (@lasomethingsomething) 👍
Micha Hobert (Isengo1989)
added
the
Improvement
Micha Hobert (Isengo1989)
deleted the
docs/scaffolding-q-and-a-findings
branch
August 26, 2026 07:51
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
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.
Summary
Adds context explaining how Shopware plugin generators produce coordinated framework features, rather than isolated files.
New info is based on a hands-on walkthrough of current
bin/console plugin:createscaffolding and cross-checked against currentshopware/shopwarescaffolding generators and the proposedshopware-cli extension creategenerator epics: shopware/shopware-cli#1255, shopware/shopware-cli#1280.The goal is to bridge the gap between “the generator created these files” and “here’s how those pieces work together”, without adding another workflow or duplicating existing guides.