migration note, formatting

Author: Lms24

docs/migration/v8-to-v9.md

@@ -82,6 +82,16 @@ In v9, an `undefined` value will be treated the same as if the value is not defi
 
 - The `getCurrentHub().getIntegration(IntegrationClass)` method will always return `null` in v9. This has already stopped working mostly in v8, because we stopped exposing integration classes. In v9, the fallback behavior has been removed. Note that this does not change the type signature and is thus not technically breaking, but still worth pointing out.
 
+- The `startSpan` behavior was slightly changed if you pass a custom `scope` to the span start options: While in v8, the passed scope was set active directly on the passed scope, in v9, the scope is cloned. This behavior change does not apply to `@sentry/node` where the scope was already cloned. This change was made to ensure that the span only remains active within the callback and to align behavior between `@sentry/node` and all other SDKs. As a result of the change, your span hierarchy should be more accurate. However, be aware that modifying the scope (e.g. set tags) within the `startSpan` callback behaves a bit differently now.
+
+```js
+startSpan({ name: 'example', scope: customScope }, () => {
+  getCurrentScope().setTag('tag-a', 'a'); // this tag will only remain within the callback
+  // set the tag directly on customScope in addition, if you want to to persist the tag outside of the callback
+  customScope.setTag('tag-a', 'a');
+});
+```
+
 ### `@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.

packages/core/src/types-hoist/startSpanOptions.ts

@@ -9,11 +9,12 @@ export interface StartSpanOptions {
    * If set, start the span on a fork of this scope instead of on the current scope.
    * To ensure proper span cleanup, the passed scope is cloned for the duration of the span.
    *
-   * If you want to modify the passed scope inside the callback, be aware that:
-   * - calling `getCurrentScope()` will return the cloned scope, meaning all modifications
-   *   will be reset once the callback finishes
-   * - if you want to modify the passed scope and have the changes persist after the callback
-   *   ends, modify the scope directly and don't use `getCurrentScope()`
+   * If you want to modify the passed scope inside the callback, calling `getCurrentScope()`
+   * will return the cloned scope, meaning all scope modifications will be reset once the
+   * callback finishes
+   *
+   * If you want to modify the passed scope and have the changes persist after the callback ends,
+   * modify the scope directly instead of using `getCurrentScope()`
    */
   scope?: Scope;
 

packages/core/test/lib/tracing/trace.test.ts

@@ -25,7 +25,7 @@ import {
 import { SentryNonRecordingSpan } from '../../../src/tracing/sentryNonRecordingSpan';
 import { startNewTrace } from '../../../src/tracing/trace';
 import type { Event, Span, StartSpanOptions } from '../../../src/types-hoist';
-import { _getSpanForScope, _setSpanForScope } from '../../../src/utils/spanOnScope';
+import { _setSpanForScope } from '../../../src/utils/spanOnScope';
 import { getActiveSpan, getRootSpan, getSpanDescendants, spanIsSampled } from '../../../src/utils/spanUtils';
 import { TestClient, getDefaultTestClientOptions } from '../../mocks/client';