Changelog
Guppy and all Guppy plugins strictly follow Semantic Versioning. This page describes the versioning rules, the update workflow, and where to find official release notes.
SemVer scheme
MAJOR.MINOR.PATCHMAJOR: Breaking changes
Incompatible changes requiring manual adjustments:
- Template blocks removed or renamed
- Configuration options removed
- CSS classes fundamentally changed
- JavaScript plugin APIs changed
Example: 2.6.1 → 3.0.0 (MINOR and PATCH reset to 0).
MINOR: New features
Backwards-compatible functionality:
- New template blocks or properties
- New configuration options
- Additional CSS classes
- New JavaScript plugin features
Example: 2.1.3 → 2.2.0 (PATCH reset to 0).
PATCH: Bug fixes
Backwards-compatible fixes:
- Styling corrections
- Performance optimisations
- Non-functional improvements
Example: 2.1.1 → 2.1.2.
Release notes per plugin
Because Guppy spans multiple plugins, the changelog lives per plugin as a CHANGELOG.md in its GitLab repository. The changelog section aggregates those files nightly, one page per plugin. Format and rules: CHANGELOG-CONVENTION.md in the docs repository.
A plugin without a CHANGELOG.md, or with a file that carries no entries, does not appear in the aggregation. The sync run reports it as a warning so it gets fixed in the repository.
Shopware update workflow
1. Read Shopware UPGRADE.md
Shopware publishes an UPGRADE.md with breaking changes per release:
curl -s https://raw.githubusercontent.com/shopware/platform/trunk/UPGRADE.md2. Read Guppy's release notes
Read the Guppy changelog for every version between yours and the target. Entries marked Visual change with default config change the look of a shop that uses the default theme configuration, and each says how to keep the old look. UPGRADE-3.0.md in the theme repository lists everything that changes or goes away in 3.0.0 (see Preparing for Guppy 3.0).
The former scanner guppy:upgrade:scan was removed in 2.7.0.
3. Run the update
composer update dmf/sw6-guppy-theme
bin/console plugin:refresh
bin/console plugin:update DmfGuppyTheme
bin/console theme:compile
bin/console cache:cleartheme:compile required
After a plugin update, run theme:compile, otherwise neither new SCSS values nor Twig changes take effect.
Preparing for Guppy 3.0
Guppy 3.0.0 switches to Shopware 6.8, removes what 2.x deprecated and changes defaults that change the look. Every 2.x minor that announces such a change adds it to UPGRADE-3.0.md in the theme repository, with what changes, why, who is affected and how to adapt. Announced so far (2.9.0):
| Change | What to do now |
|---|---|
Skip link fields guppy-header-skip-to-main-content, -main-nav, -search default to true | Nothing, if you want skip links. To keep them off, store false for the three fields: the theme manager only saves changed values, so switch each on, save, switch it off and save again. |
Theme field guppy-login-register and the tab Login & Register are removed, a migration removes the stored value | Remove theme_config('guppy-login-register') from child theme templates and the field from a child theme's theme.json. The field has no effect since 2.7.0. |
21 unused storefront snippet keys are removed: breadcrumb.backLabel, listing.showDetails, footer.languages.ariaLabel and 18 keys under component.checkout.{cart,progress,register,quantity,products}.* | A child theme or plugin that renders one of them with |trans defines the text under its own key. The full list is in UPGRADE-3.0.md, section "Removals". checkout.summaryNetPrice and component.checkout.cart.discountApply stay. |
Deprecated code carries @deprecated tag:v3.0.0; deprecated theme.json fields say so in their label or help text.
Branching as a source of updates
| Branch / tag | When to use |
|---|---|
Tagged version (e.g. v2.6.0) | production |
RC tag (e.g. v2.8.0-rc1) | testing upcoming Shopware major versions |
main | intentional "latest stable without tag", rarely in production |
stage | testing environments only |
Details: Contributing.
Hotfixes
Outside of regular releases, critical bug fixes ship as PATCHes. Workflow details: Contributing → Hotfixes.
Related
- Contributing: branch strategy and workflow.
- Architecture: console commands.