docs/research/changelog-and-php-floor.md

@@ -0,0 +1,167 @@
+# Research: shopware-cli changelog handling and the PHP floor for a Shopware 6.6 plugin
+
+Sources are primary only: `shopware/shopware-cli` source (main branch, fetched 2026-10-04),
+`shopware/docs` (the repo behind developer.shopware.com, main), and `shopware/shopware` tags.
+Paths below are relative to those repos. Refs are branch heads or tags as noted; no commit SHAs
+were pinned.
+
+## Summary
+
+- **`extension package --release` does not parse CHANGELOG.md.** It only generates one, from git commits, and only if `changelog.enabled: true` is set in `.config/shopware-extension.yml`. Our pipeline does not pass `--release`.
+- **Parsing happens elsewhere:** in `account producer extension upload` (Store push) and in `extension get-changelog`. The parser treats every line starting with `#` as a version key.
+- **Our Keep-a-Changelog file is not compatible with that parser.** The key becomes `# [0.1.0] - 2026-10-03`, never `0.1.0`, so the Store upload would fail with "english changelog is missing". This only matters if we later use `account producer extension upload`; today we publish to Gitea and a Composer registry.
+- **Minimal fix if we ever upload to the Store:** add `CHANGELOG_en-GB.md` with `# x.y.z` headings and flat bullets, with no `###` sub-headings. Keep `CHANGELOG.md` for humans; the localized file wins for `en-GB`.
+- **PHP:** Shopware 6.6.x requires `~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0` (6.6.0.0 was `~8.2.0 || ~8.3.0`). Our `php: ^8.2` is consistent but broader than core; it is harmless because `shopware/core ~6.6.0` already pins the effective range.
+- **Recommendation:** keep `^8.2` or use `>=8.2`. Do not copy core's tilde list. Shopware's own docs skeleton declares no `php` at all, only `shopware/core`.
+
+## Q1. Changelog handling
+
+### 1.1 What the parser does (verified in source)
+
+File: `internal/extension/changelog.go` (shopware-cli, main).
+
+File discovery and locale:
+
+```go
+files, err := filepath.Glob(path + "/CHANGELOG*.md")
+...
+language := strings.Trim(strings.ReplaceAll(strings.ReplaceAll(filepath.Base(file), "CHANGELOG", ""), ".md", ""), "_")
+if len(language) == 0 { language = "en-GB" }
+```
+
+- `CHANGELOG.md` maps to `en-GB`.
+- `CHANGELOG_en-GB.md` maps to `en-GB`, and `CHANGELOG_de-DE.md` maps to `de-DE`.
+- If both `CHANGELOG.md` and `CHANGELOG_en-GB.md` exist, both land in the same map slot. `filepath.Glob` returns lexically sorted names and `.` sorts before `_`, so `CHANGELOG_en-GB.md` is processed last and overwrites. This ordering is inferred from Go's documented sorted-directory behaviour; I did not run it.
+
+Section splitting (`parseMarkdownChangelog`):
+
+```go
+for _, line := range strings.Split(content, "\n") {
+    if strings.HasPrefix(line, "#") {
+        ...
+        currentVersion = strings.Trim(strings.TrimPrefix(line, "#"), " ")
+```
+
+- Every line that starts with `#`, at any heading depth, starts a new "version" section.
+- The key is the line minus one leading `#`, with spaces trimmed. Only a single `#` is removed.
+- The body is converted to HTML with goldmark via `internal/markdown`. Headings inside bodies are rendered as `<span class="hN">`.
+- Upstream's own tests use this exact shape: `"# 1.0.0\n\n- Test\n- Test2\n# 2.0.0\n- Test3\n- Test4\n"` (`internal/extension/changelog_test.go`).
+
+Version lookup (`parseExtensionMarkdownChangelog`):
+
+- The key looked up is `ext.GetVersion().String()`, which is the plain version from `composer.json`, for example `0.1.0`.
+- `changelogs["en-GB"][version]` must exist, or it returns an error ("english changelog is missing").
+- `de-DE` is optional and falls back to the English file. If a `de-DE` file exists but lacks the version, it errors.
+- The docs agree: "The zip file contains a `CHANGELOG*.md` file with a changelog entry for the new version. Having a German changelog is optional." (`products/tools/cli/shopware-account-commands/releasing-extension-to-shopware-store.md`).
+
+### 1.2 Where it is used
+
+`GetChangelog()` is called in only two non-test places:
+
+- `internal/account-api/producer_store_upload.go`: `account producer extension upload` sends `de_DE` and `en_GB` texts as the Store changelog.
+- `cmd/extension/extension_changelog.go`: `extension get-changelog`.
+
+Not called from `cmd/extension/extension_package.go`, nor from validation: no `changelog` reference was found under `internal/validation`.
+
+### 1.3 What `--release` does
+
+`cmd/extension/extension_package.go`:
+
+```go
+extensionPackageCmd.Flags().BoolVar(&extensionReleaseMode, "release", false, "Prepare a release build: generate the changelog if enabled and, for apps, remove the secret from manifest.xml")
+```
+
+`internal/extension/zip.go`, `PrepareExtensionForRelease`:
+
+```go
+if ext.GetExtensionConfig().Changelog.Enabled {
+    ...
+    changelogFile := fmt.Sprintf("# %s\n%s", v.String(), content)
+    os.WriteFile(path.Join(extensionRoot, "CHANGELOG_en-GB.md"), ...)
+}
+if ext.GetType() == "plugin" { return nil }
+// apps only: remove setup/secret from manifest.xml
+```
+
+- **Added:** a generated `CHANGELOG_en-GB.md`, containing `# <version>` plus one bullet per git commit between the last tag and the current commit (template `internal/changelog/changelog.tpl`). It only happens if `changelog.enabled: true`. The default is false (`internal/changelog/changelog.go`, `Enabled bool`).
+- **Stripped:** the app secret in `manifest.xml`. This does not apply to plugins, which return early.
+- **Not stripped or rewritten:** an existing `CHANGELOG.md` is left untouched. When enabled, the generated file overwrites any existing `CHANGELOG_en-GB.md`.
+- This confirms `# x.y.z` is the format the tool itself writes.
+- Docs on release mode and `changelog.enabled`: `products/tools/cli/extension-commands/build.md`, "Release mode" section.
+
+### 1.4 Our repo
+
+- `.gitea/actions/package/action.yml:29` runs `shopware-cli extension package . --output-directory .build --filename ... --git-commit "$GITHUB_SHA"`. There is no `--release`, and no `changelog:` key was found in `.config` or `.gitea`.
+- The release notes come from our own awk in `.gitea/workflows/release.yml`, which matches `## [x.y.z]`. That is independent of shopware-cli.
+- `CHANGELOG.md` uses `## [0.1.0] - 2026-10-03` and `### Added/Changed/...`.
+
+### 1.5 Compatibility verdict
+
+Walking `CHANGELOG.md` through `parseMarkdownChangelog` by hand (not executed):
+
+- `## [0.1.0] - 2026-10-03` gives key `# [0.1.0] - 2026-10-03`, which never equals `0.1.0`.
+- Each `### Added` and similar heading becomes its own bogus "version", so the entries under it are split off.
+
+Result: **incompatible.** `account producer extension upload` and `extension get-changelog` would fail with "english changelog is missing". `extension package`, with or without `--release`, would not fail, because it does not call the parser. `extension validate` does not parse it either, as far as I could find.
+
+Minimal change, only needed if we adopt Store upload:
+
+```markdown
+# 0.1.0
+
+- Services and routes are now configured in YAML; the plugin requires PHP `^8.2`.
+- Release pipeline: ...
+```
+
+- Put it in `CHANGELOG_en-GB.md` at the plugin root, with one `# <exact composer version>` section per release and flat bullets. Prefix bullets with Added/Changed/Fixed if the categories matter.
+- No `###` sub-headings, and no brackets or dates in the heading.
+- `CHANGELOG_de-DE.md` is optional.
+- The alternative is to enable `changelog.enabled: true` plus `--release` and let the CLI generate it from commits. That would not use our hand-written entries.
+- The packaged zip must contain the file. I did not verify whether `.config/shopware-extension.yml` pack excludes would remove it.
+
+Not verified: the Store's own server-side handling of the changelog HTML. The CLI source only shows what is sent (`de_DE`/`en_GB` text), not what the Store renders. The Store API and backend are not public.
+
+## Q2. PHP constraint
+
+### 2.1 What Shopware 6.6 requires
+
+`require.php` in `shopware/shopware` `src/Core/composer.json` and the root `composer.json`:
+
+| Ref | `require.php` |
+|---|---|
+| `v6.6.0.0` | `"php": "~8.2.0 \|\| ~8.3.0"` |
+| `v6.6.10.28` (latest 6.6 tag seen) | `"php": "~8.2.0 \|\| ~8.3.0 \|\| ~8.4.0 \|\| ~8.5.0"` |
+
+- The `v6.6.10.28` root `composer.json` has the same line as core.
+- A fetch of the `6.6.x` branch-head `composer.json` returned no usable content, so only the two tags above are verified.
+- Official docs, `guides/hosting/index.md` ("Recommended stack and supported versions"): PHP minimum `8.2+`, recommended `8.4`.
+- `guides/development/dev-environment.md`: "PHP Version | `8.2`, `8.3`, `8.4`, `8.5`".
+- Fetching the rendered developer.shopware.com requirements page returned no PHP row. It defers to the hosting guide, which is the source above.
+- The repo's own `CLAUDE.md` says PHP `^8.1`. That is stale for 6.6, since core requires 8.2+. It is outside this task's scope.
+
+### 2.2 Is `php: ^8.2` right?
+
+`composer.json` today:
+
+```json
+"require": { "php": "^8.2", "shopware/core": "~6.6.0" }
+```
+
+- `^8.2` means `>=8.2.0 <9.0.0`. It is consistent with core's floor.
+- It is wider than core's ceiling (`<8.6`). The plugin's PHP range is the intersection of its own constraint and core's. Because `shopware/core ~6.6.0` is also required, Composer resolves to core's tilde list anyway. The plugin constraint adds no extra restriction in practice.
+- Copying core's `~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0` would only make sense if the plugin itself breaks on a specific PHP minor. That would also force a release every time Shopware adds a PHP minor.
+- Practical conclusion: `^8.2` is fine and not too strict. `>=8.2` behaves the same in practice. The only real argument for changing it is wanting the plugin's PHP floor to stay visible in its own metadata, which `^8.2` already does.
+
+### 2.3 What Shopware's skeletons recommend
+
+- `guides/plugins/plugins/creating-plugins.md` (docs repo): the example plugin `composer.json` has only `"require": { "shopware/core": "~6.7.0" }`. There is no `php` key, and "Depending on other plugins" repeats the same shape.
+- shopware-cli's scaffolding (`internal/extension/create.go`) does not set a `php` constraint; the only `"php"` hit in that package is a test fixture, `internal/extension/root_test.go:233`, with `">=8.1"`.
+- So the official guidance is to constrain `shopware/core` and leave PHP to core. A plugin `php` constraint is optional. If you want one, mirroring the supported floor (`>=8.2` or `^8.2`) is reasonable.
+- I did not find a `SwagPluginSkeleton` repo (fetching `shopware/SwagPluginSkeleton` returned 404).
+
+## Could not verify
+
+- That the Store's server-side processing matches what the CLI sends. The Store backend is not public.
+- That `.config/shopware-extension.yml` pack excludes would keep or remove a `CHANGELOG_en-GB.md` in the zip.
+- The exact ordering behaviour of `filepath.Glob` for the two `en-GB` files was inferred from Go's documented sorted results, not run.
+- No source evidence of whether the Store accepts HTML headings; the CLI renders headings as `<span class="hN">` per a comment in `internal/markdown`.