feat: Update RN troubleshooting docs for promise polyfill fix

src/platforms/react-native/troubleshooting.mdx

@@ -6,11 +6,45 @@ sidebar_order: 1000
 
 ## Unhandled Promise Rejections
 
-Due to an issue with React Native's dependencies, unhandled promise rejections might not be correctly caught by Sentry. You will need to ensure that the version of `promise` that you use matches exactly with the version that React Native uses. If the versions do not match, our SDK might issue a warning:
+Due to an issue with React Native's dependencies, unhandled promise rejections might not be correctly caught by Sentry. If the promise rejection handler was not correctly attached, our SDK might issue a warning:
 
 > WARN: Unhandled promise rejections might not be caught by Sentry. Read about how to fix this on our troubleshooting docs.
 
-### How to ensure the version matches
+Otherwise, we will let you know that the handler is attached:
+
+> [Sentry] Unhandled promise rejections will be caught by Sentry.
+
+### Auto Patching (Default Behavior)
+
+By default we will patch the global `Promise` instance to ensure it matches exactly with the version that React Native uses.
+
+#### Using With Other Polyfills
+
+If you use a polyfilling library that patches the global `Promise` instance, you'll need to make sure you run the polyfill **after** `Sentry.init` is called.
+
+```js
+import allSettled from "promise.allsettled";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+});
+// Any Promise polyfilling must occur AFTER Sentry.init
+// This step globally patches Promise.
+allSettled.shim();
+
+// Separate core-js example
+import "core-js/stable/promise/all-settled";
+```
+
+Your linter might throw some errors here, but this step is necessary.
+
+#### Disable Auto Patching
+
+You can disable the global promise patching by passing `patchGlobalPromise: false` in either `Sentry.init` or the `ReactNativeErrorHandlers` integration. Note that if you disable our auto patching, to ensure that unhandled rejections are still caught, you will need to [manually force a package resolution](#manually-forcing-a-package-resolution).
+
+### Manually Forcing a Package Resolution
+
+You don't need to perform the steps below if you don't disable [auto patching](#auto-patching-default-behavior). You'll need to ensure that the version of `promise` that you use matches exactly with the version that React Native uses.
 
 1. Check the version of `promise` that your version of `react-native` uses. You can do this by going into `node_modules/react-native/package.json` and checking the version there, for example we find that it uses `^8.0.3`:
 
@@ -39,8 +73,7 @@ Package resolutions are currently only supporred by `yarn`. If you use `npm`, yo
 
 </Note>
 
-3. If the fix is successful, our SDK will no longer display the above warning. If you want to double check, you can put Sentry in debug mode with `debug: true`. If promise rejection handling is active, you will see the log below in your Javascript console:
-   > [Sentry] Unhandled promise rejections will be caught by Sentry.
+3. If the fix is successful, our SDK will no longer display the above warning and will indicate that promise rejections will be caught.
 
 ## Source Maps
 
@@ -59,7 +92,7 @@ Common fixes to this issue include:
 
 ### Source Maps With Hermes
 
-Although the build script should already handle this for you most of the time, you may need to perform some extra steps when using the source maps with the Hermes engine. [You can follow the guide here.](/platforms/react-native/manual-setup/hermes/#custom-source-maps). 
+Although the build script should already handle this for you most of the time, you may need to perform some extra steps when using the source maps with the Hermes engine. [You can follow the guide here.](/platforms/react-native/manual-setup/hermes/#custom-source-maps).
 
 ### Different Bundles for Different Platforms