Add changelog for 8.x (alpha) release (#3421)

* changelog and more deprecation javadoc

* Update CHANGELOG.md

Co-authored-by: Markus Hintersteiner <[email protected]>

---------

Co-authored-by: Markus Hintersteiner <[email protected]>

Author: adinauer

CHANGELOG.md

@@ -2,6 +2,55 @@
 
 ## Unreleased
 
+Version 8 of the Sentry Android/Java SDK brings a variety of features and fixes. The most notable changes are:
+
+- New `Scope` types have been introduced, see "Behavioural Changes" for more details.
+- Lifecycle tokens have been introduced to manage `Scope` lifecycle, see "Behavioural Changes" for more details.
+- `Hub` has been replaced by `Scopes`
+
+### Behavioural Changes
+
+- We're introducing some new `Scope` types in the SDK, allowing for better control over what data is attached where. Previously there was a stack of scopes that was pushed and popped. Instead we now fork scopes for a given lifecycle and then restore the previous scopes. Since `Hub` is gone, it is also never cloned anymore. Separation of data now happens through the different scope types while making it easier to manipulate exactly what you need without having to attach data at the right time to have it apply where wanted.
+    - Global scope is attached to all events created by the SDK. It can also be modified before `Sentry.init` has been called. It can be manipulated using `Sentry.configureScope(ScopeType.GLOBAL, (scope) -> { ... })`.
+    - Isolation scope can be used e.g. to attach data to all events that come up while handling an incoming request. It can also be used for other isolation purposes. It can be manipulated using `Sentry.configureScope(ScopeType.ISOLATION, (scope) -> { ... })`. The SDK automatically forks isolation scope in certain cases like incoming requests, CRON jobs, Spring `@Async` and more.
+    - Current scope is forked often and data added to it is only added to events that are created while this scope is active. Data is also passed on to newly forked child scopes but not to parents.
+- `Sentry.popScope` has been deprecated, please call `.close()` on the token returned by `Sentry.pushScope` instead or use it in a way described in more detail in "Migration Guide".
+- We have chosen a default scope that is used for `Sentry.configureScope()` as well as API like `Sentry.setTag()`
+    - For Android the type defaults to `CURRENT` scope
+    - For Backend and other JVM applicatons it defaults to `ISOLATION` scope
+- Event processors on `Scope` can now be ordered by overriding the `getOrder` method on implementations of `EventProcessor`. NOTE: This order only applies to event processors on `Scope` but not `SentryOptions` at the moment. Feel free to request this if you need it.
+- `Hub` is deprecated in favor of `Scopes`, alongside some `Hub` relevant APIs. More details can be found in the "Migration Guide" section.
+
+### Breaking Changes
+
+- `Contexts` no longer extends `ConcurrentHashMap`, instead we offer a selected set of methods.
+
+### Migration Guide / Deprecations
+
+- `Hub` has been deprecated, we're replacing the following:
+    - `IHub` has been replaced by `IScopes`, however you should be able to simply pass `IHub` instances to code expecting `IScopes`, allowing for an easier migration.
+    - `HubAdapter.getInstance()` has been replaced by `ScopesAdapter.getInstance()`
+    - The `.clone()` method on `IHub`/`IScopes` has been deprecated, please use `.pushScope()` or `.pushIsolationScope()` instead
+    - Some internal methods like `.getCurrentHub()` and `.setCurrentHub()` have also been replaced.
+- `Sentry.popScope` has been replaced by calling `.close()` on the token returned by `Sentry.pushScope()` and `Sentry.pushIsolationScope()`. The token can also be used in a `try` block like this:
+
+```
+try (final @NotNull ISentryLifecycleToken ignored = Sentry.pushScope()) {
+  // this block has its separate current scope
+}
+```
+
+as well as:
+
+
+```
+try (final @NotNull ISentryLifecycleToken ignored = Sentry.pushIsolationScope()) {
+  // this block has its separate isolation scope
+}
+```
+
+You may also use `LifecycleHelper.close(token)`, e.g. in case you need to pass the token around for closing later.
+
 ### Features
 
 - Report exceptions returned by Throwable.getSuppressed() to Sentry as exception groups ([#3396] https://github.com/getsentry/sentry-java/pull/3396)

sentry-graphql/src/main/java/io/sentry/graphql/ExceptionReporter.java

@@ -149,6 +149,9 @@ public boolean isSubscription() {
       return isSubscription;
     }
 
+    /**
+     * @deprecated please use {@link ExceptionDetails#getScopes()} instead.
+     */
     @Deprecated
     public @NotNull IScopes getHub() {
       return scopes;

sentry-graphql/src/main/java/io/sentry/graphql/SentryInstrumentation.java

@@ -48,6 +48,9 @@ public final class SentryInstrumentation
           );
   public static final @NotNull String SENTRY_SCOPES_CONTEXT_KEY = "sentry.scopes";
 
+  /**
+   * @deprecated please use {@link SentryInstrumentation#SENTRY_SCOPES_CONTEXT_KEY} instead.
+   */
   @Deprecated
   public static final @NotNull String SENTRY_HUB_CONTEXT_KEY = SENTRY_SCOPES_CONTEXT_KEY;
 

sentry-spring-jakarta/src/main/java/io/sentry/spring/jakarta/webflux/AbstractSentryWebFilter.java

@@ -35,7 +35,12 @@
 public abstract class AbstractSentryWebFilter implements WebFilter {
   private final @NotNull SentryRequestResolver sentryRequestResolver;
   public static final String SENTRY_SCOPES_KEY = "sentry-scopes";
+
+  /**
+   * @deprecated please use {@link AbstractSentryWebFilter#SENTRY_SCOPES_KEY} instead.
+   */
   @Deprecated public static final String SENTRY_HUB_KEY = SENTRY_SCOPES_KEY;
+
   private static final String TRANSACTION_OP = "http.server";
 
   public AbstractSentryWebFilter(final @NotNull IScopes scopes) {

sentry-spring/src/main/java/io/sentry/spring/webflux/SentryWebFilter.java

@@ -35,7 +35,11 @@
 @ApiStatus.Experimental
 public final class SentryWebFilter implements WebFilter {
   public static final String SENTRY_SCOPES_KEY = "sentry-scopes";
+  /**
+   * @deprecated please use {@link SentryWebFilter#SENTRY_SCOPES_KEY} instead.
+   */
   @Deprecated public static final String SENTRY_HUB_KEY = SENTRY_SCOPES_KEY;
+
   private static final String TRANSACTION_OP = "http.server";
   private static final String TRACE_ORIGIN = "auto.spring.webflux";
 

sentry/src/main/java/io/sentry/HubAdapter.java

@@ -163,6 +163,10 @@ public void removeExtra(@NotNull String key) {
     return Sentry.pushIsolationScope();
   }
 
+  /**
+   * @deprecated please call {@link ISentryLifecycleToken#close()} on the token returned by {@link
+   *     ScopesAdapter#pushScope()} or {@link ScopesAdapter#pushIsolationScope()} instead.
+   */
   @Override
   @Deprecated
   public void popScope() {
@@ -199,6 +203,11 @@ public void flush(long timeoutMillis) {
     Sentry.flush(timeoutMillis);
   }
 
+  /**
+   * @deprecated please use {@link IScopes#forkedScopes(String)} or {@link
+   *     IScopes#forkedCurrentScope(String)} instead.
+   */
+  @Deprecated
   @Override
   public @NotNull IHub clone() {
     return Sentry.getCurrentScopes().clone();

sentry/src/main/java/io/sentry/HubScopesWrapper.java

@@ -158,6 +158,10 @@ public void removeExtra(@NotNull String key) {
     return scopes.pushIsolationScope();
   }
 
+  /**
+   * @deprecated please call {@link ISentryLifecycleToken#close()} on the token returned by {@link
+   *     IScopes#pushScope()} or {@link IScopes#pushIsolationScope()} instead.
+   */
   @Override
   @Deprecated
   public void popScope() {
@@ -194,7 +198,12 @@ public void flush(long timeoutMillis) {
     scopes.flush(timeoutMillis);
   }
 
+  /**
+   * @deprecated please use {@link IScopes#forkedScopes(String)} or {@link
+   *     IScopes#forkedCurrentScope(String)} instead.
+   */
   @Override
+  @Deprecated
   public @NotNull IHub clone() {
     return scopes.clone();
   }

sentry/src/main/java/io/sentry/NoOpHub.java

@@ -136,6 +136,10 @@ public void removeExtra(@NotNull String key) {}
     return NoOpScopesStorage.NoOpScopesLifecycleToken.getInstance();
   }
 
+  /**
+   * @deprecated please call {@link ISentryLifecycleToken#close()} on the token returned by {@link
+   *     IScopes#pushScope()} or {@link IScopes#pushIsolationScope()} instead.
+   */
   @Override
   @Deprecated
   public void popScope() {}
@@ -164,6 +168,11 @@ public boolean isHealthy() {
   @Override
   public void flush(long timeoutMillis) {}
 
+  /**
+   * @deprecated please use {@link IScopes#forkedScopes(String)} or {@link
+   *     IScopes#forkedCurrentScope(String)} instead.
+   */
+  @Deprecated
   @Override
   public @NotNull IHub clone() {
     return instance;

sentry/src/main/java/io/sentry/NoOpScopes.java

@@ -131,6 +131,10 @@ public void removeExtra(@NotNull String key) {}
     return NoOpScopesStorage.NoOpScopesLifecycleToken.getInstance();
   }
 
+  /**
+   * @deprecated please call {@link ISentryLifecycleToken#close()} on the token returned by {@link
+   *     IScopes#pushScope()} or {@link IScopes#pushIsolationScope()} instead.
+   */
   @Override
   @Deprecated
   public void popScope() {}
@@ -159,6 +163,10 @@ public boolean isHealthy() {
   @Override
   public void flush(long timeoutMillis) {}
 
+  /**
+   * @deprecated please use {@link IScopes#forkedScopes(String)} or {@link
+   *     IScopes#forkedCurrentScope(String)} instead.
+   */
   @Deprecated
   @Override
   public @NotNull IHub clone() {

sentry/src/main/java/io/sentry/Scopes.java

@@ -607,6 +607,10 @@ public ISentryLifecycleToken pushIsolationScope() {
     return Sentry.setCurrentScopes(this);
   }
 
+  /**
+   * @deprecated please call {@link ISentryLifecycleToken#close()} on the token returned by {@link
+   *     IScopes#pushScope()} or {@link IScopes#pushIsolationScope()} instead.
+   */
   @Override
   @Deprecated
   public void popScope() {
@@ -715,7 +719,12 @@ public void flush(long timeoutMillis) {
     }
   }
 
+  /**
+   * @deprecated please use {@link IScopes#forkedScopes(String)} or {@link
+   *     IScopes#forkedCurrentScope(String)} instead.
+   */
   @Override
+  @Deprecated
   @SuppressWarnings("deprecation")
   public @NotNull IHub clone() {
     if (!isEnabled()) {