Merge branch 'main' into lcian/checkin-api-experimental

Author: lcian

.cursor/rules/new_module.mdc

@@ -0,0 +1,88 @@
+---
+description: Module Addition Rules for sentry-java
+alwaysApply: false
+---
+# Module Addition Rules for sentry-java
+
+## Overview
+
+This document outlines the complete process for adding a new module to the sentry-java repository. Follow these steps in order to ensure proper integration and release management.
+
+## Step-by-Step Process
+
+### 1. Create the Module Structure
+
+1. Create the new module, conforming to the existing naming conventions and build scripts
+
+2. Add the module to the include list in `settings.gradle.kts`
+
+If adding a `sentry-samples` module, also add it to the `ignoredProjects` list in the root `build.gradle.kts`:
+
+```kotlin
+ignoredProjects.addAll(
+    listOf(
+        // ... existing projects ...
+        "sentry-samples-{module-name}"
+    )
+)
+```
+
+3. If adding a JVM sample, add E2E (system) tests, following the structure we have in the existing JVM examples.
+   The test should then be added to `test/system-test-runner.py` and `.github/workflows/system-tests-backend.yml`.
+
+### 2. Create Module Documentation
+
+Create a `README.md` in the module directory with the following structure:
+
+```markdown
+# sentry-{module-name}
+
+This module provides an integration for [Technology/Framework Name].
+
+Please consult the documentation on how to install and use this integration in the Sentry Docs for [Android](https://docs.sentry.io/platforms/android/integrations/{module-name}/) or [Java](https://docs.sentry.io/platforms/java/tracing/instrumentation/{module-name}/).
+```
+
+The following tasks are required only when adding a module that isn't a sample.
+
+### 3. Update Main README.md
+
+Add the new module to the packages table in the main `README.md` with a placeholder link to the badge:
+
+```markdown
+| sentry-{module-name} | [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}) | |
+```
+
+Note that the badge will only work after the module is released to Maven Central.
+
+### 4. Add Documentation to docs.sentry.io
+
+Add the necessary documentation to [docs.sentry.io](https://docs.sentry.io):
+- For Java modules: Add to Java platform docs, usually in integrations section
+- For Android modules: Add to Android platform docs, usually in integrations section
+- Include installation instructions, configuration options, and usage examples
+
+### 5. Post release tasks
+
+Remind the user to perform the following tasks after the module is merged and released:
+
+1. Add the SDK to the Sentry release registry, following the instructions in the [sentry-release-registry README](https://github.com/getsentry/sentry-release-registry#adding-new-sdks)
+
+2. Add the module to `.craft.yml` in the `sdks` section:
+   ```yaml
+   sdks:
+     # ... existing modules ...
+     maven:io.sentry:sentry-{module-name}:
+   ```
+
+## Module Naming Conventions
+
+- Use kebab-case for module names: `sentry-{module-name}`
+- Follow existing patterns: `sentry-okhttp`, `sentry-apollo-4`, `sentry-spring-boot`
+- For version-specific modules, include the version: `sentry-apollo-3`, `sentry-apollo-4`
+
+## Important Notes
+
+1. **API Files**: Do not modify `.api` files manually. Run `./gradlew apiDump` to regenerate them
+2. **Backwards Compatibility**: Ensure new features are opt-in by default
+3. **Testing**: Write comprehensive tests for all new functionality
+4. **Documentation**: Always include proper documentation and examples

.cursor/rules/overview_dev.mdc

@@ -42,6 +42,8 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
   - `OtelSpanFactory`, `SentrySpanExporter`
   - Tracing, distributed tracing
 
+- **`new_module`**: Use when adding a new integration or sample module
+
 ### Testing
 - **`e2e_tests`**: Use when working with:
   - System tests, sample applications
@@ -58,5 +60,6 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
    - Scope/Hub/forking → `scopes`
    - Duplicate/dedup → `deduplication` 
    - OpenTelemetry/tracing/spans → `opentelemetry`
+   - new module/integration/sample → `new_module`
    - Cache/offline/network → `offline`
    - System test/e2e/sample → `e2e_tests`

.github/pull_request_template.md

@@ -6,13 +6,18 @@
 <!--- Why is this change required? What problem does it solve? -->
 <!--- If it fixes an open issue, please link to the issue here. -->
 
+<!--
+* resolves: #1234
+* resolves: LIN-1234
+-->
 
 ## :green_heart: How did you test it?
 
 
 ## :pencil: Checklist
 <!--- Put an `x` in the boxes that apply -->
 
+- [ ] I added GH Issue ID _&_ Linear ID
 - [ ] I added tests to verify the changes.
 - [ ] No new PII added or SDK only sends newly added PII if `sendDefaultPII` is enabled.
 - [ ] I updated the docs if needed.

sentry-android-distribution/build.gradle.kts

@@ -25,5 +25,8 @@ androidComponents.beforeVariants {
 
 dependencies {
   implementation(projects.sentry)
+  implementation(
+    libs.jetbrains.annotations
+  ) // Use implementation instead of compileOnly to override kotlin stdlib's version
   implementation(kotlin(Config.kotlinStdLib, Config.kotlinStdLibVersionAndroid))
 }

sentry-android-distribution/src/main/java/io/sentry/android/distribution/DistributionIntegration.kt

@@ -9,13 +9,15 @@ import io.sentry.Integration
 import io.sentry.SentryOptions
 import io.sentry.UpdateInfo
 import io.sentry.UpdateStatus
+import org.jetbrains.annotations.ApiStatus
 
 /**
  * The public Android SDK for Sentry Build Distribution.
  *
  * Provides functionality to check for app updates and download new versions from Sentry's preprod
  * artifacts system.
  */
+@ApiStatus.Experimental
 public class DistributionIntegration(context: Context) : Integration, IDistributionApi {
 
   private lateinit var scopes: IScopes

sentry/src/main/java/io/sentry/IDistributionApi.java

@@ -1,5 +1,6 @@
 package io.sentry;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -8,6 +9,7 @@
  * <p>Provides methods to check for app updates and download new versions from Sentry's preprod
  * artifacts system.
  */
+@ApiStatus.Experimental
 public interface IDistributionApi {
 
   /**

sentry/src/main/java/io/sentry/NoOpDistributionApi.java

@@ -1,8 +1,10 @@
 package io.sentry;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /** No-op implementation of IDistributionApi. Used when distribution module is not available. */
+@ApiStatus.Experimental
 public final class NoOpDistributionApi implements IDistributionApi {
 
   private static final NoOpDistributionApi instance = new NoOpDistributionApi();

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -602,6 +602,7 @@ public class SentryOptions {
    * SentryAndroidOptions, but there's a circular dependency issue between sentry-android-core and
    * sentry-android-distribution modules.
    */
+  @ApiStatus.Experimental
   public static final class DistributionOptions {
     /** Organization authentication token for API access */
     public String orgAuthToken = "";
@@ -2848,10 +2849,12 @@ public void setReplayController(final @Nullable ReplayController replayControlle
         replayController != null ? replayController : NoOpReplayController.getInstance();
   }
 
+  @ApiStatus.Experimental
   public @NotNull IDistributionApi getDistributionController() {
     return distributionController;
   }
 
+  @ApiStatus.Experimental
   public void setDistributionController(final @Nullable IDistributionApi distributionController) {
     this.distributionController =
         distributionController != null ? distributionController : NoOpDistributionApi.getInstance();
@@ -3567,10 +3570,12 @@ public interface BeforeSendLogCallback {
     }
   }
 
+  @ApiStatus.Experimental
   public @NotNull DistributionOptions getDistribution() {
     return distribution;
   }
 
+  @ApiStatus.Experimental
   public void setDistribution(final @NotNull DistributionOptions distribution) {
     this.distribution = distribution != null ? distribution : new DistributionOptions();
   }

sentry/src/main/java/io/sentry/UpdateInfo.java

@@ -1,8 +1,10 @@
 package io.sentry;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /** Information about an available app update. */
+@ApiStatus.Experimental
 public final class UpdateInfo {
   private final @NotNull String id;
   private final @NotNull String buildVersion;

sentry/src/main/java/io/sentry/UpdateStatus.java

@@ -1,8 +1,10 @@
 package io.sentry;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /** Represents the result of checking for app updates. */
+@ApiStatus.Experimental
 public abstract class UpdateStatus {
 
   /** Current app version is up to date, no update available. */