sentry-java / rules

---
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.
   Copy the `build.gradle.kts` of the closest existing integration rather than writing one from
   scratch — `sentry-kafka` is a good JVM template, `sentry-android-timber` a good Android one.

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. Add a `SENTRY_{MODULE}_SDK_NAME` constant to the `Config.Sentry` block in
   `buildSrc/src/main/java/Config.kt`:

```kotlin
val SENTRY_FOO_SDK_NAME = "$SENTRY_JAVA_SDK_NAME.foo"
```

The module's `build.gradle.kts` consumes it in both `buildConfig` and the jar manifest
(`Sentry-SDK-Name` / `Sentry-SDK-Package-Name`) — see `sentry-kafka/build.gradle.kts`.

4. Add the instrumented library to `gradle/libs.versions.toml` and depend on it with
   `compileOnly(libs.<lib>)`, so the integration does not force the dependency on users.

5. Register the integration with the SDK so it is reported in the `sdk` payload. Every
   integration does this — see `sentry-openfeature/.../SentryOpenFeatureHook.java`:

```java
static {
  SentryIntegrationPackageStorage.getInstance()
      .addPackage("maven:io.sentry:sentry-{module-name}", BuildConfig.VERSION_NAME);
}
// then, from the constructor:
addIntegrationToSdkVersion("{IntegrationName}");
```

6. 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`.

`sentry-bom` and the root `build.gradle.kts` need no change — they iterate over subprojects.

### 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`. Copy the row of a neighbouring
module and swap the name — Android modules carry a third column for the min API level, JVM modules
do not:

```markdown
| sentry-{module-name} | [![Maven Central Version](https://img.shields.io/maven-central/v/io.sentry/sentry-{module-name}?style=for-the-badge&logo=sentry&color=green)](https://central.sonatype.com/artifact/io.sentry/sentry-{module-name}) |
```

Note that the badge will only work after the module is released to Maven Central.

### 4. Add the Module to the Issue Template

Add `- sentry-{module-name}` to the integrations dropdown in
`.github/ISSUE_TEMPLATE/bug_report_java.yml`, or `bug_report_android.yml` for an Android module.

### 5. 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

### 6. 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`