From 6e9a6cee62ca50363d53dd8352d96fbf76ee89f4 Mon Sep 17 00:00:00 2001
From: Adam Gleitman <adgleitm@microsoft.com>
Date: Mon, 14 Jul 2025 12:01:05 -0700
Subject: [PATCH] ci(0.77): Add docs and CI checks for RN peer dependency

---
 .ado/apple-pr.yml | 18 ++++++++++++++++++
 docs/Releases.md  | 10 ++++++++++
 2 files changed, 28 insertions(+)

diff --git a/.ado/apple-pr.yml b/.ado/apple-pr.yml
index c8671f8441ea63..d35adf6177c5a0 100644
--- a/.ado/apple-pr.yml
+++ b/.ado/apple-pr.yml
@@ -34,3 +34,21 @@ stages:
   #   jobs:
   #     - template: /.ado/jobs/test-react-native-macos-init.yml@self
   #     - template: /.ado/jobs/react-native-test-app-integration.yml@self
+
+  - stage: Validate_Peer_Dependency
+    displayName: 'Validate Peer Dependency'
+    dependsOn: []
+    condition: and(succeeded(), contains(variables['System.PullRequest.TargetBranch'], '-stable'))
+    jobs:
+      - job: CheckRNPeerDependency
+        displayName: 'react-native'
+        pool:
+          vmImage: $(vmImageApple)
+        steps:
+          - script: |
+              set -eox pipefail
+              if ! jq -e '.peerDependencies["react-native"]' packages/react-native/package.json > /dev/null; then
+                echo "##vso[task.logissue type=error]react-native is not listed as a peerDependency in packages/react-native/package.json"
+                exit 1
+              fi
+            displayName: 'Validate peerDependency in package.json'
diff --git a/docs/Releases.md b/docs/Releases.md
index c70a7a795be474..187e1166a749e6 100644
--- a/docs/Releases.md
+++ b/docs/Releases.md
@@ -215,3 +215,13 @@ We do this so that our first release will have a proper patch version of 0, as s
 ```
 
 </details>
+
+## Hermes Compatibility (0.74 and above)
+
+*Note: This is only applicable if Hermes is enabled via the `USE_HERMES=1` environment variable when running `pod install`.*
+
+React Native macOS updates the patch version automatically for every change that comes through, so our patch number can differ wildly from that of vanilla React Native.
+
+To ensure the best possible Hermes compatibility, we specify a peer dependency in React Native macOS's `package.json` indicating which version of upstream React Native best corresponds with our own version. For example, our 0.74.34 corresponds to upstream's 0.74.7, and we reflect this connection in [this particular version of `package.json`](https://github.com/microsoft/react-native-macos/blob/2db3abeb5d4318fee3abdff4a4d1a68967223135/packages/react-native/package.json#L103).
+
+For stable branches, the existence of this peer dependency is enforced as part of our CIs.