Skip to content

Prepare the first (alpha) release: docs, screenshots, release zip - #235

Merged
Sebastian Hölscher (HoelShare) merged 4 commits into
mainfrom
claude/alpha-release-prep-6388fd
Oct 9, 2026
Merged

Prepare the first (alpha) release: docs, screenshots, release zip#235
Sebastian Hölscher (HoelShare) merged 4 commits into
mainfrom
claude/alpha-release-prep-6388fd

Conversation

@HoelShare

@HoelShare Sebastian Hölscher (HoelShare) commented Oct 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What this does

Gets the repo ready for the first GitHub release, v0.1.0 (alpha).

Release zip (plugin-zip.yml)

  • Publishing a GitHub release builds the zip, stamps it with the tag's version and attaches it as MerchantQuoteAgentPlugin.zip. The upload runs in a separate job, the only one with contents: write.
  • Tags must be plain MAJOR.MINOR.PATCH, and the workflow fails on anything else:
    • With -alpha1, a bare composer require fails on minimum-stability: stable shops.
    • With -alpha.1, Shopware shortens the version to -alpha, so the admin upload's own composer require matches nothing.
  • Main builds become <latest tag's major.minor>.<run>+<sha> (0.0.<run> until the first tag), so they stay above the release they follow.

Docs

  • Every guide was checked claim by claim against src/:
    • README
    • for-merchants
    • end-to-end
    • development
    • ADR 0001
    • AGENTS.md
    • evals-design
    • the 2026-08-25 design doc, which now has a "historical" note at the top
  • The settings path was wrong everywhere. It's Extensions → My extensions → Quote Agent → Configure.
  • Agentic Commerce: 1.3 and 1.4 are released. The docs now say 1.3 or newer, because 1.2 crashes the shop next to this plugin.
  • README: alpha notice and an install step linking to /releases/latest. The Actions artifact is kept as the way to get an unreleased main build.
  • New: which AI providers work (Chat Completions + structured outputs) and configuration from the environment: MQA_LLM_API_KEY, plus Shopware's static system config with %env()%, checked on the local shop.
  • Written for a first install: upgrade notes for earlier versions are removed (e.g. "Custom strategy"). Workers are described as something most shops already run; the admin worker alone is not enough. The guides also say when a developer has to install the plugin.
  • Install step removed: rm -f config/packages/ai_generic_platform.yaml is gone from the README, end-to-end §9 and the workflow summary. It guarded against the Generic bridge's Flex recipe, and the plugin dropped that dependency in ffb2d9c (it's not in composer.lock).
  • 8 setup screenshots in docs/images/ from the local test shop. Example values were typed in and never saved, the API key field is empty, and docs/ is not in the zip.

config.xml: help text only. Draft Mode names the current menu label; the base URL help names the OpenRouter and Azure addresses.

After merge: creating the release

  1. Tag v0.1.0 and title it "0.1.0 (alpha)".
  2. Leave "Set as a pre-release" unticked. /releases/latest, which the README links to, skips pre-releases.
  3. Publish. The zip attaches itself about 5 minutes later.

Test shops on a 1.0.x main build must reinstall: Shopware sees 0.1.0 as older.

Not in this PR (found during the audit)

  • 2.9 LLM transport failures can log the base URL's query string (API key); llmBaseUrl is not validated #62: a base URL that carries the API key can end up in logs. Worth fixing before the release is widely used.
  • quote.spec.html tells agents to read config.endpoint from the capability descriptor, which the code never publishes. It also promises 501 where the route is simply absent (404).
  • tests/Unit/ReleaseCapabilityMatrixTest.php:25 hardcodes a personal path, so that test always skips for others.
  • Unverified provider claims: Azure /openai/v1 with structured outputs. OpenRouter is the only provider used on the test shops.

Test plan

  • composer run quality passes
  • composer run test: 1923 tests pass
  • Version logic dry-run: v0.1.0 and 0.1.0 are accepted, -alpha1 and -alpha.1 are rejected, and a main build without a tag becomes 0.0.<run>
  • %env()% in shopware.system_config resolves on the local 6.7.13 shop (probe key, removed afterwards)
  • Plugin Zip run on this merge still succeeds
  • First release run attaches MerchantQuoteAgentPlugin.zip

🤖 Generated with Claude Code

@HoelShare @claude
ci: attach the plugin zip to every published GitHub release
5030adf 
The Plugin Zip workflow now also runs on `release: published`. A release
build is stamped with the tag's version (`v0.1.0` -> `0.1.0`) and a
separate job, the only one holding `contents: write`, attaches it to the
release as MerchantQuoteAgentPlugin.zip, the file the README links to.

The tag must be plain MAJOR.MINOR.PATCH and the workflow refuses anything
else: a shop's `minimum-stability: stable` cannot resolve `0.1.0-alpha1`
with a bare `composer require`, and Shopware's VersionSanitizer turns
`0.1.0-alpha.1` into `0.1.0-alpha`, so the admin upload's own require
matches nothing.

Builds of main move from `1.0.<run>+<sha>` to `<latest tag's
major.minor>.<run>+<sha>` (`0.0.<run>` until the first tag), so a main
build sorts above the release it follows and below the next one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@HoelShare @claude
docs: bring the guides in line with the code for the first release
8397c12 
Every guide was checked claim by claim against src/ before the first
(alpha) release. The notable corrections:

- The settings live under Extensions -> My extensions -> Quote Agent ->
  Configure. "Settings -> Extensions -> Merchant Quote Agent" never
  existed, and the extension is listed as "Quote Agent".
- Agentic Commerce 1.3 and 1.4 are released. The SDK floor (>=0.0.6)
  pairs this plugin with AC 1.3 or newer; 1.2 fails the container build.
- The quote value ceiling is one admin number in the quote's currency,
  not one per currency; volume asks are answered, not escalated; the
  editor role beside viewer and deleter; the strategy assignment ladder; the seeded
  escalation flow; the export and forget commands.
- Install now downloads MerchantQuoteAgentPlugin.zip from the latest
  GitHub release. The README carries an alpha notice that links there.

New: which AI providers work (Chat Completions with structured outputs;
Claude and Gemini through OpenRouter, Azure only via /openai/v1), and
configuration from the environment (MQA_LLM_API_KEY, plus Shopware's
static system config with %env()% for the base URL and model, verified
on the local shop).

Setup screenshots in docs/images/, taken from the local test shop with
example values typed in and never saved. docs/ is excluded from the zip.

config.xml: Draft Mode's help text names the menu entry as it is now
labelled (Orders > Quote Agent Dashboard), and the base URL help names
the OpenRouter and Azure addresses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@HoelShare @claude
docs: write the guides for a first install, drop the obsolete rm step
9af8abe 
First release, so nobody upgrades from anything: the "Custom strategy"
migration note, the "after this measure shipped" caveat, the per-line
original-prices exception and the "same key as before" note are gone.

Workers are framed as what most production shops already run, with the
one real trap named: the admin worker only runs while the Administration
is open.

The install docs now say why a developer may be needed: the zip carries
no libraries, so the upload runs Composer in the web request, which a
host may forbid, and in a repository-deployed shop the next deployment
removes an upload.

The `rm -f config/packages/ai_generic_platform.yaml` step is removed from
the README, end-to-end §9 and the workflow summary. It guarded against the
Generic bridge's Flex recipe, and the plugin has not depended on that
bridge since ffb2d9c; composer.lock no longer contains it.

The dashboard list opens on "Needs review"; the record section and the
"agent seems to do nothing" checklist now say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@HoelShare @claude
docs: state what the plugin does, not what it avoids or what you want
f31dbfa 
- end-to-end §9: drop the paragraph about a dependency the plugin does
  not use. Nobody reading it knew that dependency existed.
- for-merchants: no "most shops will not want it" or "probably not".
  The Agentic Commerce section now says what the extension adds and
  leaves the decision to the merchant.
- end-to-end §1: the class_exists() pitfall is described as a pitfall,
  not as history.
- The plugin class docblock loses the matching Flex sentence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@HoelShare
Sebastian Hölscher (HoelShare) merged commit ab6d8f1 into main Oct 9, 2026
1 check passed
@HoelShare
Sebastian Hölscher (HoelShare) deleted the claude/alpha-release-prep-6388fd branch October 9, 2026 11:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@HoelShare