Cloud 8.04

Apply Patches

Understanding m2-hotfixes/ directory, patch workflows, ece-tools patches, and emergency fixes.

Exam Critical: Understanding how to apply patches in the m2-hotfixes/ directory and ece-tools patches is important for the exam!

Apply Patches

mindmap root((Patches)) m2 hotfixes Magento support patches Third party fixes Emergency production Git patches Workflow Place in directory Test git apply Clear cache Commit and push ece tools patches 80 patches Cloud compatibility SCD on demand Core fixes Build Phase Auto applied During deployment

Magento Patches Overview

What Are Patches?

Purpose

Patches are code fixes that:

  • Fix bugs in Magento core or modules
  • Add Cloud-specific compatibility
  • Apply emergency hotfixes
  • Modify third-party module behavior
  • Applied automatically during build phase

Two Types of Patches

  • m2-hotfixes/: Custom patches from support or emergency fixes
  • ece-tools patches: ~80 built-in patches for Cloud compatibility

m2-hotfixes/ Directory

Custom Patch Location

Critical Information

Magento support occasionally provides patches for Commerce customers. When received, place the patch in the m2-hotfixes/ directory.

Directory Location

m2-hotfixes/

This directory is in the project root (same level as app/, vendor/, etc.)

Directory Structure:
project-root/
├── app/
├── vendor/
├── m2-hotfixes/
│   ├── MDVA-12345__fix_checkout_issue.patch
│   ├── MDVA-67890__update_catalog.patch
│   └── custom-fix.patch
├── composer.json
└── .magento.app.yaml

Applying Patches Workflow

Step-by-Step Process

Step 1: Place Patch in Directory

When you receive a patch from Magento support or create one:

# Create directory if it doesn't exist
mkdir -p m2-hotfixes

# Place patch file
mv MDVA-12345__fix_issue.patch m2-hotfixes/

Step 2: Test the Patch

Test Before Committing

Once in this directory, test the patch by running git apply:

git apply ./m2-hotfixes/{PATCH_NAME}
Example:
git apply ./m2-hotfixes/MDVA-12345__fix_checkout_issue.patch
What git apply Does:
  • Tests if patch can be applied cleanly
  • Shows conflicts if any
  • Does NOT actually modify files (dry run)
  • Verifies patch compatibility

Step 3: Clear Cache and Test

Clear the Magento cache and test:
# Clear cache
bin/magento cache:flush

# Test functionality
# Navigate to affected areas
# Verify fix works correctly

Step 4: Commit and Push

Once satisfied, commit and push:
git add m2-hotfixes/MDVA-12345__fix_checkout_issue.patch
git commit -m "Apply MDVA-12345 patch to fix checkout issue"
git push origin integration

Build Phase Application

The patch is applied in the build phase automatically. When you deploy, ece-tools will find patches in m2-hotfixes/ and apply them during build.

Patch Use Cases

When to Use m2-hotfixes/

Use Case 1: Magento Support Patches

Scenario:

Magento support provides a patch to fix a bug in core Magento.

Workflow:
  1. Receive patch file from support ticket
  2. Place in m2-hotfixes/ directory
  3. Test with git apply
  4. Deploy to integration, verify fix
  5. Deploy to staging, test thoroughly
  6. Deploy to production

Use Case 2: Third-Party Module Fixes

Scenario:

m2-hotfixes is also useful when third-party modules are installed from repos and need to have bugs or mods made.

Example:
  • Third-party module has a bug
  • Vendor hasn't released fix yet
  • Create patch to fix the issue
  • Place in m2-hotfixes/ until vendor updates

Use Case 3: Emergency Production Fixes

Emergency Hotfix

It is also used when an emergency fix is needed on production.

Emergency Workflow:
  1. Production issue discovered
  2. Create a patch to fix the issue
  3. Add directly to the production branch
  4. Deploy immediately to production
  5. Then fix the problem properly
  6. Promote the fix through normal processes

This allows quick emergency fix while maintaining proper development workflow for permanent solution.

Third-Party Vendor Patches

Using Third-Party Patches

Important Note

Ultimately, any third-party vendor can apply patches here, but they may have unintended side effects.

Risks of Third-Party Patches

  • May conflict with other patches
  • Could break existing functionality
  • May not be compatible with Magento version
  • Might have security implications
  • Could cause performance issues

Best Practices

  • Always test in integration first
  • Review patch contents before applying
  • Verify source is trustworthy
  • Test thoroughly in staging
  • Keep patches documented
  • Monitor for conflicts

ece-tools Built-in Patches

Cloud Compatibility Patches

Built-in Patch System

In addition, ece-tools comes with approximately 80 patches to make core Magento code compatible with Magento Cloud.

Purpose of ece-tools Patches:
  • Enable Cloud-specific features
  • Fix incompatibilities with Cloud environment
  • Optimize for Cloud infrastructure
  • Add features not native to Magento
  • Improve deployment performance

Example: SCD On Demand Patch

On-Demand Static Content Deploy

For example, on-demand static-content deploy is not a native Magento feature.

This patch adds the ability to generate static content on-demand rather than during deployment.

Patch Process in ece-tools:
  1. Patch is made known to ece-tools - Defined in patch configuration
  2. Loaded - ece-tools loads the patch during build
  3. Applied - Patch is applied to Magento code

How ece-tools Patches Work

Automatic Patch Application

Stage What Happens Location in ece-tools
1. Made Known Patches defined and registered Patch configuration files
2. Loaded ece-tools loads patch definitions Patch loading logic
3. Applied Patches applied to Magento code Build phase execution

Benefits of ece-tools Patches:

  • Automatic: No manual intervention needed
  • Tested: Patches are tested for Cloud compatibility
  • Maintained: Updated with ece-tools versions
  • Comprehensive: ~80 patches for various fixes
  • Transparent: Applied during build phase

Creating Custom Patches

How to Create a Patch File

Method 1: Git Diff

# Make your code changes
# Create patch from uncommitted changes
git diff > m2-hotfixes/custom-fix.patch

Method 2: Git Format-Patch

# Make changes and commit
git add .
git commit -m "Fix issue"

# Create patch from last commit
git format-patch -1 HEAD --stdout > m2-hotfixes/CUSTOM-001.patch

Method 3: Compare Branches

# Create patch from difference between branches
git diff master..fix-branch > m2-hotfixes/fix-branch.patch
Patch File Format:

Git patch files contain:

  • File paths to modify
  • Line numbers and changes
  • Context around changes
  • Human-readable diff format

Testing Patches

Verification Process

Test Patch Application

# Check if patch applies cleanly (dry run)
git apply --check ./m2-hotfixes/MDVA-12345.patch

# If successful, see what would change
git apply --stat ./m2-hotfixes/MDVA-12345.patch

# Apply the patch (for testing only, not needed for deployment)
git apply ./m2-hotfixes/MDVA-12345.patch

Rollback Patch (for Testing)

# Reverse a patch
git apply -R ./m2-hotfixes/MDVA-12345.patch
Note:

You don't need to manually apply patches before deployment. Simply placing them in m2-hotfixes/ and committing is enough. ece-tools applies them automatically during build phase.

Patch Application During Build

Automatic Application

Build Phase Process

  1. Deployment starts
  2. Build phase begins
  3. ece-tools scans m2-hotfixes/ directory
  4. Applies all patches found
  5. Applies ece-tools built-in patches (~80)
  6. Continues with normal build process

Patch Order:

  • Patches applied in alphabetical order
  • ece-tools patches applied first
  • m2-hotfixes/ patches applied second
  • Order matters if patches conflict

Common Patch Scenarios

Real-World Examples

Scenario 1: Critical Production Bug

Problem:

Checkout breaks due to tax calculation bug in production.

Emergency Solution:
  1. Identify bug in code
  2. Create patch with fix: git diff > m2-hotfixes/emergency-tax-fix.patch
  3. Commit to production branch
  4. Push and deploy immediately
  5. Test checkout functionality
Proper Follow-up:
  1. Create proper fix in integration branch
  2. Test thoroughly
  3. Code review
  4. Deploy through normal process
  5. Remove emergency patch once proper fix deployed

Scenario 2: Third-Party Module Bug

Problem:

Third-party payment module has bug, vendor slow to respond.

Solution:
  1. Create patch fixing the bug
  2. Place in m2-hotfixes/
  3. Test in integration
  4. Deploy to production
  5. Remove patch when vendor releases official fix

Best Practices

Patch Management Guidelines

Do's

  • Test patches first: Always test with git apply
  • Use descriptive names: MDVA-12345__description.patch
  • Document patches: Keep list of applied patches
  • Test in integration: Never apply directly to production without testing
  • Clear cache after: bin/magento cache:flush
  • Review patch contents: Understand what changes
  • Keep patches minimal: One fix per patch
  • Remove when fixed: Remove patches after proper fix deployed

Don'ts

  • Don't skip testing: Always verify patch works
  • Don't leave emergency patches: Replace with proper fixes
  • Don't trust unknown sources: Review all third-party patches
  • Don't forget to commit: Patches must be in git
  • Don't apply conflicting patches: Test compatibility

Exam Tips

Key Points to Remember

  • Patch location: m2-hotfixes/ directory in project root
  • Test command: git apply ./m2-hotfixes/{PATCH_NAME}
  • Clear cache: bin/magento cache:flush after testing
  • Commit and push: Patches must be in git repository
  • Applied in build phase: Automatic during deployment
  • Third-party patches: Can use, but may have unintended side effects
  • Module fixes: m2-hotfixes useful for third-party module bugs
  • Emergency fixes: Can add directly to production branch
  • Proper process: Fix properly, promote through normal workflow
  • ece-tools patches: ~80 patches for Cloud compatibility
  • SCD on demand: Example of non-native feature added by patch
  • Patch process: Made known → Loaded → Applied
Previous: Cloud 8.03 Debug with XDebug Practice Cloud 8.04