Skip to content

Commit 59862ca

Browse files
markushimarkushi
authored
Merge branch 'main' into markushi/fix/kotlin-stdlib-dependency
2 parents 52914dd + 46ae35c commit 59862ca

File tree

1 file changed

+156
-0
lines changed

1 file changed

+156
-0
lines changed

‎CLAUDE.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
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

Comments
 (0)