# 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`.