docs(replay): Add MIGRATION.md & add badges to README.md

MIGRATION.md

@@ -16,6 +16,10 @@ This is no longer used.
 
 This release deprecates `@sentry/hub` and all of it's exports. All of the `@sentry/hub` exports have moved to `@sentry/core`. `@sentry/hub` will be removed in the next major release.
 
+# Upgrading Sentry Replay (beta, 7.24.0)
+
+For details on upgrading Replay in its beta phase, please view the [dedicated Replay MIGRATION docs](./packages/replay/MIGRATION.md).
+
 # Upgrading from 6.x to 7.x
 
 The main goal of version 7 is to reduce bundle size. This version is breaking because we removed deprecated APIs, upgraded our build tooling, and restructured npm package contents.

packages/replay/MIGRATION.md

@@ -0,0 +1,54 @@
+# Upgrading Replay from 0.6.x to 7.24.0
+
+The Sentry Replay integration was moved to the Sentry JavaScript SDK monorepo. Hence we're jumping from version 0.x to the monorepo's 7.x version which is shared across all JS SDK packages.
+
+## Replay sample rates are defined on top level (https://github.com/getsentry/sentry-javascript/issues/6351)
+
+Instead of defining the sample rates on the integration like this:
+
+```js
+Sentry.init({
+  dsn: '__DSN__',
+  integrations: [
+    new Replay({
+      sessionSampleRate: 0.1,
+      errorSampleRate: 1.0,
+    })
+  ],
+  // ...
+});
+```
+
+They are now defined on the top level of the SDK:
+
+```js
+Sentry.init({
+  dsn: '__DSN__',
+  replaysSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+  integrations: [
+    new Replay({
+      // other replay config still goes in here
+    })
+  ],
+});
+```
+
+Note that the sample rate options inside of `new Replay({})` have been deprecated and will be removed in a future update.
+
+## Removed deprecated options (https://github.com/getsentry/sentry-javascript/pull/6370)
+
+Two options, which have been deprecated for some time, have been removed:
+
+* `replaysSamplingRate` - instead use `sessionSampleRate`
+* `captureOnlyOnError` - instead use `errorSampleRate`
+
+## New NPM package structure (https://github.com/getsentry/sentry-javascript/issues/6280)
+
+The internal structure of the npm package has changed. This is unlikely to affect you, unless you have imported something from e.g.:
+
+```js
+import something from '@sentry/replay/submodule';
+```
+
+If you only imported from `@sentry/replay`, this will not affect you.

packages/replay/README.md

@@ -1,10 +1,20 @@
+<p align="center">
+  <a href="https://sentry.io/?utm_source=github&utm_medium=logo" target="_blank">
+    <img src="https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png" alt="Sentry" width="280" height="84">
+  </a>
+</p>
+
 # Sentry Session Replay
 
-Note: Session Replay is currently in beta.
+[![npm version](https://img.shields.io/npm/v/@sentry/replay.svg)](https://www.npmjs.com/package/@sentry/replay)
+[![npm dm](https://img.shields.io/npm/dm/@sentry/replay.svg)](https://www.npmjs.com/package/@sentry/replay)
+[![npm dt](https://img.shields.io/npm/dt/@sentry/replay.svg)](https://www.npmjs.com/package/@sentry/replay)
+
+**Note: Session Replay is currently in beta.** Functionality may change outside of major version bumps - while we try our best to avoid any breaking changes, semver cannot be guaranteed before Replay is out of beta. You can find more information about upgrading in [MIGRATION.md](./MIGRATION.md).
 
 ## Pre-requisites
 
-For the sentry-replay integration to work, you must have the [Sentry browser SDK package](https://www.npmjs.com/package/@sentry/browser), or an equivalent framework SDK (e.g. [@sentry/react](https://www.npmjs.com/package/@sentry/react)) installed. The minimum version required for the SDK is `7.23.0`.
+For the sentry-replay integration to work, you must have the [Sentry browser SDK package](https://www.npmjs.com/package/@sentry/browser), or an equivalent framework SDK (e.g. [@sentry/react](https://www.npmjs.com/package/@sentry/react)) installed. The minimum version required for the SDK is `7.24.0`.
 
 Make sure to use the exact same version of `@sentry/replay` as your other Sentry package(s), e.g. `@sentry/browser` or `@sentry/react`.