Updates & Migration

The Guppy Theme follows a structured update process to ensure compatibility with Shopware updates while enabling continuous improvements.

Contents of this page:

• Versioning Strategy
  • Semantic Versioning (SemVer)
• Git Branch Strategy
  • Branch Overview
  • Development Workflow
  • Testing Environments
  • Best Practices
  • Workflow Diagram
  • Checklist: Feature Release
• Update Process
  • Shopware Update Workflow
• Support
  • Update Help
  • AI Support

Versioning Strategy

Semantic Versioning (SemVer)

The Guppy Theme and all Guppy plugins strictly follow Semantic Versioning:

MAJOR.MINOR.PATCH

MAJOR (Breaking Changes)

Incompatible changes that require manual adjustments:

• Template blocks removed or renamed
• Configuration options removed
• CSS classes fundamentally changed
• JavaScript plugin APIs changed

Example: 2.0.0 → 3.0.0

MINOR (New Features)

Backward-compatible functionalities:

• New template blocks or properties
• New configuration options
• Additional CSS classes
• New JavaScript plugin features

Example: 2.1.0 → 2.2.0

PATCH (Bugfixes)

Backward-compatible bug fixes:

• Styling corrections
• Performance optimizations
• Documentation updates
• Non-functional improvements

Example: 2.1.1 → 2.1.2

---

Git Branch Strategy

Branch Overview

main        ← Current stable version for production
  ↑
stage       ← Testing branch for playground
  ↑
next        ← Development for next Shopware major version

main

• Purpose: Production-ready, stable version
• Releases: All MAJOR, MINOR and PATCH releases
• Testing: Fully tested and approved
• Shopware Compatibility: Current Shopware LTS version

stage

• Purpose: Staging and testing new features
• Environment: Guppy Playground
• Testing: Beta features and release candidates
• Feedback: Community testing and feedback collection

next

• Purpose: Preparation for next Shopware major version
• Development: Adaptations for upcoming Shopware updates
• Timeline: Development begins before Shopware release
• Migration: Breaking changes are prepared here

---

Development Workflow

The following workflow describes the practical development process from feature development to release.

Feature Development Step-by-Step

1. Create Feature Branch (from main)

git checkout main
git pull
git checkout -b TICKET-123_feature-name

Naming Convention: TICKET-123_description (Jira ticket + short description)

2. Development & Commits

git add .
git commit -m "GUPPY-123: Add product slider component"
git push origin GUPPY-123_product-slider-component

3. Merge to stage for Testing

git checkout stage
git pull
git merge GUPPY-123_product-slider-component
git push

TIP

Multiple features can be tested in stage in parallel.

4. Trigger Playground Pipeline

• Open guppy-playground project in GitLab
• CI/CD → Pipelines → Run Pipeline
• Pipeline automatically pulls dev-stage branches

5. QA Testing in Jira

• Set ticket status to "Testing"
• Assign to QA person
• Testing: Functionality, Cross-Browser, Mobile, Accessibility
• If issues: Back to step 2
• If successful: QA approval

6. Merge Feature Branch to main

git checkout main
git pull
git merge GUPPY-123_product-slider-component  # Feature branch, not stage!
git push

Why Feature Branch?

For clean Git history, the feature branch is merged directly into main, not stage.

7. Tag Version

git tag v2.6.0  # See Semantic Versioning above
git push --tags

8. Update Projects

• Express-Demo: composer update dmf/sw6-guppy-theme
• Customer Projects: After coordination with project manager

---

Testing Environments

Environment	Branch/Version	Purpose	Update
Guppy Playground	dev-stage	QA & Feature Testing	Pipeline Trigger
Express-Demo	Tagged releases	Showcase	After Release
Customer Projects	Specific tags	Production	Project Plan

---

Best Practices

Update Stage Branch

Regularly (every few months) merge main into stage:

git checkout stage
git merge main
git push

Parallel Feature Development

# Developer A
git checkout -b GUPPY-100_feature-a

# Developer B
git checkout -b GUPPY-101_feature-b

Both features are tested independently and merged separately to main after QA approval.

Hotfixes

For critical bugfixes:

1. Branch from main: HOTFIX-123_critical-bug
2. Develop fix
3. Merge directly to main (skip stage)
4. Tag PATCH version (e.g., 2.5.8)
5. Deploy immediately
6. Update stage and next

WARNING

Hotfixes should be the exception. When possible, use the normal workflow through stage.

---

Workflow Diagram

Feature Branch (from main)
         ↓
  Development
         ↓
  Merge → stage
         ↓
  Playground Pipeline
         ↓
  QA Testing ──→ Issues? ──→ Back to Development
         ↓
    QA Approval
         ↓
  Merge Feature Branch → main
         ↓
  Tag Version
         ↓
  Update Projects

---

Checklist: Feature Release

• [ ] Feature branch created from main
• [ ] Feature developed and tested locally
• [ ] Feature branch merged to stage
• [ ] Playground pipeline triggered
• [ ] Jira ticket assigned to QA person
• [ ] QA testing successful
• [ ] Feature branch merged to main
• [ ] Version tag created
• [ ] Express-Demo updated
• [ ] Customer projects informed (if needed)

---

Update Process

Shopware Update Workflow

1. Analyze Shopware UPGRADE.md

Shopware provides an UPGRADE.md with each release that documents breaking changes and important modifications.

# Analyze current Shopware UPGRADE.md
curl -s https://raw.githubusercontent.com/shopware/platform/trunk/UPGRADE.md

2. Automated Compatibility Check

The Guppy Theme offers a built-in scanner for update compatibility:

# Check plugins for updates
bin/console guppy:upgrade:scan

# Detailed analysis with Shopware version
bin/console guppy:upgrade:scan --shopware-version=6.5.0

Scanner Features:

• Checks all installed Guppy plugins
• Compares with Shopware UPGRADE.md
• Identifies potential breaking changes
• Creates compatibility report

3. AI-Supported Update Analysis

Use Claude AI for automated update analysis:

Analyze the Guppy Theme [source code] against the current Shopware UPGRADE.md [URL/content].
Identify:
1. Breaking changes affecting the theme
2. Deprecated features in use
3. New Shopware features for integration
4. Recommended adjustments

Create a structured update plan with priorities.

Support

Update Help

• 📖 Changelog: Detailed change history
• 🔧 Migration Guides: Step-by-step instructions
• 🎮 Playground: Testing environment
• 🐛 Issues: GitLab Repository

AI Support

Use Claude AI for:

• Automated Update Analysis
• Code Migration Help
• Compatibility Checks
• Custom Update Strategies

---

Structured update management ensures stable, predictable updates and minimizes downtime while maximizing feature development.