|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is the Sentry Java/Android SDK - a comprehensive error monitoring and performance tracking SDK for Java and Android applications. The repository contains multiple modules for different integrations and platforms. |
| 8 | + |
| 9 | +## Build System |
| 10 | + |
| 11 | +The project uses **Gradle** with Kotlin DSL. Key build files: |
| 12 | +- `build.gradle.kts` - Root build configuration |
| 13 | +- `settings.gradle.kts` - Multi-module project structure |
| 14 | +- `buildSrc/` and `build-logic/` - Custom build logic and plugins |
| 15 | +- `Makefile` - High-level build commands |
| 16 | + |
| 17 | +## Essential Commands |
| 18 | + |
| 19 | +### Development Workflow |
| 20 | +```bash |
| 21 | +# Format code and regenerate .api files (REQUIRED before committing) |
| 22 | +./gradlew spotlessApply apiDump |
| 23 | + |
| 24 | +# Run all tests and linter |
| 25 | +./gradlew check |
| 26 | + |
| 27 | +# Build entire project |
| 28 | +./gradlew build |
| 29 | + |
| 30 | +# Create coverage reports |
| 31 | +./gradlew jacocoTestReport koverXmlReportRelease |
| 32 | + |
| 33 | +# Generate documentation |
| 34 | +./gradlew aggregateJavadocs |
| 35 | +``` |
| 36 | + |
| 37 | +### Testing |
| 38 | +```bash |
| 39 | +# Run unit tests for a specific file |
| 40 | +./gradlew ':<module>:testDebugUnitTest' --tests="*<file name>*" --info |
| 41 | + |
| 42 | +# Run system tests (requires Python virtual env) |
| 43 | +make systemTest |
| 44 | + |
| 45 | +# Run specific test suites |
| 46 | +./gradlew :sentry-android-core:testDebugUnitTest |
| 47 | +./gradlew :sentry:test |
| 48 | +``` |
| 49 | + |
| 50 | +### Code Quality |
| 51 | +```bash |
| 52 | +# Check code formatting |
| 53 | +./gradlew spotlessJavaCheck spotlessKotlinCheck |
| 54 | + |
| 55 | +# Apply code formatting |
| 56 | +./gradlew spotlessApply |
| 57 | + |
| 58 | +# Update API dump files (after API changes) |
| 59 | +./gradlew apiDump |
| 60 | + |
| 61 | +# Dependency updates check |
| 62 | +./gradlew dependencyUpdates -Drevision=release |
| 63 | +``` |
| 64 | + |
| 65 | +### Android-Specific Commands |
| 66 | +```bash |
| 67 | +# Assemble Android test APKs |
| 68 | +./gradlew :sentry-android-integration-tests:sentry-uitest-android:assembleRelease |
| 69 | +./gradlew :sentry-android-integration-tests:sentry-uitest-android:assembleAndroidTest -DtestBuildType=release |
| 70 | + |
| 71 | +# Run critical UI tests |
| 72 | +./scripts/test-ui-critical.sh |
| 73 | +``` |
| 74 | + |
| 75 | +## Development Workflow Rules |
| 76 | + |
| 77 | +### Planning and Implementation Process |
| 78 | +1. **First think through the problem**: Read the codebase for relevant files and propose a plan |
| 79 | +2. **Check in before beginning**: Verify the plan before starting implementation |
| 80 | +3. **Use todo tracking**: Work through todo items, marking them as complete as you go |
| 81 | +4. **High-level communication**: Give high-level explanations of changes made, not step-by-step descriptions |
| 82 | +5. **Simplicity first**: Make every task and code change as simple as possible. Avoid massive or complex changes. Impact as little code as possible. |
| 83 | +6. **Format and regenerate**: Once done, format code and regenerate .api files: `./gradlew spotlessApply apiDump` |
| 84 | +7. **Propose commit**: As final step, git stage relevant files and propose (but not execute) a single git commit command |
| 85 | + |
| 86 | +## Module Architecture |
| 87 | + |
| 88 | +The repository is organized into multiple modules: |
| 89 | + |
| 90 | +### Core Modules |
| 91 | +- **`sentry`** - Core Java SDK implementation |
| 92 | +- **`sentry-android-core`** - Core Android SDK implementation |
| 93 | +- **`sentry-android`** - High-level Android SDK |
| 94 | + |
| 95 | +### Integration Modules |
| 96 | +- **Spring Framework**: `sentry-spring*`, `sentry-spring-boot*` |
| 97 | +- **Logging**: `sentry-logback`, `sentry-log4j2`, `sentry-jul` |
| 98 | +- **Web**: `sentry-servlet*`, `sentry-okhttp`, `sentry-apache-http-client-5` |
| 99 | +- **GraphQL**: `sentry-graphql*`, `sentry-apollo*` |
| 100 | +- **Android UI**: `sentry-android-fragment`, `sentry-android-navigation`, `sentry-compose` |
| 101 | +- **Reactive**: `sentry-reactor`, `sentry-ktor-client` |
| 102 | +- **Monitoring**: `sentry-opentelemetry*`, `sentry-quartz` |
| 103 | + |
| 104 | +### Utility Modules |
| 105 | +- **`sentry-test-support`** - Shared test utilities |
| 106 | +- **`sentry-system-test-support`** - System testing infrastructure |
| 107 | +- **`sentry-samples`** - Example applications |
| 108 | +- **`sentry-bom`** - Bill of Materials for dependency management |
| 109 | + |
| 110 | +### Key Architectural Patterns |
| 111 | +- **Multi-platform**: Supports JVM, Android, and Kotlin Multiplatform (Compose modules) |
| 112 | +- **Modular Design**: Each integration is a separate module with minimal dependencies |
| 113 | +- **Options Pattern**: Features are opt-in via `SentryOptions` and similar configuration classes |
| 114 | +- **Transport Layer**: Pluggable transport implementations for different environments |
| 115 | +- **Scope Management**: Thread-safe scope/context management for error tracking |
| 116 | + |
| 117 | +## Development Guidelines |
| 118 | + |
| 119 | +### Code Style |
| 120 | +- **Languages**: Java 8+ and Kotlin |
| 121 | +- **Formatting**: Enforced via Spotless - always run `./gradlew spotlessApply` before committing |
| 122 | +- **API Compatibility**: Binary compatibility is enforced - run `./gradlew apiDump` after API changes |
| 123 | + |
| 124 | +### Testing Requirements |
| 125 | +- Write comprehensive unit tests for new features |
| 126 | +- Android modules require both unit tests and instrumented tests where applicable |
| 127 | +- System tests validate end-to-end functionality with sample applications |
| 128 | +- Coverage reports are generated for both JaCoCo (Java/Android) and Kover (KMP modules) |
| 129 | + |
| 130 | +### Contributing Guidelines |
| 131 | +1. Follow existing code style and language |
| 132 | +2. Do not modify API files (e.g. sentry.api) manually - run `./gradlew apiDump` to regenerate them |
| 133 | +3. Write comprehensive tests |
| 134 | +4. New features must be **opt-in by default** - extend `SentryOptions` or similar Option classes with getters/setters |
| 135 | +5. Consider backwards compatibility |
| 136 | + |
| 137 | +## Domain-Specific Knowledge Areas |
| 138 | + |
| 139 | +For complex SDK functionality, refer to the detailed cursor rules in `.cursor/rules/`: |
| 140 | + |
| 141 | +- **Scopes and Hub Management**: See `.cursor/rules/scopes.mdc` for details on `IScopes`, scope types (global/isolation/current), thread-local storage, forking behavior, and v7→v8 migration patterns |
| 142 | +- **Event Deduplication**: See `.cursor/rules/deduplication.mdc` for `DuplicateEventDetectionEventProcessor` and `enableDeduplication` option |
| 143 | +- **Offline Behavior and Caching**: See `.cursor/rules/offline.mdc` for envelope caching, retry logic, transport behavior, and Android vs JVM differences |
| 144 | +- **OpenTelemetry Integration**: See `.cursor/rules/opentelemetry.mdc` for agent vs agentless modes, span processing, context propagation, and configuration |
| 145 | +- **System Testing (E2E)**: See `.cursor/rules/e2e_tests.mdc` for system test framework, mock server setup, and CI workflows |
| 146 | + |
| 147 | +### Usage Pattern |
| 148 | +When working on these specific areas, read the corresponding cursor rule file first to understand the detailed architecture, then proceed with implementation. |
| 149 | + |
| 150 | +## Useful Resources |
| 151 | + |
| 152 | +- Main SDK documentation: https://develop.sentry.dev/sdk/overview/ |
| 153 | +- Internal contributing guide: https://docs.sentry.io/internal/contributing/ |
| 154 | +- Git commit message conventions: https://develop.sentry.dev/engineering-practices/commit-messages/ |
| 155 | + |
| 156 | +This SDK is production-ready and used by thousands of applications. Changes should be thoroughly tested and maintain backwards compatibility. |
0 commit comments