Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

docs: add release-note skill (#1527)

Viktor Holik0f61fd87bf35
diff --git a/.claude/skills/release-note/SKILL.md b/.claude/skills/release-note/SKILL.md
new file mode 100644
index 000000000..408e9e8d4
--- /dev/null
+++ b/.claude/skills/release-note/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: release-note
+description: Write the GitHub release note for a stable Mercur release from the auto-generated changelog and the merged PRs. Use when the user asks to "write / create / polish the release note" for a `vX.Y.Z` tag, pastes the auto-generated "What's Changed" list, or wants a release note in Mercur's voice.
+argument-hint: "[vX.Y.Z]"
+---
+
+# release-note — Mercur GitHub release notes
+
+Turn a release's merged PRs into a curated, human-readable note in Mercur's own voice. The reference is our v2.3.0 note and [`references/example-v2.3.4.md`](references/example-v2.3.4.md). Other projects' notes (e.g. Vendure) are inspiration for *structure* only — never copy their tone, section names, or length 1:1.
+
+Use this skill when:
+- a stable tag (`vX.Y.Z`) was pushed and the auto-generated note needs replacing
+- the user pastes the "What's Changed" list and asks for a proper note
+
+## Workflow
+
+1. **Collect the PR list.** Use what the user pasted, or:
+ ```bash
+ gh release view vX.Y.Z --json body -q .body
+ ```
+ The range is the previous **stable** tag → this tag (`vX.Y.(Z-1)...vX.Y.Z`), not the last canary. The GitHub "View changes" link from changelogithub points at the last canary and is wrong for this purpose.
+2. **Filter.** Drop:
+ - every `chore: vX.Y.Z-canary.N` / `-rc.N` / `chore: vX.Y.Z` version bump
+ - change + revert pairs that net to zero (e.g. a pin and its rollback)
+ - a feature, its revert, and its re-land collapse into **one** entry citing the re-land PR
+3. **Read the substantive PRs** — titles are not enough to explain impact:
+ ```bash
+ gh pr view <n> --json body -q .body
+ ```
+ Always read `!` (breaking) PRs, `feat` PRs, and anything touching migrations, config (`withMercur`, feature flags) or Medusa versions.
+4. **Draft** into the scratchpad as `release-notes-vX.Y.Z.md` using the format below, then send it to the user for review.
+5. **Publish only after the user approves:**
+ ```bash
+ gh release edit vX.Y.Z --notes-file <path>
+ ```
+
+## Format
+
+```markdown
+# Mercur vX.Y.Z
+
+<2–4 sentence intro: the theme of the release, the headline features, the Medusa bump if any, "plus a batch of fixes">
+
+## ⚠️ Before you upgrade
+<only if needed: breaking changes (from `!` PRs), migrations to run, config/flag changes. Short bullets with PR refs.>
+
+## ✨ Highlights
+
+### <emoji> <Feature name>
+<2–4 sentences: what it enables for an operator/vendor/developer, the hook/API name in backticks, what happens if you don't opt in. (#PR)>
+
+### 🧩 More extension points
+- <smaller additive seams, one line each (#PR)>
+
+### Platform
+- **Bump Medusa to X.Y.Z** (#PR).
+
+## 🐛 Fixes
+- <imperative, one line, user-visible effect (#PR)>
+
+## 📚 Docs
+- <docs PRs (#PR)>
+
+## 🙌 New contributors
+- @handle made their first contribution in #PR — thank you!
+
+**Full Changelog**: https://github.com/mercurjs/mercur/compare/vPREV...vX.Y.Z
+```
+
+## Rules
+
+- **Voice:** friendly, concise, product-first ("sellers can now…", "lets a plugin…"). Not a security advisory, no tables, no exhaustive per-file detail.
+- **Group by impact, not by package.** Features go in Highlights; small additive hooks go under "More extension points"; everything else is a Fix.
+- Every bullet cites its PR as `(#1234)`. Omit sections that would be empty.
+- Breaking changes must name the removed endpoints/fields/links concretely so users can grep for them.
+- Mention migrations whenever a PR adds columns or a `Migration*` file.
+- Don't invent behaviour — if a PR body doesn't say it, don't claim it.
+- No AI attribution in the note.
diff --git a/.claude/skills/release-note/references/example-v2.3.4.md b/.claude/skills/release-note/references/example-v2.3.4.md
new file mode 100644
index 000000000..f808a4b24
--- /dev/null
+++ b/.claude/skills/release-note/references/example-v2.3.4.md
@@ -0,0 +1,69 @@
+# Mercur v2.3.4
+
+This release is all about extensibility. Commissions get pluggable providers,
+split orders and product edits get new workflow hooks, and offers learn about
+handling time. Shipping profiles become operator-owned, RBAC is now fully
+opt-in, and we bumped Medusa to 2.20.1 — plus a batch of fixes across offers,
+the panels and the client.
+
+## ⚠️ Before you upgrade
+
+- **Shipping profiles are now operator-owned** (#1498). Only the marketplace
+ operator defines shipping profiles; vendors can still read and select them.
+ `POST` / `DELETE` on `/vendor/shipping-profiles` are removed, along with the
+ `seller_id` filter on `GET /admin/shipping-profiles` and the
+ `shipping-profile-seller-link`.
+- **Run migrations** — new columns on offers, sellers and commission lines.
+- **RBAC is opt-in** (#1521). If you use seller roles and permissions, enable
+ it with `withMercur({ featureFlags: { rbac: true } })`.
+
+## ✨ Highlights
+
+### 💸 Commission providers
+The commission module now has a provider seam, just like payouts. Implement
+`ICommissionProvider` to plug in your own commission logic, and pass extra
+context through the new `setCommissionContext` hook. The existing calculation
+ships as the default `system` provider, so nothing changes unless you
+configure one. (#1509)
+
+### 📦 Order acceptance flows
+A new `setOrderStatus` hook on `completeCartWithSplitOrdersWorkflow` lets a
+plugin set each seller order's initial status — for example `requires_action`
+for marketplaces where sellers accept orders first. Both panels now lock
+fulfil, edit, return, exchange, claim, capture and refund on those orders, and
+order tables get a status filter. (#1513)
+
+### 🚚 Handling time on offers
+Offers accept `leadtime_to_ship` — business days until the parcel is handed to
+the carrier — falling back to the seller's `default_leadtime_to_ship`
+(default `2`). The building block for shipping deadlines and delivery
+estimates. (#1491)
+
+### 🧩 More extension points
+- `validate` hook on the vendor product-edit workflows (#1484).
+- `value_ids` accepted on product attribute batch update (#1481).
+- `ClientError` keeps the API error `code`, so your storefront can react to a
+ specific refusal instead of matching on the message (#1477).
+
+### Platform
+- **Bump Medusa to 2.20.1** (#1489).
+
+## 🐛 Fixes
+- Reject offer prices of `0` or less, and skip unpriced variants in the vendor
+ Create offers form (#1522).
+- Accept a decimal comma in offer price fields (#1520).
+- Stop marking unhandled product-change actions as applied (#1463).
+- Tolerate dangling price links in `updateOffersWorkflow` (#1482).
+- Merge plugin i18n into the panels and keep parent breadcrumbs on file-based
+ routes (#1511).
+- Use valid BCP 47 tags for Chinese and Portuguese (#1519).
+- Stub `virtual:medusa/search-entities` in the dashboard SDK (#1495).
+- Avoid a 4-level field expansion when the storefront retrieves the cart (#1518).
+
+## 📚 Docs
+- Clarify the Stripe webhook events needed for split-order checkout (#1523).
+
+## 🙌 New contributors
+- @skaffff made their first contribution in #1477 — thank you!
+
+**Full Changelog**: https://github.com/mercurjs/mercur/compare/v2.3.3...v2.3.4