Document Marketplace ratings and reviews, and campaign sharing to the Marketplace

[promptless-for-oss]

Open in Promptless

Documents the user-facing Marketplace changes introduced in mautic/mautic PR #15904 ("New Marketplace API, review, rating (public-marketplace)"), merged to 7.x. Targets the 7.2 docs branch.

Changes

docs/marketplace/marketplace.rst

• New "Ratings and reviews" section (top-level):
  • Viewing ratings: the list view shows each Plugin's community rating (a number, not star icons) and total review count; the Plugin detail page shows a Reviews panel of individual reviews, each with a 1 to 5 star rating, the review text, and the reviewer's username.
  • Submitting a review: Rate & Review is a standalone primary button (star icon) on the Plugin detail page — not a context-menu item. It opens that Plugin's own page on the public Mautic Marketplace website (marketplace.mautic.org) in a new browser tab, where the user signs in and leaves the review. Reviews are managed on the public site, not within the instance.
  • Adds a caution that community ratings/reviews reflect other users' opinions, not a Mautic-verified check of version compatibility or security.

docs/campaigns/exporting_campaigns.rst

• Corrects the "Using Mautic instance" export step: the Export action (reachable from the Campaign detail page and the Campaign list row) now opens a Share form instead of downloading the ZIP directly. The form offers Download ZIP (a local export ZIP, now including a package manifest and any images added in the form) and Publish to Marketplace (shares the Campaign to the public Mautic Marketplace as a resource package). Publishing requires five fields — Name, Vendor Name, Package Version, Headline, and Description — with constraints (Description ≥ 100 characters, Headline ≤ 60 characters, Vendor Name lowercase alphanumeric/hyphens with mautic reserved, Package Version a valid semantic version). Optional fields: Keywords, Works with (at least one Mautic version required to publish), and Languages, plus a Banner Image and an image gallery with per-image alt text.

docs/links/marketplace_mautic_org.py

• New xref registry entry for the Mautic Marketplace website.

Review feedback applied (@vukovicpredrag, verified against mautic/mautic 7.x)

Two reviews on this PR were folded in. Disposition per item:

Review 1 — Rate & Review:

• ✅ Applied — "Rate & Review" is a primary button, not a context-menu item. Removed the Rate & Review bullet from the "Context menu" list and rewrote "Submitting a review" to describe a standalone star-icon button on the Plugin detail page. (Confirmed: 'primary': true in Package/detail.html.twig.)
• ✅ Applied — it's not a redirect to the site root. Corrected to "opens that Plugin's own page … in a new browser tab" (target="_blank", URL /package/{vendor}/{name}).
• ✅ No change needed — there is no marketplace-api.mautic.org; the docs only ever referenced marketplace.mautic.org via the xref, which is already correct. (Confirmed: MARKETPLACE_WEBSITE_URL and MARKETPLACE_REGISTRY_URL both https://marketplace.mautic.org.)

Review 2 — Campaign Share form:

• ✅ Applied — five required fields, not four. Added Headline and corrected the labels to the ones users see: Name, Vendor Name, Package Version (CampaignShareType NotBlank on title/vendorName/version/headline/description).
• ✅ Applied — Description has a 100-character minimum; Headline capped at 60. Added the Keywords, Works with, and Languages fields, plus the Banner Image and gallery with per-image alt text.
• ⚠️ Applied with deviation — the image gallery is described without a maximum count, rather than stating "up to 5". The in-product help text says "up to 5" but the form/template code builds 8 gallery slots with no max constraint (CampaignShareType loop 1..8; share_form.twig {% for i in 1..8 %}). Given that code/help-text mismatch, the docs avoid committing to a number. Flagging for maintainers to reconcile the help text with the code.

Notes

• The publish/share flow depends on the public marketplace backend (marketplace.mautic.org), which may not be fully live yet, so the docs describe the Mautic UI behavior and keep Publish coverage brief.

Generated by Promptless.

[promptless-for-oss]

Verified on mautic/mautic 7.x (commit 504af18c): the "Rate & Review" button on the Plugin detail page (id 'ratePackage') is defined with 'primary': true, class 'btn btn-primary btn-nospin', icon 'ri-star-line', href = marketplaceWebsiteUrl ~ '/package/' ~ vendor ~ '/' ~ package, and target='_blank'. ButtonHelper::orderButtons() (CoreBundle/Twig/Helper/ButtonHelper.php) sorts primary=true buttons to the front (priority 215) and outside the Options dropdown (listMarker), confirming it renders as a standalone primary button, not a dropdown/context-menu item. Label 'mautic.marketplace.rate.package' = "Rate & Review" (MarketplaceBundle/Translations/en_US/messages.ini). Context menu (Close/Install/Issue tracker) correctly has no Rate & Review bullet.

Source: https://github.com/mautic/mautic/blob/504af18cf90d8fbe701fde55cb1a94603db9e21a/app/bundles/MarketplaceBundle/Resources/views/Package/detail.html.twig#L46-L58

[vukovicpredrag]

Checked against 7.x - the class changes are right (RateController and Auth0 gone, Review DTO and ReviewCollection present). Three fixes:

• Not in the context menu. It's 'primary': true in Package/detail.html.twig, and primary buttons render standalone on the detail page, not in the dropdown. The "Context menu" bullet needs the same fix.
• Not a redirect. target="_blank", and it points at the package's own page — /package/{vendor}/{name} — not the site root the xref resolves to.
• No marketplace-api.mautic.org. Config/config.php sets both MARKETPLACE_WEBSITE_URL and MARKETPLACE_REGISTRY_URL to https://marketplace.mautic.org.

[promptless-for-oss]

Verified on mautic/mautic 7.x (commit 504af18c), CampaignBundle/Form/Type/CampaignShareType.php: five NotBlank fields - title (label 'mautic.campaign.share.title'="Name"), vendorName (label "Vendor Name", Regex '^(?!mautic$)a-z0-9?$'), version (label "Package Version", semver Regex, default data '1.0.0'), headline (label "Headline", Length max:60), description (label "Description", Length min:100). Labels confirmed in CampaignBundle/Translations/en_US/messages.ini lines 257-269. Optional fields: keywords (required:false), worksWithVersions (ChoiceType, required:false, but Count(min:1) constraint applies only in validation group 'publish' - i.e. required only when clicking Publish), languages (required:false). Images: bannerImage plus galleryImage1..8/galleryAlt1..8 (8 gallery slots in code; doc correctly avoids stating a specific max count since in-product help text says "up to 5" while code allows 8 - a known product mismatch).

Source: https://github.com/mautic/mautic/blob/504af18cf90d8fbe701fde55cb1a94603db9e21a/app/bundles/CampaignBundle/Form/Type/CampaignShareType.php#L62-L229

[vukovicpredrag]

Routing and ZIP details check out. Two corrections:

• headline is also required - CampaignShareType has NotBlank on title, vendorName, version, headline and description. Five, not four.
• The UI labels differ from the field names: users see "Name", "Vendor Name" and "Package Version".

Worth adding: description has a 100 character minimum, and the form also has Keywords, Works with and Languages. Images is a Banner Image plus a Gallery of up to 5, each with ALT text.

[adiati98]

@promptless-for-oss please address the Vale warnings.

[promptless-for-oss]

Thanks, @adiati98 — on it. We'll run Vale on the changed files and fix the flagged warnings, then follow up here once pushed.

[promptless-for-oss]

Update: we ran Vale on both changed files and are reworking the flagged lines — converting the passive "Reviews are managed…" sentence to active voice and rewording the false-positive term hits (e.g. "page", "form", "Publish" where they aren't the Mautic feature) without changing any documented behavior. We'll push shortly.

[promptless-for-oss]

Thanks, @adiati98 — the Vale warnings on the changed lines are addressed and pushed to this PR.

• Rewrote the passive "Reviews are managed…" note in active voice.
• Reworded the phrases Vale was flagging as Mautic feature names (in "other users' opinions", "Plugin detail page", and "publishing") so they read naturally without tripping the feature-name rule. No documented behavior changed.

Two Vale suggestions (non-failing) intentionally remain, and I want to flag them rather than silently suppress them:

• "form" — this is the generic Share form, not the Mautic Form feature.
• Publish — a real button label, not the activate/turn-on concept.

Per the style guide those substitutions apply only to the actual features, so keeping the accurate UI terms is correct here. If you'd rather have them silenced, the repo's convention would be a block-level .. vale off/.. vale on wrapper — happy to add that if you prefer. Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks, @adiati98 — on it. We'll investigate the mautic/mautic source behind the Share form to confirm the correct term for the flagged line (docs/campaigns/exporting_campaigns.rst:58), fix the Vale warning accordingly, and address the other review suggestions. We'll follow up here once the fixes are pushed.

[promptless-for-oss]

Update: we confirmed against the mautic/mautic source (PR #15904) that the Share form's submit button is literally labeled Publish to Marketplace, so Publish is the accurate term for the flagged line. The Vale finding is a false positive — the rule maps the activate/deactivate sense of "publish" to Active/Turn On, which doesn't apply to a button named Publish to Marketplace. We're finalizing the fix on the branch and will follow up once pushed.

[promptless-for-oss]

Thanks for the review, @adiati98. We confirmed the button labels against the Mautic 7.x source (PR #15904): the Campaign Share form's actions are Publish to Marketplace and Download ZIP, so we've updated the page to use the exact Publish to Marketplace label rather than the bare word "Publish". Because that label is the button's own name (not the entity-activation sense the linter checks for), we fenced those two action bullets with the docs' standard .. vale off / .. vale on markers, which clears the Vale warning you flagged on line 58. The fix is pushed to this PR (commit 5d66c263). Ready for another look.

[promptless-for-oss]

Thanks for the detailed review, @vukovicpredrag — verifying the three corrections (standalone primary button vs. context menu, the target="_blank" link to the package page rather than a redirect to the site root, and the single marketplace.mautic.org URL) against the 7.x source now and updating the docs on this branch.

[promptless-for-oss]

Thanks, @vukovicpredrag — folding in the second batch too: the fifth required field (headline), the UI label names (Name, Vendor Name, Package Version), the 100-character description minimum, and the additional form fields (Keywords, Works with, Languages, Banner Image plus a Gallery of up to 5 images with ALT text). All corrections are going onto this branch.

[promptless-for-oss]

Verified both reviews against the 7.x source and all corrections check out — Rate & Review is a standalone primary button (not a context-menu item) that opens the package's own page in a new tab, and the Share form has five required fields (Name, Vendor Name, Package Version, Headline, Description) plus the Keywords / Works with / Languages / image-gallery details. Applying the edits to this branch now.

One thing surfaced along the way: the gallery is described as "up to 5" in the reviewer note and in-product help text, but the 7.x form/template code builds 8 slots with no max constraint — a code/help-text mismatch in the product itself. We'll document the user-facing behavior conservatively; flagging it in case it's worth a product-side look.

[vukovicpredrag]

Left two review comments with corrections against the 7.x source. @promptless-for-oss those need a push before this lands in 7.2.

[promptless-for-oss]

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.

[promptless-for-oss]

Pushed (SHA 3beed786). Both of your reviews are applied, verified against the 7.x source:

Rate & Review (docs/marketplace/marketplace.rst): removed from the Context menu list; Submitting a review now describes it as a standalone star-icon button on the Plugin detail page that opens the Plugin's own page on marketplace.mautic.org in a new browser tab (not a redirect to the site root). The docs never referenced marketplace-api.mautic.org, so no edit was needed there.

Publish to Marketplace (docs/campaigns/exporting_campaigns.rst): now lists five required fields (Name, Vendor Name, Package Version, Headline, Description, with the 100-character description minimum), plus optional Keywords, Works with, Languages, a Banner Image, and the image gallery with ALT text. A per-item disposition is in the PR description.

One note on the red build check: it's not from this branch. It fails at the checklinks step on pre-existing parse errors in files this PR doesn't touch (campaign_builder.rst:97, importing_campaigns.rst:94) and a couple of unreachable external links; the one link this branch adds (semver.org) resolves fine and exporting_campaigns.rst parses cleanly. Flagging in case it's worth a separate fix, but it isn't blocking on the content here.