|
| 1 | +--- |
| 2 | +description: Module Addition Rules for sentry-java |
| 3 | +alwaysApply: false |
| 4 | +--- |
| 5 | +# Module Addition Rules for sentry-java |
| 6 | + |
| 7 | +## Overview |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +## Step-by-Step Process |
| 12 | + |
| 13 | +### 1. Create the Module Structure |
| 14 | + |
| 15 | +1. Create the new module, conforming to the existing naming conventions and build scripts |
| 16 | + |
| 17 | +2. Add the module to the include list in `settings.gradle.kts` |
| 18 | + |
| 19 | +If adding a `sentry-samples` module, also add it to the `ignoredProjects` list in the root `build.gradle.kts`: |
| 20 | + |
| 21 | +```kotlin |
| 22 | +ignoredProjects.addAll( |
| 23 | + listOf( |
| 24 | + // ... existing projects ... |
| 25 | + "sentry-samples-{module-name}" |
| 26 | + ) |
| 27 | +) |
| 28 | +``` |
| 29 | + |
| 30 | +3. If adding a JVM sample, add E2E (system) tests, following the structure we have in the existing JVM examples. |
| 31 | + The test should then be added to `test/system-test-runner.py` and `.github/workflows/system-tests-backend.yml`. |
| 32 | + |
| 33 | +### 2. Create Module Documentation |
| 34 | + |
| 35 | +Create a `README.md` in the module directory with the following structure: |
| 36 | + |
| 37 | +```markdown |
| 38 | +# sentry-{module-name} |
| 39 | + |
| 40 | +This module provides an integration for [Technology/Framework Name]. |
| 41 | + |
| 42 | +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}/). |
| 43 | +``` |
| 44 | + |
| 45 | +The following tasks are required only when adding a module that isn't a sample. |
| 46 | + |
| 47 | +### 3. Update Main README.md |
| 48 | + |
| 49 | +Add the new module to the packages table in the main `README.md` with a placeholder link to the badge: |
| 50 | + |
| 51 | +```markdown |
| 52 | +| sentry-{module-name} | [](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}) | | |
| 53 | +``` |
| 54 | + |
| 55 | +Note that the badge will only work after the module is released to Maven Central. |
| 56 | + |
| 57 | +### 4. Add Documentation to docs.sentry.io |
| 58 | + |
| 59 | +Add the necessary documentation to [docs.sentry.io](https://docs.sentry.io): |
| 60 | +- For Java modules: Add to Java platform docs, usually in integrations section |
| 61 | +- For Android modules: Add to Android platform docs, usually in integrations section |
| 62 | +- Include installation instructions, configuration options, and usage examples |
| 63 | + |
| 64 | +### 5. Post release tasks |
| 65 | + |
| 66 | +Remind the user to perform the following tasks after the module is merged and released: |
| 67 | + |
| 68 | +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) |
| 69 | + |
| 70 | +2. Add the module to `.craft.yml` in the `sdks` section: |
| 71 | + ```yaml |
| 72 | + sdks: |
| 73 | + # ... existing modules ... |
| 74 | + maven:io.sentry:sentry-{module-name}: |
| 75 | + ``` |
| 76 | + |
| 77 | +## Module Naming Conventions |
| 78 | + |
| 79 | +- Use kebab-case for module names: `sentry-{module-name}` |
| 80 | +- Follow existing patterns: `sentry-okhttp`, `sentry-apollo-4`, `sentry-spring-boot` |
| 81 | +- For version-specific modules, include the version: `sentry-apollo-3`, `sentry-apollo-4` |
| 82 | + |
| 83 | +## Important Notes |
| 84 | + |
| 85 | +1. **API Files**: Do not modify `.api` files manually. Run `./gradlew apiDump` to regenerate them |
| 86 | +2. **Backwards Compatibility**: Ensure new features are opt-in by default |
| 87 | +3. **Testing**: Write comprehensive tests for all new functionality |
| 88 | +4. **Documentation**: Always include proper documentation and examples |
0 commit comments