hello-theme/.github/USE-MAIN-WORKFLOW.md

USE MAIN WORKFLOW - HELLO THEME ANALYSIS

🎯 OBJECTIVE

Analyze Hello Theme's workflow setup and trace what happens when version 3.4.4 is passed as input, examining how build files, workflow/action files, and test files are handled.

📋 SCENARIO ANALYSIS: HELLO THEME VERSION 3.4.4

🔄 FLOW OVERVIEW

When version hello_theme_version: "3.4.4" is passed to the workflow, here's what happens:

Daily Matrix → Playwright Workflow → NO CHECKOUT → Build Process → Test Extraction
     ↓              ↓                     ↓              ↓              ↓
   3.4.4         3.4.4 input        main branch     main source    3.4.4 tests

---

🚨 CRITICAL DISCOVERY: HELLO THEME HAS NO PRESERVE/RESTORE PATTERN

Hello Theme's Unique Approach:

Unlike Hello Biz, Hello Commerce, and Hello Plus, Hello Theme does NOT implement any version checkout logic. It uses a completely different strategy:

1. Always builds from main branch (current source code)
2. Only extracts tests from the target version
3. No preserve/restore pattern needed

---

🏗️ PART 1: BUILD FILES (What gets built)

Build Process Flow:

# Lines 59-108: playwright-with-specific-elementor-version.yml
- name: Set version outputs
  run: |
    # Hello Theme version from current repo (like Hello Commerce pattern)
    HT_VERSION=$(node -p "require('./package.json').version")  # Gets 3.4.4
    
    # Input version for reference (main, etc.)
    HELLO_THEME_INPUT="${{ inputs.hello_theme_version || 'main' }}"  # Gets "3.4.4"

- name: Build Hello Theme
  uses: ./.github/workflows/build-theme
  with:
    PACKAGE_VERSION: ${{ steps.set-versions.outputs.hello-theme-version }}  # Uses 3.4.4
    BUILD_SCRIPT_PATH: "npm run build:prod"

Key Insight: Version Coincidence

# Lines 65-66: Version detection logic
HT_VERSION=$(node -p "require('./package.json').version")  # Current: 3.4.4
HELLO_THEME_INPUT="${{ inputs.hello_theme_version || 'main' }}"  # Input: 3.4.4

Hello Theme works by coincidence: The current main branch version (3.4.4) matches the requested test version (3.4.4).

Result: Build Zip Contains:

• ✅ Source Code: From Hello Theme main branch (current 3.4.4)
  • style.css with version 3.4.4 header
  • package.json with "version": "3.4.4"
  • All PHP files, modules, assets from main branch
  • Current dependencies from main branch composer.json
• ✅ Build Assets: Compiled from main branch source
  • assets/js/ compiled from main branch TypeScript/JavaScript
  • assets/css/ compiled from main branch SCSS
  • Webpack output from main branch configuration

Key Point: The build uses main branch source code (which happens to be version 3.4.4) with main branch build tooling.

---

⚙️ PART 2: WORKFLOW AND ACTION FILES (What executes the build)

Workflow Files Used:

• ✅ Source: Always from main branch (current checkout)
• ✅ Location: .github/workflows/ directory
• ✅ Files: All workflow YAML files from main branch
• ✅ No Checkout: No version-specific checkout happens

Action Files Used:

• ✅ Source: Always from main branch (current checkout)
• ✅ Location: .github/workflows/*/action.yml
• ✅ Examples:
  • .github/workflows/build-theme/action.yml (main branch)
  • All other actions from main branch

Script Files Used:

• ✅ Source: Always from main branch (current checkout)
• ✅ Location: .github/scripts/ directory
• ✅ Files:
  • build-wp-env.js (main branch - configures WordPress environment)
  • All other scripts from main branch

Critical Difference from Other Themes:

# Hello Theme: NO checkout step exists
# Lines 54-57: Only standard checkout
- name: Checkout Hello Theme
  uses: actions/checkout@v4
  with:
    fetch-depth: 0
# No version-specific checkout follows

Key Point: Hello Theme never checks out a different version, so it always uses main branch for everything except tests.

---

🧪 PART 3: TEST FILES (What gets tested)

Test Extraction Process:

# Lines 450-524: Hybrid Test Setup - Extract tests from target version
TARGET_VERSION="${{ inputs.hello_theme_version || 'main' }}"  # "3.4.4"

# Extract tests from 3.4.4 tag
git archive "v3.4.4" tests/playwright/ | tar -x

Test Files Used:

• ✅ Source: From Hello Theme v3.4.4 tag (version-specific)
• ✅ Location: tests/playwright/ directory
• ✅ Content: Test files that match 3.4.4 functionality
  • Test specs from 3.4.4 (tests/playwright/tests/)
  • Page objects from 3.4.4 (tests/playwright/pages/)
  • Test configuration from 3.4.4 (tests/playwright/playwright.config.ts)

Hybrid Approach Logic:

# Lines 453-455: Hybrid approach explanation
echo "🎯 HYBRID APPROACH: Always latest workflows + version-specific tests"
echo "📋 Workflow infrastructure: main branch (latest build-wp-env.js, scripts, etc.)"
echo "🧪 Test content: ${{ inputs.hello_theme_version || 'main' }} (matches theme functionality)"

Test Execution:

• ✅ Test Runner: Uses main branch Playwright configuration and scripts
• ✅ Test Content: Uses 3.4.4-specific test files
• ✅ WordPress Environment: Built with main branch build-wp-env.js
• ✅ Theme Under Test: Hello Theme 3.4.4 build (from main branch)

Key Point: Tests from 3.4.4 run against Hello Theme 3.4.4 functionality, but use main branch test infrastructure.

---

📊 COMPLETE VERSION MATRIX

Component	Version Source	Actual Version	Purpose
Build Zip File	main branch	3.4.4	Theme functionality to test
Workflow Files	main branch	Latest	Latest workflow definitions
Action Files	main branch	Latest	Latest build/deploy logic
Script Files	main branch	Latest	Latest automation scripts
Test Files	v3.4.4 tag	3.4.4	Tests matching theme functionality
Test Infrastructure	main branch	Latest	Latest test runner and environment

---

🔍 DETAILED FLOW ANALYSIS

Step 1: Daily Matrix Triggers Workflow

# Daily matrix generates combinations like:
{"combination":"ht-ga-el-main","name":"Hello Theme 3.4.4 (GA) + Elementor main","hello_theme_version":"3.4.4","elementor_version":"main"}

Step 2: Workflow Receives Input

# Lines 9-12: playwright-with-specific-elementor-version.yml
inputs:
  hello_theme_version:
    description: 'Hello Theme version to test (e.g., 3.4.4 or main)'
    default: 'main'
    # Receives: "3.4.4"

Step 3: Version Detection (No Checkout)

# Lines 65-69: Set version variables
HT_VERSION=$(node -p "require('./package.json').version")  # Gets 3.4.4 from main
HELLO_THEME_INPUT="3.4.4"  # Input version

# No checkout happens - stays on main branch

Step 4: Build Process

# Lines 104-108: Build step
- name: Build Hello Theme
  uses: ./.github/workflows/build-theme
  with:
    PACKAGE_VERSION: 3.4.4  # Uses current main branch version
    BUILD_SCRIPT_PATH: "npm run build:prod"

Step 5: Test Extraction

# Lines 487-489: Test extraction
echo "📥 Extracting tests directory from v3.4.4..."
rm -rf ./tests/playwright/
git archive "v3.4.4" tests/playwright/ | tar -x

Step 6: Test Execution

# Test runner uses:
# - Hello Theme 3.4.4 theme (built from main)
# - Tests from 3.4.4 (extracted)  
# - Test infrastructure from main (latest)

---

🚨 CRITICAL OBSERVATIONS

✅ What Works (By Coincidence):

1. Current Version Match: Main branch is currently at 3.4.4
2. No Checkout Needed: Since main = requested version
3. Hybrid Test Approach: Uses latest infrastructure with version-specific tests
4. Simplified Logic: No complex preserve/restore pattern needed

⚠️ Critical Vulnerabilities:

1. Version Dependency: Only works when main branch version = requested version
2. Future Versions: Will break when main branch advances to 3.4.5+
3. Past Versions: Cannot test versions older than current main
4. No Preserve/Restore: Missing the pattern other themes have

🔧 Comparison with Other Themes:

Theme	Approach	Version Handling	Risk Level
Hello Biz	Preserve/Restore	✅ Any version	✅ Low
Hello Commerce	Preserve/Restore	✅ Any version	✅ Low
Hello Plus	JavaScript Script	✅ Any version	✅ Low
Hello Theme	No Checkout	❌ Current version only	🚨 High

---

🎯 HELLO THEME'S FUNDAMENTAL PROBLEM

The Issue:

Hello Theme's approach only works by coincidence because:

• Main branch version: 3.4.4
• Requested test version: 3.4.4
• They happen to match

What Happens When They Don't Match:

Scenario A: Testing Hello Theme 3.4.3

# Input: hello_theme_version: "3.4.3"
# Main branch: 3.4.4
# Result: Builds 3.4.4 source, tests with 3.4.3 tests → Version mismatch!

Scenario B: Main Branch Advances to 3.4.5

# Input: hello_theme_version: "3.4.4"  
# Main branch: 3.4.5
# Result: Builds 3.4.5 source, tests with 3.4.4 tests → Version mismatch!

The Root Cause:

Hello Theme lacks the preserve/restore pattern that other themes have implemented.

---

🔧 RECOMMENDED SOLUTION

Hello Theme Needs Preserve/Restore Pattern:

Hello Theme should implement the same preserve/restore pattern as Hello Biz and Hello Commerce:

1. Add version validation and preserve step
2. Add checkout specific version step
3. Add restore main branch actions step
4. Add cleanup steps

This would ensure:

• ✅ Build: Uses requested version source code (3.4.4)
• ✅ Workflows/Actions: Always uses main branch (latest)
• ✅ Tests: Uses version-specific tests (3.4.4)

---

🤔 CRITICAL QUESTIONS

1. Why Does Hello Theme Work Currently?

Answer: Pure coincidence - main branch version matches requested version.

2. What Happens When Versions Don't Match?

Answer: Version mismatch - builds wrong version, tests with different version.

3. Should Hello Theme Implement Preserve/Restore?

Answer: Yes, to ensure consistent behavior across all themes.

4. Is Hello Theme's Approach Intentional?

Answer: Likely not - it appears to be missing the pattern other themes have.

---

📋 IMPLEMENTATION RECOMMENDATION

Hello Theme Should:

1. Implement preserve/restore pattern like Hello Biz/Commerce
2. Add version checkout logic to handle any requested version
3. Maintain hybrid test approach (works well)
4. Add proper error handling for missing versions

Benefits:

• ✅ Consistency: Same pattern across all themes
• ✅ Reliability: Works for any version combination
• ✅ Future-proof: Won't break when main branch advances
• ✅ Maintainability: Predictable behavior

---

🎯 CONCLUSION

Hello Theme Version 3.4.4 Flow Summary:

1. Build Zip: Contains main branch source (happens to be 3.4.4)
2. Workflow/Actions: Always use main branch (current checkout)
3. Tests: Extract 3.4.4-specific tests but run with main branch infrastructure

Key Insight:

Hello Theme works by pure coincidence because the main branch version (3.4.4) matches the requested test version (3.4.4). This approach is fundamentally fragile and will break when versions don't align.

The Pattern Works Currently Because:

• ✅ Source Code: Happens to match the version being tested (3.4.4)
• ✅ Build Tools: Always latest (main branch)
• ✅ Test Content: Matches theme functionality (3.4.4)
• ✅ Test Infrastructure: Always latest (main branch)

But It Will Break When:

• ❌ Main branch advances to 3.4.5+
• ❌ Testing older versions like 3.4.3
• ❌ Any version mismatch occurs

Hello Theme needs the preserve/restore pattern to ensure reliable version testing like the other themes.