docs: Add upgrade guide

Author: AbhiPrasad

CHANGELOG.md

@@ -3,6 +3,8 @@
 ## Unreleased
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
+- [react] feat: Export `createReduxEnhancer` to log redux actions as breadcrumbs, and attach state as an extra. (#2717)
+- [tracing] feat: `Add @sentry/tracing` (#2719)
 
 ## 5.19.2
 
@@ -17,8 +19,6 @@
 - [tracing] fix: APM CDN bundle expose startTransaction (#2726)
 - [browser] fix: Correctly remove all event listeners (#2725)
 - [tracing] fix: Add manual `DOMStringList` typing (#2718)
-- [react] feat: Export `createReduxEnhancer` to log redux actions as breadcrumbs, and attach state as an extra. (#2717)
-- [tracing] feat: `Add @sentry/tracing` (#2719)
 
 ## 5.19.0
 

packages/apm/README.md

@@ -19,4 +19,7 @@
 
 ## General
 
+Note: This package is deprecated in favour of `@sentry/tracing` and will be removed in a future major release. We are still
+publishing `@sentry/apm` packages for backwards compatibility.
+
 This package contains extensions to the `@sentry/hub` to enable APM related functionality. It also provides integrations for Browser and Node that provide a good experience out of the box.

packages/tracing/README.md

@@ -20,3 +20,55 @@
 ## General
 
 This package contains extensions to the `@sentry/hub` to enable Sentry AM related functionality. It also provides integrations for Browser and Node that provide a good experience out of the box.
+
+## Migrating from @sentry/apm to @sentry/tracing
+
+The `@sentry/tracing` package is the replacement to the `@sentry/apm` package. No functionality has changed between
+the packages, but there are some steps required for upgrade.
+
+First, you must update your imports from the `Tracing` integration to the `BrowserTracing` integration.
+
+```ts
+import * as Sentry from "@sentry/browser";
+import { Integrations } from "@sentry/tracing";
+
+Sentry.init({
+  integrations: [
+    new Integrations.BrowserTracing({}),
+  ]
+})
+```
+
+Next, if you were using the `beforeNavigate` option, the API has changed to this type:
+
+```ts
+/**
+ * beforeNavigate is called before a pageload/navigation transaction is created and allows for users
+ * to set a custom transaction context.
+ *
+ * If undefined is returned, a pageload/navigation transaction will not be created.
+ */
+beforeNavigate(context: TransactionContext): TransactionContext | undefined;
+```
+
+We removed the location argument, in favour of being able to see what the transaction context is on creation. You will
+have to access `window.location` yourself if you want to replicate that. In addition, if you return undefined in
+`beforeNavigate`, the transaction will not be created.
+
+```ts
+import * as Sentry from "@sentry/browser";
+import { Integrations } from "@sentry/tracing";
+
+Sentry.init({
+  integrations: [
+    new Integrations.BrowserTracing({
+      beforeNavigate: (ctx) => {
+        return {
+          ...ctx,
+          name: getTransactionName(ctx.name, window.location)
+        }
+      }
+    }),
+  ]
+})
+```

packages/tracing/src/browser/browsertracing.ts

@@ -47,7 +47,7 @@ export interface BrowserTracingOptions extends RequestInstrumentationOptions {
 
   /**
    * beforeNavigate is called before a pageload/navigation transaction is created and allows for users
-   * to set a custom navigation transaction name. Defaults behaviour is to return `window.location.pathname`.
+   * to set custom transaction context. Defaults behaviour is to return `window.location.pathname`.
    *
    * If undefined is returned, a pageload/navigation transaction will not be created.
    */