Git Branching Strategies for Magento

GitFlow Overview

GitFlow uses long-lived branches for releases and short-lived branches for features:

main (production)
  |
  +-- release/2.4.6
  |     |
  |     +-- (final QA, bug fixes)
  |     +-- merge -> main
  |     +-- merge -> develop
  |
  +-- develop (integration)
  |     |
  |     +-- feature/graphql-search
  |     +-- feature/loyalty-points
  |     +-- bugfix/cart-discount
  |
  +-- hotfix/xss-vulnerability
        |
        +-- (fix on production)
        +-- merge -> main
        +-- merge -> develop

Branch Purposes

GitFlow Commands

# Start a feature
git checkout develop
git pull origin develop
git checkout -b feature/custom-checkout

# Finish a feature
git checkout develop
git merge --no-ff feature/custom-checkout
git branch -d feature/custom-checkout
git push origin --delete feature/custom-checkout

# Start a release
git checkout develop
git checkout -b release/2.4.6

# Finish a release
git checkout main
git merge --no-ff release/2.4.6
git tag -a v2.4.6 -m "Release 2.4.6"
git checkout develop
git merge --no-ff release/2.4.6

# Hotfix
git checkout main
git checkout -b hotfix/security-patch
# ... fix ...
git checkout main
git merge --no-ff hotfix/security-patch
git tag -a v2.4.6.1
git checkout develop
git merge --no-ff hotfix/security-patch

Magento Module Development with GitFlow

# Module development feature
git checkout develop
git checkout -b feature/inventory-module

# Work on module
mkdir -p app/code/Vendor/Inventory/etc
# ... develop module ...

git add .
git commit -m "feat(inventory): add module skeleton with di.xml"
git commit -m "feat(inventory): add inventory resource model"
git commit -m "feat(inventory): add REST API endpoints"
git commit -m "test(inventory): add unit tests"

# Merge back
git checkout develop
git merge --no-ff feature/inventory-module

Key Takeaway

GitFlow provides structured branching for teams with scheduled releases. Use develop for integration, main for production, feature/* for work, release/* for stabilization.

Trunk-Based Overview

Everyone commits to main (trunk) with short-lived branches:

main (trunk)
  |
  +-- feature/loyalty (1-2 days)
  +-- feature/search (1-2 days)
  +-- bugfix/tax (hours)
  +-- feature/checkout (1-2 days)

Key Principles

• Branches live < 2 days
• Feature flags for incomplete work
• Continuous integration to main
• Small, frequent commits
• Comprehensive test suite

Feature Flags in Magento

// app/code/Vendor/Feature/etc/config.xml
<config>
    <default>
        <vendor_feature>
            <enable_new_checkout>0</enable_new_checkout>
        </vendor_feature>
    </default>
</config>

// Usage in code
$isEnabled = $this->scopeConfig->isSetFlag(
    'vendor_feature/enable_new_checkout'
);

if ($isEnabled) {
    return $this->newCheckoutFlow->execute();
}
return $this->legacyCheckoutFlow->execute();

Short-Lived Branch Workflow

# Create branch
git checkout -b feature/cart-widget

# Commit frequently (1-2 commits)
git commit -m "feat(cart): add cart widget component"
git commit -m "feat(cart): integrate widget with checkout"

# Same day or next day - merge
git checkout main
git merge --no-ff feature/cart-widget
git push origin main

When to Use Trunk-Based

• High-performing teams with strong CI/CD
• Projects with feature flags
• Continuous deployment workflows
• Teams with comprehensive automated tests

Key Takeaway

Trunk-based development enables faster delivery with short-lived branches and feature flags. Best for teams with strong CI/CD pipelines and automated testing.

Feature Branch Naming

feature/short-description     feature/product-api
feature/ticket-id-description feature/MAGE-123-cart-widget
bugfix/short-description      bugfix/tax-calculation-error
hotfix/short-description      hotfix/xss-in-search
release/version-number        release/2.4.6-p1

Feature Branch Best Practices

# 1. Keep branches short-lived (< 3 days)
# 2. Sync with develop regularly
git checkout feature/cart-widget
git fetch origin
git rebase origin/develop

# 3. One feature per branch
# 4. Delete branch after merge
git branch -d feature/cart-widget
git push origin --delete feature/cart-widget

# 5. Use meaningful names
feature/add-wishlist           # Good
feature/johns-work             # Bad

Pull Request Workflow

# Push feature branch
git push origin feature/cart-widget

# Create PR on GitHub/GitLab
# Target: develop
# Reviewers: team members
# Labels: enhancement, needs-review

# After approval and CI passes
git checkout develop
git merge --no-ff feature/cart-widget
git push origin develop

Stale Branch Cleanup

# Find merged branches
git branch --merged develop | grep -v develop | grep -v main

# Delete local merged branches
git branch --merged develop | grep -v develop | grep -v main | xargs git branch -d

# Delete remote stale branches
git fetch --prune origin

Feature Branch for Magento Module

# Branch per module feature
git checkout develop
git checkout -b feature/catalog-layered-nav

# Files for this feature only
app/code/Vendor/Catalog/Block/LayeredNav/
app/code/Vendor/Catalog/Model/Layer/
app/code/Vendor/Catalog/view/frontend/templates/layered-nav/

# Tests
test/unit/Vendor/Catalog/Block/LayeredNavTest.php

# Commit with scope
git commit -m "feat(catalog): add layered navigation block"
git commit -m "test(catalog): add layered navigation unit tests"

Key Takeaway

Feature branches isolate work, enable code review, and keep main clean. Keep branches short-lived, sync frequently, and delete after merge.

Release Branch Lifecycle

# 1. Create release branch from develop
git checkout develop
git checkout -b release/2.4.6

# 2. Stabilization phase - only bug fixes
git commit -m "fix(checkout): resolve tax rounding error"
git commit -m "fix(catalog): fix image zoom on mobile"

# 3. Update version numbers
bin/magento module:config:set Vendor_Module 2.4.6

# 4. Merge to main
git checkout main
git merge --no-ff release/2.4.6
git tag -a v2.4.6 -m "Release 2.4.6"

# 5. Merge back to develop
git checkout develop
git merge --no-ff release/2.4.6

# 6. Delete release branch
git branch -d release/2.4.6

Magento Deployment from Release Branch

# In release branch - deploy to staging
git checkout release/2.4.6
git push origin release/2.4.6

# CI/CD deploys to staging automatically
# After QA approval - merge to main
git checkout main
git merge --no-ff release/2.4.6
git tag v2.4.6
git push origin main --tags

Version Management

# Update composer.json version
composer config version 2.4.6

# Update module versions
bin/magento module:config:set Vendor_Module 2.4.6

# Create git tag
git tag -a v2.4.6 -m "Release 2.4.6 - Holiday features"
git push origin v2.4.6

# List tags
git tag -l "v2.*"

Release Branch for Multi-Module Updates

# When releasing multiple module updates
git checkout develop
git checkout -b release/2024-q4

# Merge feature branches that are ready
git merge --no-ff feature/inventory-api
git merge --no-ff feature/search-v2
git merge --no-ff feature/loyalty-points

# Final testing and fixes
git commit -m "fix(search): resolve faceted search performance"

# Deploy
git checkout main
git merge --no-ff release/2024-q4
git tag -a v2024-q4
git push origin main --tags

Key Takeaway

Release branches stabilize code before production. Only bug fixes go into release branches. Always merge back to both main and develop. Tag releases for tracking.