Prefer stable version for docs app conflicts in backport workflow (#1791)

* Prefer stable version for docs app conflicts in backport workflow

After #1786 restored a minimal Next.js placeholder docs app on stable,
docs app conflicts should resolve to the stable branch version rather
than being deleted. Only docs/content/ is actively maintained on stable,
so conflicts there should still be resolved normally.

Update both the auto-resolution logic in backport.yml and the AI prompt
to reflect the new policy, and update AGENTS.md to match.

* Use git show :2:$file to detect ours-side presence in conflicts

git ls-files --error-unmatch succeeds for unmerged paths even when
the file only exists on the incoming (theirs) side, which would then
fail on git checkout --ours. Use git show :2:$file to specifically
check for a stage-2 entry, which indicates the file exists on the
ours (stable) side.

Author: TooTallNate

.github/workflows/backport.yml

@@ -47,12 +47,22 @@ jobs:
             echo "status=clean" >> "$GITHUB_OUTPUT"
             echo "cherry_pick_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
           else
-            # The docs app is not maintained on the stable branch (only
-            # docs/content/ is kept for npm prepack scripts). Auto-resolve
-            # any non-content docs/ conflicts by deleting the files.
+            # The docs app on the stable branch is a minimal placeholder —
+            # only docs/content/ is actively maintained (markdown files
+            # bundled into npm packages via prepack scripts). Auto-resolve
+            # any non-content docs/ conflicts by keeping the stable branch
+            # version (discarding the incoming change from main).
             git diff --name-only --diff-filter=U | grep '^docs/' | grep -v '^docs/content/' | while IFS= read -r file; do
-              echo "Auto-resolving docs conflict (deleting): $file"
-              git rm -f -- "$file"
+              echo "Auto-resolving docs conflict (keeping stable version): $file"
+              # Check for a stage-2 ("ours") entry in the index, which means
+              # the file exists on the stable side of the conflict. Otherwise
+              # the file was newly added on main and we drop it.
+              if git show ":2:$file" >/dev/null 2>&1; then
+                git checkout --ours -- "$file"
+                git add -- "$file"
+              else
+                git rm -f -- "$file"
+              fi
             done || true
 
             # Lockfile conflicts can be resolved by re-running pnpm install,
@@ -110,11 +120,14 @@ jobs:
           PR title: $PR_TITLE
           Commit message: $COMMIT_MSG
 
-          IMPORTANT: Only docs/content/ exists on the stable branch (the rest
-          of the docs app is removed). If any remaining conflicts involve files
-          under docs/ that are NOT in docs/content/, resolve them by deleting
-          the file with "git rm". Conflicts in docs/content/ should be resolved
-          normally (these are markdown files bundled into npm packages).
+          IMPORTANT: On the stable branch, only docs/content/ is actively
+          maintained (markdown files bundled into npm packages). The rest of
+          the docs app is a minimal placeholder. If any remaining conflicts
+          involve files under docs/ that are NOT in docs/content/, resolve
+          them by keeping the stable branch version (the <<<<<<< HEAD side)
+          and discarding the incoming change from main. If the file does not
+          exist on the stable side (HEAD side is empty), remove it with
+          "git rm". Conflicts in docs/content/ should be resolved normally.
 
           Resolve all merge conflicts in the working tree. The content between
           <<<<<<< HEAD and ======= is the current stable branch. The content between

AGENTS.md

@@ -173,7 +173,7 @@ This repository uses a dual-branch release model with [changesets](https://githu
 
 Both branches trigger the release workflow (`.github/workflows/release.yml`) on push. The changesets action creates a "Version Packages" PR on each branch when there are pending changesets.
 
-**Important:** The docs app (everything under `docs/` except `docs/content/`) is **not maintained on the `stable` branch**. Documentation is deployed only from `main`. The `docs/content/` directory is kept on `stable` because the markdown files are bundled into npm packages via `prepack` scripts. When backporting changes to `stable`, any conflicts involving docs app files (outside of `docs/content/`) should be resolved by deleting the conflicting files. Conflicts in `docs/content/` should be resolved normally. The backport GitHub Action handles this automatically.
+**Important:** On the `stable` branch, only `docs/content/` is actively maintained — the rest of the docs app is a minimal placeholder. Documentation is deployed only from `main`. The `docs/content/` directory is kept on `stable` because the markdown files are bundled into npm packages via `prepack` scripts. When backporting changes to `stable`, any conflicts involving docs app files (outside of `docs/content/`) should be resolved by keeping the `stable` branch version (discarding the incoming change from `main`). Conflicts in `docs/content/` should be resolved normally. The backport GitHub Action handles this automatically.
 
 ### Changesets
 
@@ -192,7 +192,7 @@ Both branches trigger the release workflow (`.github/workflows/release.yml`) on
 
 To backport a change from `main` to `stable`, add the `backport-stable` label to the PR on `main`. A GitHub Action (`.github/workflows/backport.yml`) will automatically cherry-pick the squashed commit to `stable`. The label can be added before or after merging — the action triggers on both merge and label events. The changeset file is included in the cherry-pick, so the correct semver bump type is preserved on `stable`.
 
-If the cherry-pick fails due to conflicts, the action first auto-resolves any docs app conflicts (files under `docs/` except `docs/content/`, since the docs app is not maintained on `stable`) and `pnpm-lock.yaml` conflicts (by re-running `pnpm install`). If those resolve everything, the cherry-pick is pushed directly to `stable`. Otherwise, it attempts to resolve remaining conflicts using [opencode](https://opencode.ai) (AI-powered conflict resolution). If successful, it creates a PR targeting `stable` for human review instead of pushing directly. If the AI cannot resolve the conflicts, the action will comment on the original PR with instructions for manual resolution.
+If the cherry-pick fails due to conflicts, the action first auto-resolves any docs app conflicts (files under `docs/` except `docs/content/`) by keeping the `stable` branch version, since the docs app is a minimal placeholder on `stable` and not actively maintained there. It also auto-resolves `pnpm-lock.yaml` conflicts by re-running `pnpm install`. If those resolve everything, the cherry-pick is pushed directly to `stable`. Otherwise, it attempts to resolve remaining conflicts using [opencode](https://opencode.ai) (AI-powered conflict resolution). If successful, it creates a PR targeting `stable` for human review instead of pushing directly. If the AI cannot resolve the conflicts, the action will comment on the original PR with instructions for manual resolution.
 
 ### Pre-release Lifecycle