Contributing

Guppy uses a staging branch workflow to test features under controlled conditions before they ship to production. The same strategy applies to DmfGuppyTheme and all Guppy plugins.

Branch structure

Branch	Purpose	Shopware compatibility
main	Production-ready, single source of truth, all tags originate here.	current Shopware LTS
stage	QA / testing branch, fed into the Guppy Playground.	current Shopware LTS
Feature branches	individual development, convention TICKET-123_feature-name.	–

Feature workflow step by step

1. Create the feature branch (from main)

git checkout main
git pull
git checkout -b GUPPY-123_product-slider-component

2. Develop and commit

Conventional Commits recommended, with a ticket prefix:

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

3. Merge into stage for testing

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

Parallel features

Multiple features can be tested in stage in parallel, as long as they don't conflict.

4. Trigger the playground pipeline

In the guppy-playground GitLab project:

• CI/CD → Pipelines → Run Pipeline
• The pipeline auto-pulls the stage branches.

5. QA in Jira

• Set ticket status to Testing.
• Assign a QA person.
• Test: functionality, cross-browser, mobile, accessibility.
• On issues: back to step 2.
• On success: QA sign-off.

6. Merge into main

Feature branch straight into main

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

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

7. Tag the version

Follow SemVer, see Changelog.

git tag v2.6.0
git push --tags

Major releases with RC tags

For breaking changes targeting a new Shopware major version there is no separate branch. RC tags are created directly on main:

git tag v2.8.0-rc1
git push --tags

Multiple RC iterations are possible (-rc1, -rc2, ...) before the final release.

8. Update consumer projects

• Express demo: composer update dmf/sw6-guppy-theme.
• Customer projects: after sign-off from the project manager.

Hotfixes

For critical bug fixes:

1. Branch off main: HOTFIX-123_critical-bug.
2. Develop the fix.
3. Merge directly into main (skip stage).
4. Tag a PATCH version.
5. Deploy immediately.
6. Update stage.

Hotfixes as exception

Hotfixes bypass QA. If at all possible, use the normal stage workflow.

Keep stage fresh

Periodically (every few months) merge main into stage so hotfixes don't get lost:

git checkout stage
git merge main
git push

Workflow diagram

Feature branch (from main)
         ↓
   Development
         ↓
   Merge → stage
         ↓
   Playground pipeline
         ↓
   QA testing ──→ Issues? ──→ Back to development
         ↓
     QA sign-off
         ↓
   Merge feature branch → main
         ↓
   Tag the version
         ↓
   Update consumer projects

Testing environments

Environment	Branch / version	Purpose
Guppy Playground	stage	QA + feature testing
Express demo	tagged releases	showcase
Customer projects	specific tags	production

Release checklist

• [ ] Feature branch created from main
• [ ] Feature developed and locally tested
• [ ] Feature branch merged into stage
• [ ] Playground pipeline triggered
• [ ] Jira ticket assigned to a QA person
• [ ] QA testing passed
• [ ] Feature branch merged into main
• [ ] Version tag created
• [ ] Express demo updated
• [ ] Customer projects informed (if necessary)

Related

• Changelog: versioning policy (SemVer).
• Architecture: plugin structure, theme.json model.