diff --git a/.cursor/rules/coding.mdc b/.cursor/rules/coding.mdc deleted file mode 100644 index 70ac39e43a..0000000000 --- a/.cursor/rules/coding.mdc +++ /dev/null @@ -1,53 +0,0 @@ ---- -alwaysApply: true -description: Cursor Coding Rules ---- - -# Contributing Rules for Agents - -## Overview - -sentry-java is the Java and Android SDK for Sentry. This repository contains the source code and examples for SDK usage. - -## Tech Stack - -- **Language**: Java and Kotlin -- **Build Framework**: Gradle - -## Key Commands - -```bash -# Format code and regenerate .api files -./gradlew spotlessApply apiDump - -# Run all tests and linter -./gradlew check - -# Run unit tests for a specific file -./gradlew '::testReleaseUnitTest' --tests="**" --info -``` - -## Contributing Guidelines - -1. Follow existing code style and language -2. Do not modify the API files (e.g. sentry.api) manually, instead run `./gradlew apiDump` to regenerate them -3. Write comprehensive tests. For assertions in new unit tests, prefer Google Truth (`com.google.common.truth.Truth.assertThat`) over `kotlin.test`/JUnit assertions; keep `kotlin.test` for test structure like `@Test` and `assertFailsWith`. Add `testImplementation(libs.google.truth)` to a module's `build.gradle.kts` if it isn't already present. -4. New features should always be opt-in by default, extend `SentryOptions` or similar Option classes with getters and setters to enable/disable a new feature -5. Consider backwards compatibility - -## Coding rules - -1. First think through the problem, read the codebase for relevant files, and propose a plan -2. Before you begin working, check in with me and I will verify the plan -3. Then, begin working on the todo items, marking them as complete as you go -4. Please do not describe every step of the way and just give me a high level explanation of what changes you made -5. Make every task and code change you do as simple as possible. We want to avoid making any massive or complex changes. Every change should impact as little code as possible. Everything is about simplicity. -6. Once you're done, format the code and regenerate the .api files using the following command `./gradlew spotlessApply apiDump` -7. As a last step, git stage the relevant files and propose (but not execute) a single git commit command (e.g. `git commit -m ""`) - - -## Useful Resources - -- Main SDK documentation: https://develop.sentry.dev/sdk/overview/ -- Internal contributing guide: https://docs.sentry.io/internal/contributing/ -- Git commit messages conventions: https://develop.sentry.dev/engineering-practices/commit-messages/ diff --git a/.cursor/rules/overview_dev.mdc b/.cursor/rules/overview_dev.mdc deleted file mode 100644 index b837be34ad..0000000000 --- a/.cursor/rules/overview_dev.mdc +++ /dev/null @@ -1,133 +0,0 @@ ---- -alwaysApply: true -description: Sentry Java SDK - Development Rules Overview ---- - -# Sentry Java SDK Development Rules - -## Always Applied Rules - -These rules are automatically included in every conversation: -- **coding.mdc**: General contributing guidelines, build commands, and workflow rules - -## Domain-Specific Rules (Fetch Only When Needed) - -Use the `fetch_rules` tool to include these rules when working on specific areas: - -### Core SDK Functionality -- **`api`**: Use when working with: - - Adding or modifying public API surface - - Binary compatibility, `.api` files, `apiDump` - - Understanding which classes to modify for new API (interfaces, implementations, no-ops, adapters) - - `IScope`, `IScopes`, `Sentry` static API - - Attributes, logging API, protocol classes - -- **`options`**: Use when working with: - - Adding or modifying SDK options (`SentryOptions`, namespaced options) - - External options (`ExternalOptions`, `sentry.properties`, environment variables) - - Android manifest metadata (`ManifestMetadataReader`) - - Spring Boot properties (`SentryProperties`) - -- **`scopes`**: Use when working with: - - Hub/Scope management, forking, or lifecycle - - `Sentry.getCurrentScopes()`, `pushScope()`, `withScope()` - - `ScopeType` (GLOBAL, ISOLATION, CURRENT) - - Thread-local storage, scope bleeding issues - - Migration from Hub API (v7 → v8) - -- **`deduplication`**: Use when working with: - - Duplicate event detection/prevention - - `DuplicateEventDetectionEventProcessor` - - `enableDeduplication` option - -- **`offline`**: Use when working with: - - Caching, envelope storage/retrieval - - Network failure handling, retry logic - - `AsyncHttpTransport`, `EnvelopeCache` - - Rate limiting, cache rotation - - Android vs JVM caching differences - -- **`feature_flags`**: Use when working with: - - Feature flag tracking and evaluation - - `addFeatureFlag()`, `getFeatureFlags()` methods - - `FeatureFlagBuffer`, `SpanFeatureFlagBuffer`, `FeatureFlag` protocol - - `maxFeatureFlags` option and buffer management - - Feature flag merging across scope types - - Scope-based vs span-based feature flag APIs - - Scope-based API: `Sentry`, `IScopes`, `IScope` APIs - - Span-based API: `ISpan`, `ITransaction` APIs - - Integrations: LaunchDarkly (Android/JVM), OpenFeature (JVM) - -- **`metrics`**: Use when working with: - - Metrics API (`Sentry.metrics()`, `IScopes.metrics()`) - - `IMetricsApi`, `MetricsApi` implementation - - Metrics types: `count`, `distribution`, `gauge` - - `MetricsBatchProcessor`, batching and queue management - - `SentryMetricsEvent`, `SentryMetricsEvents` - - `SentryOptions.getMetrics()`, `beforeSend` callback - -- **`queues`**: Use when working with: - - Sentry Queues product data or messaging span conventions - - Queue tracing spans/transactions (`queue.publish`, `queue.process`) - - `enableQueueTracing` option and `sentry.enable-queue-tracing` - - Kafka instrumentation (`sentry-kafka`, `SentryKafkaProducer`, `SentryKafkaConsumerTracing`) - - Spring Kafka queue auto-instrumentation and `SentryKafkaRecordInterceptor` - - Messaging span data (`messaging.system`, `messaging.destination.name`, receive latency, retry count) - - `sentry-task-enqueued-time` header and distributed trace propagation through queues - -- **`continuous_profiling_jvm`**: Use when working with: - - JVM continuous profiling (`sentry-async-profiler` module) - - `IContinuousProfiler`, `JavaContinuousProfiler` - - `ProfileChunk`, chunk rotation, JFR file handling - - `ProfileLifecycle` (MANUAL vs TRACE modes) - - async-profiler integration, ServiceLoader discovery - - Rate limiting, offline caching, scopes integration - -- **Android profiling**: There is currently no dedicated rule for this area yet. - - Inspect the relevant `sentry-android-core` profiling code directly - - Fetch other related rules as needed (for example `options`, `offline`, or `api`) - -### Integration & Infrastructure -- **`opentelemetry`**: Use when working with: - - OpenTelemetry modules (`sentry-opentelemetry-*`) - - Agent vs agentless configurations - - Span processing, sampling, context propagation - - `OtelSpanFactory`, `SentrySpanExporter` - - Tracing, distributed tracing - -- **`new_module`**: Use when adding a new integration or sample module - -### Workflow -- **`pr`**: Use when working with: - - Creating pull requests - - Stacked PRs, PR naming, stack comments - - PR changelog entries - - Merging or syncing stacked branches - -### Testing -- **`e2e_tests`**: Use when working with: - - System tests, sample applications - - `system-test-runner.py`, mock Sentry server - - End-to-end test infrastructure - - CI system test workflows - -## Usage Guidelines - -1. **Start minimal**: Only include `coding.mdc` (auto-applied) for general tasks -2. **Fetch on-demand**: Use `fetch_rules ["rule_name"]` when you identify specific domain work -3. **Multiple rules**: Fetch multiple rules if task spans domains (e.g., `["scopes", "opentelemetry"]` for tracing scope issues) -4. **Context clues**: Look for these keywords in requests to determine relevant rules: - - Public API/apiDump/.api files/binary compatibility/new method → `api` - - Options/SentryOptions/ExternalOptions/ManifestMetadataReader/sentry.properties → `options` - - 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` - - Feature flag/addFeatureFlag/flag evaluation → `feature_flags` - - Metrics/count/distribution/gauge → `metrics` - - Queues/queue tracing/Kafka/Spring Kafka/queue.publish/queue.process/enableQueueTracing/messaging spans → `queues` - - PR/pull request/stacked PR/stack → `pr` - - JVM continuous profiling/async-profiler/JFR/ProfileChunk → `continuous_profiling_jvm` - - Android continuous profiling/AndroidProfiler/frame metrics/method tracing → no dedicated rule yet; inspect the code directly diff --git a/AGENTS.md b/AGENTS.md index 4f938ceff2..f785961ece 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,15 +2,30 @@ This file provides guidance to AI coding agents when working with code in this repository. -## STOP — Required Reading (Do This First) - -Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load these files: -1. `.cursor/rules/coding.mdc` -2. `.cursor/rules/overview_dev.mdc` - -Then identify and read any topically relevant `.cursor/rules/*.mdc` files for the area you're working on (e.g., `opentelemetry.mdc` for OTel work, `metrics.mdc` for metrics work). Use the Glob tool on `.cursor/rules/*.mdc` to discover available rule files. - -Do NOT skip this step. Do NOT proceed without reading these files first. +## Domain-Specific Rules + +This file covers the whole repository. Before working on a specific area, read the matching +rule file in `.cursor/rules/`: + +| Rule | Read it when working on | +|---|---| +| `api` | Public API surface, binary compatibility, `.api` files, `apiDump`, `IScope`/`IScopes`/`Sentry` static API, protocol classes | +| `options` | `SentryOptions`, namespaced options, `ExternalOptions`, `sentry.properties`, `ManifestMetadataReader`, Spring Boot properties | +| `scopes` | Scope management, forking, lifecycle, `ScopeType`, thread-local storage, scope bleeding, Hub → Scopes migration | +| `deduplication` | Duplicate event detection, `DuplicateEventDetectionEventProcessor`, `enableDeduplication` | +| `offline` | Caching, envelope storage, network failure handling, retries, `AsyncHttpTransport`, `EnvelopeCache`, rate limiting | +| `feature_flags` | `addFeatureFlag`, `FeatureFlagBuffer`, `maxFeatureFlags`, LaunchDarkly and OpenFeature integrations | +| `metrics` | `Sentry.metrics()`, `IMetricsApi`, count/distribution/gauge, `MetricsBatchProcessor` | +| `queues` | Queue tracing, `queue.publish`/`queue.process`, `enableQueueTracing`, Kafka instrumentation, messaging span data | +| `continuous_profiling_jvm` | `sentry-async-profiler`, `IContinuousProfiler`, `ProfileChunk`, JFR files, `ProfileLifecycle` | +| `opentelemetry` | `sentry-opentelemetry-*`, agent vs agentless, span processing, sampling, context propagation | +| `new_module` | Adding a new integration or sample module | +| `pr` | Creating pull requests, stacked PRs, changelog entries | +| `e2e_tests` | System tests, sample applications, `system-test-runner.py`, mock Sentry server | + +Rules can be combined — a tracing scope issue may need both `scopes` and `opentelemetry`. +There is no rule for Android profiling yet; read the `sentry-android-core` profiling code +directly and fetch related rules such as `options`, `offline`, or `api` as needed. ## Project Overview diff --git a/CLAUDE.md b/CLAUDE.md index 19507016af..f59e5a152f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,5 +2,8 @@ ## STOP — Required Reading (Do This First) -Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load [AGENTS.md](AGENTS.md) and follow ALL of its instructions, including reading the required `.cursor/rules/*.mdc` files it references. -Do NOT skip this step. Do NOT proceed without reading these files first. +Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load +[AGENTS.md](AGENTS.md) and follow ALL of its instructions. It is the single source of truth +for build commands, contributing guidelines, workflow rules, and the index of the +domain-specific rules. +Do NOT skip this step. Do NOT proceed without reading it first.