ci: enforce RN peer dependency in stable branches

Author: Adam Gleitman

.ado/apple-pr.yml

@@ -28,6 +28,24 @@ stages:
       - template: /.ado/jobs/test-javascript.yml@self
       - template: /.ado/jobs/npm-publish-dry-run.yml@self
 
+  - stage: Validate_Peer_Dependency
+    displayName: 'Validate react-native Peer Dependency on Stable Branches'
+    dependsOn: []
+    condition: and(succeeded(), contains(variables['System.PullRequest.TargetBranch'], '-stable'))
+    jobs:
+      - job: CheckPeerDependency
+        displayName: 'Check react-native in peerDependencies'
+        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'
+
   # https://github.com/microsoft/react-native-macos/issues/2344
   # The Verdaccio server consistently hangs on creation, which is required for the integration tests
   # - stage: Integration

docs/Releases.md

@@ -221,3 +221,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.