Clone release workflow

Author: hein-obox

.github/BUILD-ACTION-COMPARISON.md

@@ -0,0 +1,247 @@
+# Build Action Detailed Comparison
+# Hello Commerce vs Hello Theme
+
+## Overview
+This document provides a line-by-line comparison of the build-theme actions from both repositories to inform the decision on which approach to use.
+
+## Current Build Actions
+
+### Hello Theme Build Action Features
+**File:** `.github/workflows/build-theme/action.yml` (120 lines)
+
+#### Key Features:
+- **Sophisticated npm retry logic** with 3 attempts
+- **Multiple fallback strategies**:
+  - Primary: `npm ci --prefer-offline`
+  - Fallback 1: `npm install --legacy-peer-deps`  
+  - Fallback 2: Public registry explicitly
+  - Fallback 3: Install without package-lock
+- **Advanced error handling** with cache clearing
+- **Registry fallback mechanisms**
+- **Detailed logging** for debugging
+
+#### Build Process:
+```yaml
+- Install npm dependencies (with retry logic)
+- Install composer dependencies  
+- Set package version
+- Run build script (npm run build:prod by default)
+- Create theme build directory (/tmp/hello-theme-builds)
+- Package theme (hello-elementor-${VERSION}.zip)
+- Move to workspace
+```
+
+### Hello Commerce Build Action Features  
+**File:** `.github/workflows/build-theme/action.yml` (68 lines)
+
+#### Key Features:
+- **Simple npm installation** with single attempt
+- **Basic error handling**  
+- **Straightforward approach**
+- **Minimal logging**
+
+#### Build Process:
+```yaml
+- Install npm dependencies (npm ci only)
+- Install composer dependencies
+- Set package version  
+- Run build script (npm run build by default)
+- Create theme build directory (/tmp/hello-commerce-builds)
+- Package theme (hello-commerce-${VERSION}.zip)
+- Move to workspace
+```
+
+## Detailed Feature Comparison
+
+| Feature | Hello Theme | Hello Commerce | Advantage |
+|---------|-------------|----------------|-----------|
+| **NPM Installation Retries** | 3 attempts with exponential backoff | 1 attempt only | 🏆 Hello Theme |
+| **Registry Fallbacks** | 4 different strategies | None | 🏆 Hello Theme |
+| **Error Handling** | Comprehensive error recovery | Basic error handling | 🏆 Hello Theme |
+| **Cache Management** | Automatic cache clearing on failure | None | 🏆 Hello Theme |
+| **Logging Detail** | Verbose logging for debugging | Minimal logging | 🏆 Hello Theme |
+| **Code Complexity** | 120 lines (more complex) | 68 lines (simpler) | 🏆 Hello Commerce |
+| **Maintenance** | More complex to maintain | Easier to maintain | 🏆 Hello Commerce |
+| **Build Reliability** | Higher (due to retry logic) | Lower (single attempt) | 🏆 Hello Theme |
+
+## NPM Installation Logic Comparison
+
+### Hello Theme Approach
+```yaml
+# Enhanced retry logic for npm ci with registry fallbacks and cache clearing
+for i in {1..3}; do
+  echo "🔄 Attempt $i/3: Installing npm dependencies..."
+  
+  # Try npm ci first
+  if npm ci --prefer-offline --no-audit --no-fund --silent; then
+    echo "✅ npm ci succeeded on attempt $i"
+    break
+  else
+    echo "❌ npm ci failed on attempt $i"
+    
+    # Check if it's a 403/registry error and clear cache
+    if [ $i -lt 3 ]; then
+      echo "🧹 Clearing npm cache to resolve potential registry issues..."
+      npm cache clean --force 2>/dev/null || true
+      echo "⏳ Waiting 30 seconds before retry..."
+      sleep 30
+    else
+      # Multiple fallback strategies...
+      # Fallback 1: npm install --legacy-peer-deps
+      # Fallback 2: NPM_CONFIG_REGISTRY=https://registry.npmjs.org/
+      # Fallback 3: Install without package-lock.json
+    fi
+  fi
+done
+```
+
+### Hello Commerce Approach
+```yaml
+- name: Install npm dependencies
+  shell: bash
+  run: |
+    export PUPPETEER_SKIP_DOWNLOAD=true
+    npm ci
+```
+
+## Package Creation Comparison
+
+### Hello Theme
+```yaml
+# Create zip file with proper naming (following Hello Commerce pattern)
+zip -r "/tmp/hello-theme-builds/hello-elementor-${PACKAGE_VERSION}.zip" . \
+  -x "node_modules/*" "test-results/*" "tests/*" ".git/*" "*.zip" \
+     "playwright-report/*" ".wp-env.json.*" ".wp-env"
+```
+
+### Hello Commerce
+```yaml
+# Create zip file with proper naming
+zip -r "/tmp/hello-commerce-builds/hello-commerce-${PACKAGE_VERSION}.zip" . \
+  -x "node_modules/*" "test-results/*" "tests/*" ".git/*" "*.zip" \
+     "playwright-report/*" ".wp-env.json.*" ".wp-env"
+```
+
+**Identical exclusion patterns - no compatibility issues**
+
+## Performance Analysis
+
+### Hello Theme Build Action
+**Pros:**
+- ✅ High reliability due to retry logic
+- ✅ Handles network issues gracefully
+- ✅ Comprehensive error recovery
+- ✅ Production-tested in hello-theme repository
+- ✅ Better for CI/CD environments with network instability
+
+**Cons:**
+- ❌ More complex code to maintain
+- ❌ Longer execution time (due to retries)
+- ❌ More verbose output
+- ❌ Higher complexity for debugging
+
+### Hello Commerce Build Action
+**Pros:**  
+- ✅ Simple and straightforward
+- ✅ Faster execution (no retries)
+- ✅ Easy to understand and maintain
+- ✅ Less verbose output
+
+**Cons:**
+- ❌ Can fail on transient network issues
+- ❌ No fallback strategies
+- ❌ Less reliable in unstable environments
+- ❌ May require manual intervention on failures
+
+## Recommendation Analysis
+
+### Technical Recommendation: **Use Hello Theme's Build Action**
+
+**Rationale:**
+1. **Higher Reliability** - The retry logic and fallback strategies make builds more reliable in CI/CD environments
+2. **Production Proven** - Already tested and working in Hello Theme production environment
+3. **Future Proof** - Handles edge cases that Hello Commerce might encounter as it scales
+4. **Error Recovery** - Automatic recovery from transient failures reduces manual intervention
+
+### Adaptation Required:
+```yaml
+# Changes needed for Hello Commerce integration:
+1. Update temp directory: /tmp/hello-theme-builds → /tmp/hello-commerce-builds  
+2. Update package naming: hello-elementor-${VERSION} → hello-commerce-${VERSION}
+3. Update default build script: npm run build:prod → npm run build
+```
+
+## Integration Strategy
+
+### Phase 1: Direct Copy with Adaptations
+```yaml
+# Copy Hello Theme's build action to Hello Commerce
+# Update these variables:
+- TEMP_DIR: "/tmp/hello-commerce-builds"
+- ZIP_NAME: "hello-commerce-${PACKAGE_VERSION}.zip"  
+- DEFAULT_BUILD_SCRIPT: "npm run build"
+```
+
+### Phase 2: Optional Enhancements
+```yaml
+# Consider these improvements:
+1. Make retry count configurable (input parameter)
+2. Add option to disable retry logic for simple builds
+3. Add build timing metrics
+4. Enhance error reporting
+```
+
+### Phase 3: Standardization
+```yaml
+# Long term: Standardize across all theme repositories
+1. Create shared build action in common repository
+2. Use consistent naming patterns
+3. Share retry/fallback logic across all themes
+```
+
+## Testing Requirements
+
+### Build Action Testing Checklist
+- [ ] Test with Hello Commerce dependencies
+- [ ] Test retry logic with simulated network failures
+- [ ] Test fallback strategies
+- [ ] Verify package naming changes
+- [ ] Validate temp directory creation
+- [ ] Test with both npm ci and npm install scenarios
+- [ ] Verify exclusion patterns work correctly
+- [ ] Test error recovery mechanisms
+
+### Performance Testing
+- [ ] Compare build times with and without retry logic
+- [ ] Test memory usage during build
+- [ ] Validate artifact size and contents
+- [ ] Test concurrent build scenarios
+
+## Risk Assessment
+
+### Low Risk Changes
+- ✅ Package naming updates
+- ✅ Temp directory path changes  
+- ✅ Build script parameter changes
+
+### Medium Risk Changes
+- 🟡 Retry logic integration
+- 🟡 Error handling adaptation
+- 🟡 Fallback strategy testing
+
+### High Risk Areas
+- 🔴 NPM dependency compatibility with Hello Commerce packages
+- 🔴 Registry fallback behavior in Hello Commerce environment
+- 🔴 Build timing impact on overall workflow duration
+
+## Conclusion
+
+**Hello Theme's build action is superior** due to its comprehensive error handling and retry mechanisms. The additional complexity is justified by the increased reliability, especially in CI/CD environments where network issues are common.
+
+**Recommended Approach:**
+1. **Adopt Hello Theme's build action** as the base
+2. **Customize** for Hello Commerce naming and paths  
+3. **Test thoroughly** with Hello Commerce specific scenarios
+4. **Consider standardizing** across all theme repositories
+
+This approach ensures maximum build reliability while maintaining the proven functionality that Hello Theme has already validated in production.