chore: Adjust grammer and formatting of migration doc

AbhiPrasad · AbhiPrasad · commit 62993b76d88a · 2025-01-13T18:05:10.000-05:00
diff --git a/docs/migration/v8-to-v9.md b/docs/migration/v8-to-v9.md
@@ -2,7 +2,7 @@
 
 **DISCLAIMER: THIS MIGRATION GUIDE IS WORK IN PROGRESS**
 
-Version 9 of the Sentry SDK concerns itself with API cleanup and compatibility updates.
+Version 9 of the Sentry SDK concerns API cleanup and compatibility updates.
 This update contains behavioral changes that will not be caught by TypeScript or linters, so we recommend carefully reading the section on [Behavioral Changes](#2-behavior-changes).
 
 Before updating to version `9.x` of the SDK, we recommend upgrading to the latest version of `8.x`.
@@ -14,14 +14,14 @@ Lower versions may continue to work, but may not support all features.
 ## 1. Version Support Changes:
 
 Version 9 of the Sentry SDK has new compatibility ranges for runtimes and frameworks.
-We periodically update the compatibility ranges in major versions to increase reliability and quality of APIs and instrumentation data.
+We periodically update the compatibility ranges in major versions to increase the reliability and quality of APIs and instrumentation data.
 
 ### General Runtime Support Changes
 
-**ECMAScript Version:** All of the JavaScript code in the Sentry SDK packages may now contain ECMAScript 2020 features.
+**ECMAScript Version:** All the JavaScript code in the Sentry SDK packages may now contain ECMAScript 2020 features.
 This includes features like Nullish Coalescing (`??`), Optional Chaining (`?.`), `String.matchAll()`, Logical Assignment Operators (`&&=`, `||=`, `??=`), and `Promise.allSettled()`.
 
-If you observe failures due to syntax or features listed above, it may be an indicator that your current runtime does not support ES2020.
+If you observe failures due to syntax or features listed above, it may indicate that your current runtime does not support ES2020.
 If your runtime does not support ES2020, we recommend transpiling the SDK using Babel or similar tooling.
 
 **Node.js:** The minimum supported Node.js version is **18.0.0**, except for ESM-only SDKs (nuxt, solidstart, astro) which require Node **18.19.1** or up.
@@ -94,15 +94,17 @@ startSpan({ name: 'example', scope: customScope }, () => {
 
 ### `@sentry/node`
 
-- When `skipOpenTelemetrySetup: true` is configured, `httpIntegration({ spans: false })` will be configured by default. This means that you no longer have to specify this yourself in this scenario. With this change, no spans are emitted once `skipOpenTelemetrySetup: true` is configured, without any further configuration being needed.
+- When `skipOpenTelemetrySetup: true` is configured, `httpIntegration({ spans: false })` will be configured by default.
+
+This means that you no longer have to specify this yourself in this scenario. With this change, no spans are emitted once `skipOpenTelemetrySetup: true` is configured, without any further configuration being needed.
 
 - The `requestDataIntegration` will no longer automatically set the user from `request.user`. This is an express-specific, undocumented behavior, and also conflicts with our privacy-by-default strategy. Starting in v9, you'll need to manually call `Sentry.setUser()` e.g. in a middleware to set the user on Sentry events.
 
 - The `tracesSampler` hook will no longer be called for _every_ span. Instead, it will only be called for "root spans". Root spans are spans that have no local parent span. Root spans may however have incoming trace data from a different service, for example when using distributed tracing.
 
 ### `@sentry/browser`
 
-- The `captureUserFeedback` method has been removed. Use `captureFeedback` instead and update the `comments` field to `message`.
+- The `captureUserFeedback` method has been removed. Use the `captureFeedback` method instead and update the `comments` field to `message`.
 
 ### `@sentry/nextjs`
 
@@ -130,7 +132,7 @@ TODO
 
 ## 3. Package Removals
 
-As part of an architectural cleanup we deprecated the following packages:
+As part of an architectural cleanup, we deprecated the following packages:
 
 - `@sentry/utils`
 - `@sentry/types`
@@ -139,7 +141,7 @@ All of these packages exports and APIs have been moved into the `@sentry/core` p
 
 The `@sentry/utils` package will no longer be published.
 
-The `@sentry/types` package will continue to be published but it is deprecated and we don't plan on extending its APi.
+The `@sentry/types` package will continue to be published but it is deprecated and we don't plan on extending its API.
 You may experience slight compatibility issues in the future by using it.
 We decided to keep this package around to temporarily lessen the upgrade burden.
 It will be removed in a future major version.
@@ -166,18 +168,17 @@ Sentry.init({
 
 - The `DEFAULT_USER_INCLUDES` constant has been removed.
 
-### `@sentry/react`
+### `@sentry/browser`
 
-- The `wrapUseRoutes` method has been removed. Use `wrapUseRoutesV6` or `wrapUseRoutesV7` instead depending on what version of react router you are using.
-- The `wrapCreateBrowserRouter` method has been removed. Use `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` depending on what version of react router you are using.
+- The `captureUserFeedback` method has been removed. Use the `captureFeedback` method instead and update the `comments` field to `message`.
 
 ### `@sentry/core`
 
 - The `getNumberOfUrlSegments` method has been removed. There is no replacement.
 - The `validSeverityLevels` export has been removed. There is no replacement.
 - The `makeFifoCache` method has been removed. There is no replacement.
 - The `arrayify` export has been removed. There is no replacement.
-- The `BAGGAGE_HEADER_NAME` export has been removed. Use `"baggage"` string constant directly instead.
+- The `BAGGAGE_HEADER_NAME` export has been removed. Use the `"baggage"` string constant directly instead.
 - The `flatten` export has been removed. There is no replacement.
 - The `urlEncode` method has been removed. There is no replacement.
 - The `getDomElement` method has been removed. There is no replacement.
@@ -193,46 +194,48 @@ The following changes are unlikely to affect users of the SDK. They are listed h
 
 - `client._prepareEvent()` now requires a currentScope & isolationScope to be passed as last arugments
 
-### `@sentry/browser`
-
-- The `captureUserFeedback` method has been removed. Use `captureFeedback` instead and update the `comments` field to `message`.
-
 ### `@sentry/nestjs`
 
-- Removed `WithSentry` decorator. Use `SentryExceptionCaptured` instead.
+- Removed `WithSentry` decorator. Use the `SentryExceptionCaptured` decorator instead.
 - Removed `SentryService`.
-  If you are using `@sentry/nestjs` you can safely remove any references to the `SentryService`.
-  If you are using another package migrate to `@sentry/nestjs` and remove the `SentryService` afterwards.
+  - If you are using `@sentry/nestjs` you can safely remove any references to the `SentryService`.
+  - If you are using another package migrate to `@sentry/nestjs` and remove the `SentryService` afterward.
 - Removed `SentryTracingInterceptor`.
-  If you are using `@sentry/nestjs` you can safely remove any references to the `SentryTracingInterceptor`.
-  If you are using another package migrate to `@sentry/nestjs` and remove the `SentryTracingInterceptor` afterwards.
+  - If you are using `@sentry/nestjs` you can safely remove any references to the `SentryTracingInterceptor`.
+  - If you are using another package migrate to `@sentry/nestjs` and remove the `SentryTracingInterceptor` afterward.
 - Removed `SentryGlobalGenericFilter`.
-  Use the `SentryGlobalFilter` instead.
-  The `SentryGlobalFilter` is a drop-in replacement.
+  - Use the `SentryGlobalFilter` instead.
+  - The `SentryGlobalFilter` is a drop-in replacement.
 - Removed `SentryGlobalGraphQLFilter`.
-  Use the `SentryGlobalFilter` instead.
-  The `SentryGlobalFilter` is a drop-in replacement.
+  - Use the `SentryGlobalFilter` instead.
+  - The `SentryGlobalFilter` is a drop-in replacement.
+
+### `@sentry/react`
+
+- The `wrapUseRoutes` method has been removed. Use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead depending on what version of react router you are using.
+- The `wrapCreateBrowserRouter` method has been removed. Use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods depending on what version of react router you are using.
 
 ## `@sentry/vue`
 
 - The options `tracingOptions`, `trackComponents`, `timeout`, `hooks` have been removed everywhere except in the `tracingOptions` option of `vueIntegration()`.
-  These options should now be set as follows:
-
-  ```ts
-  import * as Sentry from '@sentry/vue';
-
-  Sentry.init({
-    integrations: [
-      Sentry.vueIntegration({
-        tracingOptions: {
-          trackComponents: true,
-          timeout: 1000,
-          hooks: ['mount', 'update', 'unmount'],
-        },
-      }),
-    ],
-  });
-  ```
+
+These options should now be set as follows:
+
+```js
+import * as Sentry from '@sentry/vue';
+
+Sentry.init({
+  integrations: [
+    Sentry.vueIntegration({
+      tracingOptions: {
+        trackComponents: true,
+        timeout: 1000,
+        hooks: ['mount', 'update', 'unmount'],
+      },
+    }),
+  ],
+});
+```
 
 - The option `logErrors` in the `vueIntegration` has been removed. The Sentry Vue error handler will propagate the error to a user-defined error handler
   or just re-throw the error (which will log the error without modifying).
@@ -250,13 +253,25 @@ Let us know if this is causing issues in your setup by opening an issue on GitHu
 
 ### `@sentry/deno`
 
-- The import of Sentry from the deno registry has changed. Use `import * as Sentry from 'https://deno.land/x/sentry/build/index.mjs'` instead.
+- The import of Sentry from the deno registry has changed. Use the `import * as Sentry from 'https://deno.land/x/sentry/build/index.mjs'` import instead.
+
+```js
+// before
+import * as Sentry from 'https://deno.land/x/sentry/index.mjs';
+
+// after
+import * as Sentry from 'https://deno.land/x/sentry/build/index.mjs';
+```
 
 ## 6. Type Changes
 
 In v8, types have been exported from `@sentry/types`, while implementations have been exported from other classes.
+
 This led to some duplication, where we had to keep an interface in `@sentry/types`, while the implementation mirroring that interface was kept e.g. in `@sentry/core`.
-Since v9, the types have been merged into `@sentry/core`, which removed some of this duplication. This means that certain things that used to be a separate interface, will not expect an actual instance of the class/concrete implementation. This should not affect most users, unless you relied on passing things with a similar shape to internal methods. The following types are affected:
+
+Since v9, the types have been merged into `@sentry/core`, which removed some of this duplication. This means that certain things that used to be a separate interface, will not expect an actual instance of the class/concrete implementation.
+
+This should not affect most users unless you relied on passing things with a similar shape to internal methods. The following types are affected:
 
 - `Scope` now always expects the `Scope` class
 - The `TransactionNamingScheme` type has been removed. There is no replacement.
@@ -272,6 +287,7 @@ Since v9, the types have been merged into `@sentry/core`, which removed some of
 
 Version support timelines are stressful for anybody using the SDK, so we won't be defining one.
 Instead, we will be applying bug fixes and features to older versions as long as there is demand for them.
+
 We also hold ourselves to high standards security-wise, meaning that if any vulnerabilities are found, we will in almost all cases backport them.
 
 Note, that we will decide on a case-per-case basis, what gets backported or not.
@@ -290,22 +306,23 @@ The following outlines deprecations that were introduced in version 8 of the SDK
 
 - **Passing `undefined` to `tracesSampleRate` / `tracesSampler` / `enableTracing` will be handled differently in v9**
 
-  In v8, a setup like the following:
+In v8, explicitly setting `tracesSampleRate` (even if it is set to `undefined`) will result in tracing being _enabled_, although no spans will be generated.
+
+```ts
+Sentry.init({
+  tracesSampleRate: undefined,
+});
+```
 
-  ```ts
-  Sentry.init({
-    tracesSampleRate: undefined,
-  });
-  ```
+In v9, we will streamline this behavior so that passing `undefined` will result in tracing being disabled, the same as not passing the option at all.
 
-  Will result in tracing being _enabled_, although no spans will be generated.
-  In v9, we will streamline this behavior so that passing `undefined` will result in tracing being disabled, the same as not passing the option at all.
-  If you are relying on `undefined` being passed in and having tracing enabled because of this, you should update your config to set e.g. `tracesSampleRate: 0` instead, which will also enable tracing in v9.
+If you are relying on `undefined` being passed in and having tracing enabled because of this, you should update your config to set e.g. `tracesSampleRate: 0` instead, which will also enable tracing in v9.
 
 - **The `autoSessionTracking` option is deprecated.**
 
-  To enable session tracking, it is recommended to unset `autoSessionTracking` and ensure that either, in browser environments the `browserSessionIntegration` is added, or in server environments the `httpIntegration` is added.
-  To disable session tracking, it is recommended unset `autoSessionTracking` and to remove the `browserSessionIntegration` in browser environments, or in server environments configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`.
+To enable session tracking, it is recommended to unset `autoSessionTracking` and ensure that either, in browser environments the `browserSessionIntegration` is added, or in server environments the `httpIntegration` is added.
+
+To disable session tracking, it is recommended unset `autoSessionTracking` and to remove the `browserSessionIntegration` in browser environments, or in server environments configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`.
 
 - **The metrics API has been removed from the SDK.**
 
@@ -315,8 +332,7 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
 
 - **The `@sentry/utils` package has been deprecated. Import everything from `@sentry/core` instead.**
 
-- Deprecated `AddRequestDataToEventOptions.transaction`. This option effectively doesn't do anything anymore, and will
-  be removed in v9.
+- Deprecated `AddRequestDataToEventOptions.transaction`. This option effectively doesn't do anything anymore, and will be removed in v9.
 - Deprecated `TransactionNamingScheme` type.
 - Deprecated `validSeverityLevels`. Will not be replaced.
 - Deprecated `urlEncode`. No replacements.
@@ -325,7 +341,7 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
 - Deprecated `arrayify`. No replacements.
 - Deprecated `memoBuilder`. No replacements.
 - Deprecated `getNumberOfUrlSegments`. No replacements.
-- Deprecated `BAGGAGE_HEADER_NAME`. Use `"baggage"` string constant directly instead.
+- Deprecated `BAGGAGE_HEADER_NAME`. Use the `"baggage"` string constant directly instead.
 - Deprecated `makeFifoCache`. No replacements.
 - Deprecated `dynamicRequire`. No replacements.
 - Deprecated `flatten`. No replacements.
@@ -347,13 +363,13 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
 
 ## `@sentry/nestjs`
 
-- Deprecated `@WithSentry`. Use `@SentryExceptionCaptured` instead.
-- Deprecated `SentryTracingInterceptor`.
+- Deprecated the `@WithSentry` decorator. Use the `@SentryExceptionCaptured` decorator instead.
+- Deprecated the `SentryTracingInterceptor` method.
   If you are using `@sentry/nestjs` you can safely remove any references to the `SentryTracingInterceptor`.
-  If you are using another package migrate to `@sentry/nestjs` and remove the `SentryTracingInterceptor` afterwards.
+  If you are using another package migrate to `@sentry/nestjs` and remove the `SentryTracingInterceptor` afterward.
 - Deprecated `SentryService`.
   If you are using `@sentry/nestjs` you can safely remove any references to the `SentryService`.
-  If you are using another package migrate to `@sentry/nestjs` and remove the `SentryService` afterwards.
+  If you are using another package migrate to `@sentry/nestjs` and remove the `SentryService` afterward.
 - Deprecated `SentryGlobalGenericFilter`.
   Use the `SentryGlobalFilter` instead.
   The `SentryGlobalFilter` is a drop-in replacement.
@@ -377,48 +393,50 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
 ## `@sentry/vue`
 
 - Deprecated `tracingOptions`, `trackComponents`, `timeout`, `hooks` options everywhere other than in the `tracingOptions` option of the `vueIntegration()`.
-  These options should now be set as follows:
-
-  ```ts
-  import * as Sentry from '@sentry/vue';
-
-  Sentry.init({
-    integrations: [
-      Sentry.vueIntegration({
-        tracingOptions: {
-          trackComponents: true,
-          timeout: 1000,
-          hooks: ['mount', 'update', 'unmount'],
-        },
-      }),
-    ],
-  });
-  ```
+
+These options should now be set as follows:
+
+```ts
+import * as Sentry from '@sentry/vue';
+
+Sentry.init({
+  integrations: [
+    Sentry.vueIntegration({
+      tracingOptions: {
+        trackComponents: true,
+        timeout: 1000,
+        hooks: ['mount', 'update', 'unmount'],
+      },
+    }),
+  ],
+});
+```
 
 - Deprecated `logErrors` in the `vueIntegration`. The Sentry Vue error handler will propagate the error to a user-defined error handler
   or just re-throw the error (which will log the error without modifying).
 
 ## `@sentry/nuxt` and `@sentry/vue`
 
 - When component tracking is enabled, "update" spans are no longer created by default.
-  Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior.
-
-  ```ts
-  Sentry.init({
-    integrations: [
-      Sentry.vueIntegration({
-        tracingOptions: {
-          trackComponents: true,
-          hooks: [
-            'mount',
-            'update', // <--
-            'unmount',
-          ],
-        },
-      }),
-    ],
-  });
-  ```
+
+Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior.
+
+```ts
+Sentry.init({
+  integrations: [
+    Sentry.vueIntegration({
+      tracingOptions: {
+        trackComponents: true,
+        hooks: [
+          'mount',
+          'update', // <--
+          'unmount',
+        ],
+      },
+    }),
+  ],
+});
+```
 
 ## `@sentry/astro`
 
@@ -430,16 +448,16 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
 
 ## `@sentry/react`
 
-- Deprecated `wrapUseRoutes`. Use `wrapUseRoutesV6` or `wrapUseRoutesV7` instead.
-- Deprecated `wrapCreateBrowserRouter`. Use `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` instead.
+- Deprecated `wrapUseRoutes`. Use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead.
+- Deprecated `wrapCreateBrowserRouter`. Use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods instead.
 
 ## `@sentry/nextjs`
 
-- Deprecated `hideSourceMaps`. No replacements. The SDK emits hidden sourcemaps by default.
+- Deprecated the `hideSourceMaps` option. There are no replacements for this option. The SDK emits hidden sourcemaps by default.
 
 ## `@sentry/opentelemetry`
 
-- Deprecated `generateSpanContextForPropagationContext` in favor of doing this manually - we do not need this export anymore.
+- Deprecated the `generateSpanContextForPropagationContext` method. There are no replacements for this method.
 
 ## Server-side SDKs (`@sentry/node` and all dependents)
 
