From 81ffadd3c9e9ab81acc9c8657f21d3e63c23a73c Mon Sep 17 00:00:00 2001
From: Olivier Biot <olivier.biot@me.com>
Date: Tue, 19 May 2026 20:53:38 +0800
Subject: [PATCH] ci: add docs-only status-check shim so docs PRs aren't
 blocked
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`main.yml` skips docs/media paths via `paths-ignore`, which leaves the
required `lint`/`test` checks unsatisfiable on docs-only PRs and BLOCKED
by branch protection. `main-docs.yml` is the mirror image: triggers only
on those paths, emits matching job names (`lint`, `test`) that succeed
immediately. Together the two workflows form a partition — exactly one
runs per push/PR.

Also tidies the now-stale header comment on `main.yml`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/main-docs.yml | 41 +++++++++++++++++++++++++++++++++
 .github/workflows/main.yml      | 12 ++++------
 2 files changed, 46 insertions(+), 7 deletions(-)
 create mode 100644 .github/workflows/main-docs.yml

diff --git a/.github/workflows/main-docs.yml b/.github/workflows/main-docs.yml
new file mode 100644
index 000000000..d653bb12d
--- /dev/null
+++ b/.github/workflows/main-docs.yml
@@ -0,0 +1,41 @@
+name: Build & Test
+# Status-check shim for docs-only PRs. `main.yml` skips docs/media paths via
+# `paths-ignore`, which leaves required `lint`/`test` checks unsatisfiable on
+# such PRs and BLOCKED by branch protection. This workflow is the mirror
+# image: triggers ONLY on those paths and emits matching job names that
+# succeed immediately. Together with `main.yml` the two form a partition —
+# exactly one runs per push/PR.
+#
+# Job names (`lint`, `test`) MUST match the names in `main.yml` and the
+# contexts required by the `master` ruleset.
+on:
+  push:
+    branches: [master]
+    paths:
+      - '*.md'
+      - 'media/**'
+      - 'packages/melonjs/DOC_README.md'
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      - '*.md'
+      - 'media/**'
+      - 'packages/melonjs/DOC_README.md'
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "docs-only change — skipping real lint"
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "docs-only change — skipping real test"
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index ddd013713..17196c30c 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -1,11 +1,9 @@
 name: Build & Test
-# Note: docs-only PRs (markdown / media changes) skip these jobs via
-# `paths-ignore`. If branch-protection rules require `lint`/`test` as
-# checks, those PRs end up BLOCKED with no checks ever running.
-# The proper fix is a status-check shim workflow emitting matching job
-# names with `success` for the same paths — until that lands, docs PRs
-# need an admin-merge or a no-op non-md commit (like this one) to nudge
-# CI into running. (PR #1442 — Capacitor icon — needed this nudge.)
+# Docs-only PRs (markdown / media changes) skip these jobs via `paths-ignore`.
+# Required `lint`/`test` checks are satisfied for those PRs by the shim in
+# `main-docs.yml`, which mirrors this file's path filters and emits matching
+# job names that succeed immediately. Together the two form a partition —
+# exactly one runs per push/PR.
 on:
   push:
     branches: [master]