Merge release/10.5.0 into trunk

Author: RadoslavGeorgiev

.claude/CLAUDE.md

@@ -15,6 +15,29 @@ WooCommerce Payments (WCPay) is a WordPress plugin that provides payment process
 - See `woocommerce-payments.php` header for current version and WordPress/WooCommerce/PHP requirements
 - See `package.json` for Node.js version requirements (engines field)
 
+## WooCommerce Core Reference
+
+WooPayments is a separate plugin that integrates with WooCommerce core, leveraging its hooks, filters, and APIs. Having the WooCommerce codebase available locally provides useful context when working on WooPayments.
+
+**Location:** `../woocommerce` (or set `WOOCOMMERCE_DIR` env var to override)
+
+**Key paths within WooCommerce:**
+- `plugins/woocommerce/includes/` - Core WooCommerce PHP classes
+- `plugins/woocommerce/src/` - Modern PSR-4 WooCommerce code
+- `plugins/woocommerce-blocks/` - Checkout and cart blocks
+
+**When to reference WooCommerce core:**
+- When working with WC hooks/filters - check the core implementation to understand parameters, timing, and context
+- When using WC base classes (e.g., `WC_Payment_Gateway`) - understand the parent class behavior
+- When debugging issues that may involve core behavior
+- When implementing features that interact with WC APIs (orders, products, customers, etc.)
+
+**Auto-reference triggers:** Proactively check WooCommerce core when you encounter:
+- Classes using `WC_*` base classes
+- Hooks starting with `woocommerce_` or `wc_`
+- Usage of `WC()` singleton or WC helper functions
+- Order, product, or customer manipulation code
+
 ## Directory Structure
 
 ### PHP Code
@@ -105,7 +128,8 @@ npm run psalm                       # PHP static analysis
 
 ### Other
 ```bash
-npm run changelog                   # Add changelog entry
+npm run changelog                   # Add changelog entry (interactive)
+npm run changelog:add               # Add changelog entry (non-interactive, for automation)
 npm run i18n:pot                    # Generate translations
 ```
 
@@ -128,7 +152,9 @@ npm run i18n:pot                    # Generate translations
 - Release branch: `trunk`
 - Husky manages git hooks
 - **Before creating a PR:**
-  - Must run `npm run changelog add` and commit the changelog entry (choose 'patch' if change is not significant)
+  - Must add and commit a changelog entry (use 'patch' significance if change is not significant)
+  - For Claude/automation: `npm run changelog:add -- --type=<type> --entry="<description>"`
+  - For interactive use: `npm run changelog`
   - Changelog must be committed and pushed before creating the PR
 - Use PR template from `.github/PULL_REQUEST_TEMPLATE.md` when creating pull requests
   - Include testing instructions
@@ -148,8 +174,15 @@ npm run i18n:pot                    # Generate translations
 - Use npm for JavaScript dependencies
 
 ### Changelog
-- Use `npm run changelog` to add entries
-- Types: Add, Fix, Update, Dev
+- Use `npm run changelog` for interactive changelog entry creation
+- Use `npm run changelog:add` for non-interactive (automation/Claude) usage:
+  ```bash
+  npm run changelog:add -- --type=fix --entry="Fixed a bug"
+  npm run changelog:add -- --type=add --entry="Added feature" --significance=minor
+  # Or with positional args: npm run changelog:add -- patch fix "Fixed a bug"
+  ```
+- Types: add, fix, update, dev
+- Significances: patch (default), minor, major
 - Entries go in `changelog/` directory
 
 ## Important Configuration Files

.github/workflows/compatibility.yml

@@ -6,7 +6,7 @@ on:
 env:
   WC_MIN_SUPPORTED_VERSION: '7.6.0'
   WP_MIN_SUPPORTED_VERSION: '6.0'
-  PHP_MIN_SUPPORTED_VERSION: '7.3'
+  PHP_MIN_SUPPORTED_VERSION: '7.4'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

.github/workflows/e2e-test.yml

@@ -72,7 +72,7 @@ jobs:
           # - WC RC: YES blocks tests (newest version, test upcoming release)
 
           # Define common values to reduce repetition
-          PHP_LEGACY="7.3"
+          PHP_LEGACY="7.4"
           PHP_STABLE="8.3"
           PHP_LATEST="8.4"
           TEST_GROUPS_WCPAY="wcpay"
@@ -84,7 +84,7 @@ jobs:
           # Initialize empty matrix array
           MATRIX_ENTRIES=()
 
-          # Add WC 7.7.0 with PHP 7.3 only (legacy - NO blocks tests)
+          # Add WC 7.7.0 with PHP 7.4 only (legacy - NO blocks tests)
           MATRIX_ENTRIES+=("{\"woocommerce\":\"7.7.0\",\"php\":\"$PHP_LEGACY\",\"test_groups\":\"$TEST_GROUPS_WCPAY\",\"test_branches\":\"$TEST_BRANCHES_MERCHANT\"}")
           MATRIX_ENTRIES+=("{\"woocommerce\":\"7.7.0\",\"php\":\"$PHP_LEGACY\",\"test_groups\":\"$TEST_GROUPS_WCPAY\",\"test_branches\":\"$TEST_BRANCHES_SHOPPER\"}")
           # The following tests are temporarily disabled due to a fatal error with WC 7.7.0.

.github/workflows/php-lint-test.yml

@@ -7,8 +7,7 @@ on:
 env:
   WP_VERSION:        latest
   WC_MIN_SUPPORTED_VERSION: '7.6.0'
-  GUTENBERG_VERSION: latest
-  PHP_MIN_SUPPORTED_VERSION: '7.3'
+  PHP_MIN_SUPPORTED_VERSION: '7.4'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -41,8 +40,8 @@ jobs:
       - name: "Generate matrix"
         id: generate_matrix
         run: |
-          PHP_VERSIONS=$( echo "[\"$PHP_MIN_SUPPORTED_VERSION\", \"7.3\", \"7.4\"]" )
-          echo "matrix={\"php\":$PHP_VERSIONS}" >> $GITHUB_OUTPUT
+          # PHP 7.4+ can use latest Gutenberg
+          echo "matrix={\"php\":[\"7.4\"],\"gutenberg\":[\"latest\"],\"include\":[{\"php\":\"$PHP_MIN_SUPPORTED_VERSION\",\"gutenberg\":\"22.3.0\"}]}" >> $GITHUB_OUTPUT
 
   test:
     name: PHP testing
@@ -69,3 +68,4 @@ jobs:
       - run: bash bin/run-ci-tests.bash
         env:
           WC_VERSION: ${{ env.WC_MIN_SUPPORTED_VERSION }}
+          GUTENBERG_VERSION: ${{ matrix.gutenberg }}

.github/workflows/qit-e2e-pr.yml

@@ -0,0 +1,82 @@
+name: QIT E2E Tests - Pull Request
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - trunk
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build plugin
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up repository
+        uses: ./.github/actions/setup-repo
+
+      - name: Build the plugin
+        uses: ./.github/actions/build
+
+      - name: Upload plugin artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: woocommerce-payments-${{ github.run_id }}
+          path: woocommerce-payments.zip
+          retention-days: 1
+
+  generate-matrix:
+    name: Generate test matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.generate.outputs.matrix }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Generate matrix
+        id: generate
+        run: |
+          # Get WC versions from matrix script
+          SCRIPT_RESULT=$(.github/scripts/generate-wc-matrix.sh)
+          L1_VERSION=$(echo "$SCRIPT_RESULT" | jq -r '.metadata.l1_version')
+
+          echo "L-1 version: $L1_VERSION" >&2
+
+          # Build PR matrix: L-1 + latest, PHP 8.3 only, all projects
+          MATRIX_ENTRIES=()
+          for wc_version in "$L1_VERSION" "latest"; do
+            for project in "shopper" "merchant" "subscriptions"; do
+              MATRIX_ENTRIES+=("{\"woocommerce\":\"$wc_version\",\"wordpress\":\"latest\",\"php\":\"8.3\",\"project\":\"$project\"}")
+            done
+          done
+
+          MATRIX_JSON=$(printf '%s\n' "${MATRIX_ENTRIES[@]}" | jq -s '{"include": .}' -c)
+          echo "matrix=$MATRIX_JSON" >> $GITHUB_OUTPUT
+
+  qit-e2e:
+    name: "${{ matrix.project }} | WC ${{ matrix.woocommerce }} | PHP ${{ matrix.php }}"
+    needs: [build, generate-matrix]
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }}
+    uses: ./.github/workflows/qit-e2e-run.yml
+    with:
+      woocommerce-version: ${{ matrix.woocommerce }}
+      wordpress-version: ${{ matrix.wordpress }}
+      php-version: ${{ matrix.php }}
+      artifact-name: woocommerce-payments-${{ github.run_id }}
+      playwright-project: ${{ matrix.project }}
+    secrets:
+      QIT_CI_USER: ${{ secrets.QIT_CI_USER }}
+      QIT_CI_SECRET: ${{ secrets.QIT_CI_SECRET }}
+      E2E_QIT_JP_SITE_ID: ${{ secrets.E2E_QIT_JP_SITE_ID }}
+      E2E_QIT_JP_BLOG_TOKEN: ${{ secrets.E2E_QIT_JP_BLOG_TOKEN }}
+      E2E_QIT_JP_USER_TOKEN: ${{ secrets.E2E_QIT_JP_USER_TOKEN }}

.github/workflows/qit-e2e-prerelease.yml

@@ -0,0 +1,71 @@
+name: QIT E2E Tests - Pre-release
+
+on:
+  workflow_dispatch:
+    inputs:
+      woocommerce-version:
+        description: 'WooCommerce version (e.g., 10.5.0-dev, 9.7.0-beta.1, 9.7.0-rc.1)'
+        required: true
+        type: string
+
+jobs:
+  build:
+    name: Build plugin
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up repository
+        uses: ./.github/actions/setup-repo
+
+      - name: Build the plugin
+        uses: ./.github/actions/build
+
+      - name: Upload plugin artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: woocommerce-payments-${{ github.run_id }}
+          path: woocommerce-payments.zip
+          retention-days: 1
+
+  generate-matrix:
+    name: Generate test matrix
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.generate.outputs.matrix }}
+    steps:
+      - name: Generate matrix
+        id: generate
+        run: |
+          WC_VERSION="${{ inputs.woocommerce-version }}"
+          echo "WC version: $WC_VERSION" >&2
+
+          # Build pre-release matrix: user-specified WC version, PHP 8.3, all projects
+          MATRIX_ENTRIES=()
+          for project in "shopper" "merchant" "subscriptions"; do
+            MATRIX_ENTRIES+=("{\"woocommerce\":\"$WC_VERSION\",\"wordpress\":\"latest\",\"php\":\"8.3\",\"project\":\"$project\"}")
+          done
+
+          MATRIX_JSON=$(printf '%s\n' "${MATRIX_ENTRIES[@]}" | jq -s '{"include": .}' -c)
+          echo "matrix=$MATRIX_JSON" >> $GITHUB_OUTPUT
+
+  qit-e2e:
+    name: "${{ matrix.project }} | WC ${{ matrix.woocommerce }} | PHP ${{ matrix.php }}"
+    needs: [build, generate-matrix]
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }}
+    uses: ./.github/workflows/qit-e2e-run.yml
+    with:
+      woocommerce-version: ${{ matrix.woocommerce }}
+      wordpress-version: ${{ matrix.wordpress }}
+      php-version: ${{ matrix.php }}
+      artifact-name: woocommerce-payments-${{ github.run_id }}
+      playwright-project: ${{ matrix.project }}
+    secrets:
+      QIT_CI_USER: ${{ secrets.QIT_CI_USER }}
+      QIT_CI_SECRET: ${{ secrets.QIT_CI_SECRET }}
+      E2E_QIT_JP_SITE_ID: ${{ secrets.E2E_QIT_JP_SITE_ID }}
+      E2E_QIT_JP_BLOG_TOKEN: ${{ secrets.E2E_QIT_JP_BLOG_TOKEN }}
+      E2E_QIT_JP_USER_TOKEN: ${{ secrets.E2E_QIT_JP_USER_TOKEN }}

.github/workflows/qit-e2e-run.yml

@@ -0,0 +1,92 @@
+name: QIT E2E Tests - Run
+
+on:
+  workflow_call:
+    inputs:
+      woocommerce-version:
+        description: 'WooCommerce version (nightly, or specific version like 9.6.0, 10.5.0-dev)'
+        required: true
+        type: string
+      wordpress-version:
+        description: 'WordPress version (latest, nightly, or specific version)'
+        required: false
+        type: string
+        default: 'latest'
+      php-version:
+        description: 'PHP version'
+        required: true
+        type: string
+      artifact-name:
+        description: 'Name of the artifact containing the built plugin zip'
+        required: true
+        type: string
+      playwright-project:
+        description: 'Playwright project to run (shopper, merchant, subscriptions)'
+        required: true
+        type: string
+    secrets:
+      QIT_CI_USER:
+        required: true
+      QIT_CI_SECRET:
+        required: true
+      E2E_QIT_JP_SITE_ID:
+        required: true
+      E2E_QIT_JP_BLOG_TOKEN:
+        required: true
+      E2E_QIT_JP_USER_TOKEN:
+        required: true
+
+jobs:
+  qit-e2e:
+    name: "Run tests"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download plugin artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ inputs.artifact-name }}
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ inputs.php-version }}
+          tools: composer
+          coverage: none
+
+      - name: Install QIT CLI
+        # Use dev-trunk because test packages feature is not yet in stable releases
+        run: composer global require woocommerce/qit-cli:dev-trunk
+
+      - name: Authenticate QIT
+        run: qit partner:add --user='${{ secrets.QIT_CI_USER }}' --application_password='${{ secrets.QIT_CI_SECRET }}'
+
+      - name: Run QIT E2E Tests
+        env:
+          E2E_JP_SITE_ID: ${{ secrets.E2E_QIT_JP_SITE_ID }}
+          E2E_JP_BLOG_TOKEN: ${{ secrets.E2E_QIT_JP_BLOG_TOKEN }}
+          E2E_JP_USER_TOKEN: ${{ secrets.E2E_QIT_JP_USER_TOKEN }}
+        run: |
+          qit run:e2e woocommerce-payments \
+            --config tests/qit/qit.json \
+            --woo=${{ inputs.woocommerce-version }} \
+            --wp=${{ inputs.wordpress-version }} \
+            --php=${{ inputs.php-version }} \
+            --env E2E_JP_SITE_ID=$E2E_JP_SITE_ID \
+            --env E2E_JP_BLOG_TOKEN=$E2E_JP_BLOG_TOKEN \
+            --env E2E_JP_USER_TOKEN=$E2E_JP_USER_TOKEN \
+            --verbose \
+            --wait \
+            -- --project=${{ inputs.playwright-project }}
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: qit-e2e-results-wp${{ inputs.wordpress-version }}-wc${{ inputs.woocommerce-version }}-php${{ inputs.php-version }}-${{ inputs.playwright-project }}
+          path: |
+            tests/qit/test-package/test-results/
+            qit-results/
+          retention-days: 7