From 736bdaf73cdcea19d014ff1a800dcae78a2cf154 Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Fri, 14 Aug 2026 15:01:48 +0200 Subject: [PATCH 1/2] docs(agents): Remove duplicated build commands and rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md is force-read at the start of every session, so anything stated there costs context on every task. Several rules had accumulated multiple copies of themselves within that one file. `spotlessApply`/`apiDump` was stated five times in AGENTS.md; it is now stated once as a command and once as a workflow step, with the underlying facts (Spotless enforces formatting, `.api` files are generated) kept where they belong. The Testing command block is dropped in favour of the `test` skill, which already resolves the per-module task and the unit-vs-system split and does not drift. The Repository Skills bullet list restated skill descriptions that the harness already injects, so it is now a pointer. In the rules, `new_module.mdc`'s "Important Notes" was a verbatim restatement of the AGENTS.md contributing guidelines, and `api.mdc` repeated the opt-in-by-default rule in passing; both now defer to their canonical homes. No guidance is lost — every removed line is still stated somewhere that is loaded when it applies. --- .cursor/rules/api.mdc | 2 +- .cursor/rules/new_module.mdc | 7 ------ AGENTS.md | 48 +++++++++--------------------------- 3 files changed, 12 insertions(+), 45 deletions(-) diff --git a/.cursor/rules/api.mdc b/.cursor/rules/api.mdc index c5a793d9240..9435bc2590f 100644 --- a/.cursor/rules/api.mdc +++ b/.cursor/rules/api.mdc @@ -34,7 +34,7 @@ Public API is tracked via `.api` files generated by the [Binary Compatibility Va - `SentryAndroidOptions` — Android-specific options - Integration modules may add their own (e.g. `SentrySpringProperties`) -New features must be **opt-in by default** — add a getter/setter pair to the appropriate options class. +See the `options` rule for how to add and wire up a new option. ### Internal Classes (Not Public API) diff --git a/.cursor/rules/new_module.mdc b/.cursor/rules/new_module.mdc index 5bf2c70c2f7..dcb9a37913c 100644 --- a/.cursor/rules/new_module.mdc +++ b/.cursor/rules/new_module.mdc @@ -79,10 +79,3 @@ Remind the user to perform the following tasks after the module is merged and re - 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` - -## Important Notes - -1. **API Files**: Do not modify `.api` files manually. Run `./gradlew apiDump` to regenerate them -2. **Backwards Compatibility**: Ensure new features are opt-in by default -3. **Testing**: Write comprehensive tests for all new functionality -4. **Documentation**: Always include proper documentation and examples diff --git a/AGENTS.md b/AGENTS.md index 42bc6677d17..1027e513c4b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,6 @@ The project uses **Gradle** with Kotlin DSL. Key build files: ## Essential Commands -### Development Workflow ```bash # Format code and regenerate .api files (REQUIRED before committing) ./gradlew spotlessApply apiDump @@ -50,36 +49,14 @@ The project uses **Gradle** with Kotlin DSL. Key build files: # Generate documentation ./gradlew aggregateJavadocs -``` - -### Testing -```bash -# Run unit tests for a specific file -./gradlew '::testReleaseUnitTest' --tests="**" --info - -# Run system tests (requires Python virtual env) -make systemTest - -# Run specific test suites -./gradlew :sentry-android-core:testReleaseUnitTest -./gradlew :sentry:test -``` - -### Code Quality -```bash -# Check code formatting -./gradlew spotlessJavaCheck spotlessKotlinCheck - -# Apply code formatting -./gradlew spotlessApply - -# Update API dump files (after API changes) -./gradlew apiDump # Dependency updates check ./gradlew dependencyUpdates -Drevision=release ``` +To run tests, use the `test` skill rather than composing the Gradle invocation by hand — it +resolves the per-module test task and the unit-test vs system-test split for you. + ### Android-Specific Commands ```bash # Assemble Android test APKs @@ -102,11 +79,9 @@ make systemTest ## Repository Skills -This repo ships task-specific skills (declared in `agents.toml`, sources under `.agents/skills`). Prefer them over performing the steps manually: -- **`create-java-pr`**: Branch, format, `apiDump`, commit, push, open PR, and add the changelog entry (automates the PR workflow above) -- **`test`**: Run unit or system tests for a module or a specific class -- **`check-code-attribution`**: Verify third-party code attribution on the current branch (see Third-Party Code Attribution below) -- **`btrace-perfetto`**: Capture and compare Perfetto traces for Android performance work +This repo ships task-specific skills, declared in `agents.toml` with sources under +`.agents/skills`. Your harness already lists them with their descriptions — prefer them over +performing the steps manually. ## Module Architecture @@ -150,8 +125,8 @@ The repository is organized into multiple modules: ### Code Style - **Languages**: Java 8+ and Kotlin -- **Formatting**: Enforced via Spotless - always run `./gradlew spotlessApply` before committing -- **API Compatibility**: Binary compatibility is enforced - run `./gradlew apiDump` after API changes +- **Formatting**: Enforced via Spotless +- **API Compatibility**: Binary compatibility is enforced. `.api` files are generated, never hand-edited ### Exception Handling @@ -189,10 +164,9 @@ PR description why the broad catch is necessary. ### Contributing Guidelines 1. Follow existing code style and language -2. Do not modify API files (e.g. sentry.api) manually - run `./gradlew apiDump` to regenerate them -3. Write comprehensive tests -4. New features must be **opt-in by default** - extend `SentryOptions` or similar Option classes with getters/setters -5. Consider backwards compatibility +2. Write comprehensive tests +3. New features must be **opt-in by default** - extend `SentryOptions` or similar Option classes with getters/setters +4. Consider backwards compatibility ### Third-Party Code Attribution When adapting code from third-party libraries: From beac27d1ccc5642cced3cb59ea2f6bbc6fd582bf Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Fri, 14 Aug 2026 15:40:56 +0200 Subject: [PATCH 2/2] docs(agents): Refresh new_module rule and cover full system-test runs Validating the previous commit with agents surfaced two gaps. `new_module.mdc` had drifted from the repo. Its README badge snippet still used the retired maven-badges.herokuapp.com format, while every current row in README.md uses shields.io with a central.sonatype.com link. It also never mentioned four steps that every existing integration module performs: the `SENTRY_*_SDK_NAME` constant in `Config.kt` consumed by buildConfig and the jar manifest, the `libs.versions.toml` entry paired with a `compileOnly` dependency, self-registration via `SentryIntegrationPackageStorage.addPackage` and `addIntegrationToSdkVersion`, and the integrations dropdown in the issue template. It now also points at `sentry-kafka` and `sentry-android-timber` as build-script templates, and records that `sentry-bom` and the root build file need no change because they iterate over subprojects. The `test` skill only ever ran a single module, so folding the AGENTS.md testing block into it dropped the only reference to running the whole system test suite. Step 3b now covers `make systemTest` and `make systemTestInteractive`. --- .claude/skills/test/SKILL.md | 8 ++++++ .cursor/rules/new_module.mdc | 48 +++++++++++++++++++++++++++++++----- 2 files changed, 50 insertions(+), 6 deletions(-) diff --git a/.claude/skills/test/SKILL.md b/.claude/skills/test/SKILL.md index 7e6ddd37294..d7b28f6d260 100644 --- a/.claude/skills/test/SKILL.md +++ b/.claude/skills/test/SKILL.md @@ -78,6 +78,14 @@ test -d .venv || make setupPython This starts the mock Sentry server, starts the sample app (Spring Boot/Tomcat/CLI), runs tests via `./gradlew :sentry-samples::systemTest`, and cleans up afterwards. +To run **every** system test instead of one module, use the Makefile targets — they also create the +venv for you: + +```bash +make systemTest # all system tests (--all) +make systemTestInteractive # pick the setups to run (--interactive) +``` + ## Step 4: Report Results Summarize the test outcome: diff --git a/.cursor/rules/new_module.mdc b/.cursor/rules/new_module.mdc index dcb9a37913c..ebf2b2d0c23 100644 --- a/.cursor/rules/new_module.mdc +++ b/.cursor/rules/new_module.mdc @@ -12,7 +12,9 @@ This document outlines the complete process for adding a new module to the sentr ### 1. Create the Module Structure -1. Create the new module, conforming to the existing naming conventions and build scripts +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` @@ -27,9 +29,36 @@ ignoredProjects.addAll( ) ``` -3. If adding a JVM sample, add E2E (system) tests, following the structure we have in the existing JVM examples. +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.)`, 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: @@ -46,22 +75,29 @@ 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` with a placeholder link to the badge: +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](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}) | | +| 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 Documentation to docs.sentry.io +### 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 -### 5. Post release tasks +### 6. Post release tasks Remind the user to perform the following tasks after the module is merged and released: