feat!: add scope merging mechanism

[giortzisg]

Description

This adds the scope merging mechanism by allocating a captureState object and copying all needed event attributes in place. This removes taking multiple scope clones on every capture.

The PR also includes breaking changes around EventModifier. The EventModifier was an agnostic modifier that was passed on ApplyToEvent. This duplicated the EventProcessor behavior and also complicated the scope merging mechanism, since we need to have a concrete *Scope type to merge the scopes. Furthermore, there is no documented behavior or signature for any EventModifier and this seems to be just the first archaic way to modify events before EventProcessor and BeforeSend hooks where a thing. Thus decided to remove this and have a concrete *Scope passed on ApplyToEvent. This behavior aligns with other sdks that pass a concrete scope.

This affects the public API with all the CaptureX methods now requiring a concrete scope to be passed, but further scope changes in the stack also change the CaptureX APIs to work with context.Context, so this change seems acceptable. Functionality isn't really removed but just shifted to BeforeSend hooks as intended.

Issues

• resolves: Add scope merging for global and isolation scopes #1369
• resolves: GO-155

Changelog Entry Instructions

To add a custom changelog entry, uncomment the section above. Supports:

• Single entry: just write text
• Multiple entries: use bullet points
• Nested bullets: indent 4+ spaces

For more details: custom changelog entries

Reminders

• Add GH Issue ID & Linear ID
• PR title should use conventional commit style (feat:, fix:, ref:, meta:)
• For external contributors: CONTRIBUTING.md, Sentry SDK development docs, Discord community

[linear-code]

GO-155

[szokeasaurusrex]

Admittedly only skimmed this, as the PR is quite huge, but I left a few questions

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5d18fe6. Configure here.}

[sentry]

Bug: When MaxBreadcrumbs is negative, mergeBreadcrumbs returns nil, which clears any pre-existing breadcrumbs on an event instead of preserving them.
_{Severity: MEDIUM}

Suggested Fix

Modify mergeBreadcrumbs to return the original eventBreadcrumbs slice unmodified when the limit is negative. This will preserve any breadcrumbs already on the event while correctly preventing new scope breadcrumbs from being added, aligning with the intended behavior of ignoring breadcrumbs.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: scope.go#L523-L526

Potential issue: When `MaxBreadcrumbs` is set to a negative value, the
`mergeBreadcrumbs` function unconditionally returns `nil`. This `nil` value is then
assigned to `event.Breadcrumbs` in the `applyToEvent` function. This action overwrites
and destroys any breadcrumbs that a user may have pre-populated on the event before it
was captured. The previous implementation would have preserved these existing
breadcrumbs, as it only appended scope breadcrumbs if they were present. This change
introduces a regression that causes the loss of user-provided data in a configuration
intended to ignore new breadcrumbs, not clear existing ones.