From 935f14010c2a8734868697dc30400f721724a6ce Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Mon, 23 Mar 2026 15:55:34 +0000 Subject: [PATCH 01/10] Added CLAUDE.md instructions A global general instruction and one per project JAVA-6143 --- CLAUDE.md | 188 +++++++++++++++++++++++++++++ bson-kotlin/CLAUDE.md | 13 ++ bson-kotlinx/CLAUDE.md | 14 +++ bson-record-codec/CLAUDE.md | 13 ++ bson-scala/CLAUDE.md | 24 ++++ bson/CLAUDE.md | 26 ++++ buildSrc/CLAUDE.md | 60 +++++++++ driver-core/CLAUDE.md | 37 ++++++ driver-kotlin-coroutine/CLAUDE.md | 15 +++ driver-kotlin-extensions/CLAUDE.md | 15 +++ driver-kotlin-sync/CLAUDE.md | 13 ++ driver-legacy/CLAUDE.md | 15 +++ driver-reactive-streams/CLAUDE.md | 20 +++ driver-scala/CLAUDE.md | 22 ++++ driver-sync/CLAUDE.md | 20 +++ mongodb-crypt/CLAUDE.md | 17 +++ testing/CLAUDE.md | 9 ++ 17 files changed, 521 insertions(+) create mode 100644 CLAUDE.md create mode 100644 bson-kotlin/CLAUDE.md create mode 100644 bson-kotlinx/CLAUDE.md create mode 100644 bson-record-codec/CLAUDE.md create mode 100644 bson-scala/CLAUDE.md create mode 100644 bson/CLAUDE.md create mode 100644 buildSrc/CLAUDE.md create mode 100644 driver-core/CLAUDE.md create mode 100644 driver-kotlin-coroutine/CLAUDE.md create mode 100644 driver-kotlin-extensions/CLAUDE.md create mode 100644 driver-kotlin-sync/CLAUDE.md create mode 100644 driver-legacy/CLAUDE.md create mode 100644 driver-reactive-streams/CLAUDE.md create mode 100644 driver-scala/CLAUDE.md create mode 100644 driver-sync/CLAUDE.md create mode 100644 mongodb-crypt/CLAUDE.md create mode 100644 testing/CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000000..0b40d8ad166 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,188 @@ +# CLAUDE.md - MongoDB Java Driver + +Guidelines for AI agents working on the MongoDB Java Driver codebase. + +## Project Overview + +This is the official MongoDB JVM driver monorepo, providing Java, Kotlin, and Scala +drivers for MongoDB. The driver implements the +[MongoDB Driver Specifications](https://github.com/mongodb/specifications) +and follows semantic versioning. + +### Module Structure + +| Module | Purpose | +|----------------------------|-----------------------------------------------------------| +| `bson` | BSON library (core serialization) | +| `bson-kotlin` | Kotlin BSON extensions | +| `bson-kotlinx` | Kotlin serialization BSON codec | +| `bson-record-codec` | Java record codec support | +| `bson-scala` | Scala BSON extensions | +| `driver-core` | Core driver internals (connections, protocol, operations) | +| `driver-sync` | Synchronous Java driver | +| `driver-legacy` | Legacy MongoDB Java driver API | +| `driver-reactive-streams` | Reactive Streams driver | +| `driver-kotlin-coroutine` | Kotlin Coroutines driver | +| `driver-kotlin-extensions` | Kotlin driver extensions | +| `driver-kotlin-sync` | Kotlin synchronous driver | +| `driver-scala` | Scala driver | +| `mongodb-crypt` | Client-side field-level encryption | +| `testing` | Shared test resources and MongoDB specifications | + +### Internal API Convention + +All code in `com.mongodb.internal.*` and `org.bson.internal.*` is private API. +It can change at any time without notice. Never expose internal types in +public APIs, and never advise users to depend on them. + +### API Stability Annotations + +- `@Alpha` - Early development, may be removed. Not for production use. +- `@Beta` - Subject to change or removal. Libraries should not depend on these. +- `@Evolving` - May add abstract methods in future releases. Safe to use, but implementing/extending bears upgrade risk. +- `@Sealed` - Must not be extended or implemented by consumers. Safe to use, but not to subclass. +- `@Deprecated` - Supported until next major release but should be migrated away from. + +## General + +- Follow existing conventions. Keep it simple. +- When stuck: stop, explain the problem, propose alternatives, ask for guidance. +- When uncertain: ask rather than assume. Present options with trade-offs. + +## Build System + +- **Build tool:** Gradle with Kotlin DSL +- **Build JDK:** Java 17+ +- **Source compatibility (baseline):** Java 8 for most modules / main driver artifacts +- **Version catalog:** `gradle/libs.versions.toml` +- **Convention plugins:** `buildSrc/src/main/kotlin/conventions/` + +### Essential Build Commands + +```bash +# Full validation (static checks + unit tests + integration tests) +./gradlew check + +# Integration tests (requires running MongoDB) +./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017" + +# Single module tests +./gradlew :driver-core:test + +# Format check only +./gradlew spotlessCheck + +# Auto-fix formatting +./gradlew spotlessApply + +# Test with alternative JDK +./gradlew test -PjavaVersion=11 +``` + +## Code Style and Formatting + +Formatting is enforced automatically because the Gradle `check` task depends on +`./gradlew spotlessApply`, which formats sources. To run a check without modifying +files, invoke `./gradlew spotlessCheck` manually. Do not manually reformat files +outside the scope of your changes. + +### Style Rules + +- **Max line length:** 140 characters +- **Indentation:** 4 spaces (no tabs) +- **Line endings:** LF (Unix) +- **Charset:** UTF-8 +- **Star imports:** Prohibited (AvoidStarImport) +- **Final parameters:** Required (FinalParameters checkstyle rule) +- **Braces:** Required for all control structures (NeedBraces) +- **Else placement:** On its own line (not cuddled) +- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.` + +### Prohibited Patterns + +- `System.out.println` / `System.err.println` — Use SLF4J logging +- `e.printStackTrace()` — Use proper logging/error handling + +## Testing + +### Frameworks + +- **JUnit 5** (Jupiter) - Primary unit test framework +- **Spock** (Groovy) - Legacy, do not add new Spock tests. +- **Mockito** - Mocking +- **ScalaTest** - Scala module testing + +### Writing Tests + +- **Every code change must include tests.** New code needs new tests; modified code needs updated tests. Do not reduce test coverage. +- Extend existing test patterns in the module you are modifying +- Unit tests should not require a running MongoDB instance +- Test methods should be descriptive: + prefer `shouldReturnEmptyListWhenNoDocumentsMatch()` over `test1()`, + use `@DisplayName` for a human readable name +- Clean up test data in `@AfterEach` / `cleanup()` to prevent test pollution + +### MongoDB Specifications and Specification Tests + +The driver implements the [MongoDB Specifications](https://github.com/mongodb/specifications). Specification test data files live in +`testing/resources/specifications/` — a git submodule for test resources. When modifying driver specification-related behavior: do +not modify existing specification tests unless they test incorrect behavior. Create new tests instead. + +## Core Development Principles + +### Essential Rules + +- **Read before modifying.** Understand existing code and patterns before making changes. +- **Minimal changes only.** No drive-by refactoring. +- **Preserve existing comments.** Only remove comments that are provably incorrect. +- **No unrelated changes.** Do not fix formatting or refactor code outside the scope of the task. +- **No rewrites** without explicit permission. + +### Search Before Implementing + +Before writing new code, search the codebase for existing implementations: + +- Check if a utility method already exists in `com.mongodb.internal.*` +- Check if a similar pattern is established elsewhere in the module +- Reuse existing well-tested infrastructure over creating duplicates + +### API Design + +- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers. +- **Information hiding:** Bury complexity behind simple interfaces. +- **Pull complexity downward:** Make the implementer work harder so callers work less. +- **General-purpose over special-case:** Fewer flexible methods over many specialized ones. +- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them. + +## Dependency Management + +Dependencies are managed centrally via `gradle/libs.versions.toml`. + +- **Never add dependencies without justification.** Dependencies are liabilities. +- **Use dependencies for:** Security/crypto, complex protocols, battle-tested algorithms. +- **Write it yourself for:** fewer than 100 LOC of straightforward code, project-specific logic, performance-critical paths. +- Optional dependencies (Netty, Snappy, Zstd, AWS SDK, SLF4J) use `optionalImplementation` and must not be required at runtime. + +## Safety Rules - Do Not Modify Without Review + +- Wire protocol implementation (connection/authentication handshakes) +- Security-critical authentication and encryption code +- Public API contracts (breaking changes require major version bump) +- BSON specification compliance +- Configuration files containing credentials or secrets +- CI/CD pipeline configurations in `.evergreen/` +- Release and publishing scripts + +## CI/CD + +### Evergreen (MongoDB Internal CI) + +Primary CI runs on MongoDB's Evergreen system. Configuration is in `.evergreen/`. + +### Before Submitting + +Run locally at minimum: + +```bash +./gradlew doc check scalaCheck # Generates docs, runs static checks + tests +``` diff --git a/bson-kotlin/CLAUDE.md b/bson-kotlin/CLAUDE.md new file mode 100644 index 00000000000..e61e7156820 --- /dev/null +++ b/bson-kotlin/CLAUDE.md @@ -0,0 +1,13 @@ +# CLAUDE.md - bson-kotlin + +Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support. + +**Depends on:** `bson` + +## Key Packages + +- `org.bson.codecs.kotlin` — Kotlin-specific codecs with inline reified functions + +## Notes + +- Formatting: ktfmt dropbox style, max width 120 diff --git a/bson-kotlinx/CLAUDE.md b/bson-kotlinx/CLAUDE.md new file mode 100644 index 00000000000..12ec24197ab --- /dev/null +++ b/bson-kotlinx/CLAUDE.md @@ -0,0 +1,14 @@ +# CLAUDE.md - bson-kotlinx + +Kotlinx serialization integration for BSON, providing a pluggable serialization format. + +**Depends on:** `bson` + +## Key Packages + +- `org.bson.codecs.kotlinx` — Kotlinx serialization BSON format support +- `org.bson.codecs.kotlinx.utils` — Helper utilities + +## Notes + +- Formatting: ktfmt dropbox style, max width 120 diff --git a/bson-record-codec/CLAUDE.md b/bson-record-codec/CLAUDE.md new file mode 100644 index 00000000000..ad2cc1904e5 --- /dev/null +++ b/bson-record-codec/CLAUDE.md @@ -0,0 +1,13 @@ +# CLAUDE.md - bson-record-codec + +Java record codec support for BSON serialization. **Requires Java 17+.** + +**Depends on:** `bson` + +## Key Packages + +- `org.bson.codecs.record` — `RecordCodecProvider` and record field accessors + +## Notes + +- Every package must have a `package-info.java` diff --git a/bson-scala/CLAUDE.md b/bson-scala/CLAUDE.md new file mode 100644 index 00000000000..68b89474276 --- /dev/null +++ b/bson-scala/CLAUDE.md @@ -0,0 +1,24 @@ +# CLAUDE.md - bson-scala + +Scala extensions for the BSON library, providing Scala-idiomatic wrappers and macro-based codecs. + +**Depends on:** `bson` + +**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root `gradle.properties`). Default: 2.13. + +See [README.md](./README.md) for full details on directory layout, formatting, and testing commands. + +## Key Packages + +- `org.mongodb.scala.bson` — Core Scala BSON wrappers +- `org.mongodb.scala.bson.codecs` — Macro-based codecs (Scala 2/3) +- `org.mongodb.scala.bson.collection` — Immutable/mutable collection support +- `org.mongodb.scala.bson.annotations` — Field annotations + +## Before Submitting + +```bash +./gradlew spotlessApply # Fix formatting +./gradlew :bson-scala:scalaCheck # Static checks + tests (default Scala version) +./gradlew :bson-scala:scalaCheck -PscalaVersion= # Test specific Scala version +``` diff --git a/bson/CLAUDE.md b/bson/CLAUDE.md new file mode 100644 index 00000000000..4bc297186e3 --- /dev/null +++ b/bson/CLAUDE.md @@ -0,0 +1,26 @@ +# CLAUDE.md - bson + +Core BSON (Binary JSON) library. This is the foundation module — all other modules depend on it. + +## Key Packages + +- `org.bson` — Core BSON value types (`BsonDocument`, `BsonValue`, `BsonReader`, `BsonWriter`) +- `org.bson.codecs` — Codec framework (`Encoder`, `Decoder`, `Codec`) +- `org.bson.codecs.configuration` — Codec registry and provider infrastructure (`CodecRegistry`, `CodecProvider`) +- `org.bson.codecs.pojo` — POJO codec support with conventions and property modeling +- `org.bson.codecs.jsr310` — Java 8+ date/time codec support +- `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`, `JsonMode`) +- `org.bson.io` — Binary I/O (`ByteBuffer`, `OutputBuffer`) +- `org.bson.types` — Legacy types (`ObjectId`, `Decimal128`, etc.) +- `org.bson.internal` — Private API (vector support, encoding utilities) + +## Notes + +- Every package must have a `package-info.java` +- JUnit 5 + Spock (Groovy) tests in both unit and functional dirs + +## Key Patterns + +- Codec-based serialization with type-safe `BsonValue` hierarchy +- `BsonDocument` implements `Map` +- All public types in `org.bson` — internal types in `org.bson.internal` diff --git a/buildSrc/CLAUDE.md b/buildSrc/CLAUDE.md new file mode 100644 index 00000000000..10ce1750e24 --- /dev/null +++ b/buildSrc/CLAUDE.md @@ -0,0 +1,60 @@ +# CLAUDE.md - buildSrc + +Gradle build infrastructure providing convention plugins and shared configuration for all modules. + +## Key Directories + +- `src/main/kotlin/conventions/` — Convention plugins applied by modules (formatting, testing, publishing, static analysis) +- `src/main/kotlin/project/` — Base project plugins for Java, Kotlin, and Scala modules +- `src/main/kotlin/ProjectExtensions.kt` — Shared Gradle extension utilities + +## Convention Plugins + +| Plugin | Purpose | +|-----------------------------------------|-----------------------------------------------------------------------------------| +| `spotless` | Code formatting (Java: Palantir; Kotlin: ktfmt dropbox, max 120; Scala: scalafmt) | +| `codenarc` | Groovy static analysis | +| `detekt` | Kotlin static analysis | +| `spotbugs` | Java bug detection | +| `bnd` | OSGi bundle metadata | +| `dokka` | Kotlin documentation generation | +| `javadoc` | Java documentation generation | +| `scaladoc` | Scala documentation generation | +| `publishing` | Maven Central publishing configuration | +| `git-version` | Version derivation from git tags | +| `optional` | Optional dependency support (`optionalImplementation`) | +| `testing-base` | Shared test configuration | +| `testing-integration` | Integration test source set and tasks | +| `testing-junit` | JUnit 5 test setup | +| `testing-junit-vintage` | JUnit 4 compatibility | +| `testing-spock` | Spock framework setup | +| `testing-spock-exclude-slow` | Spock with slow test exclusion | +| `testing-mockito` | Mockito setup | +| `test-artifacts` | Test artifact sharing between modules | +| `test-artifacts-runtime-dependencies` | Runtime dependency sharing for tests | +| `test-include-optionals` | Include optional dependencies in tests | + +## Project Plugins + +| Plugin | Purpose | +|------------------|------------------------------------------------------------| +| `project/base` | Common settings for all modules | +| `project/java` | Java module conventions (source compatibility, checkstyle) | +| `project/kotlin` | Kotlin module conventions | +| `project/scala` | Scala module conventions (multi-version support) | + +## Notes + +- Formatting: ktfmt dropbox style, max width 120 (for buildSrc's own code) +- `check` depends on `spotlessCheck` in buildSrc itself +- Java toolchain is set to Java 17 + +## Keeping CLAUDE.md Files in Sync + +When modifying buildSrc, you **must** update the relevant CLAUDE.md files if your changes affect: + +- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root `CLAUDE.md` "Code Style and Formatting" section and any module CLAUDE.md files that reference formatting rules +- **Convention plugins added or removed** — update this file's plugin table and the root `CLAUDE.md` if the change affects build commands or developer workflow +- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root `CLAUDE.md` "Testing" section and affected module CLAUDE.md files +- **Project plugins added or removed** — update this file's project plugin table +- **Build commands or task names changed** — update the root `CLAUDE.md` "Essential Build Commands" and "Before Submitting" sections, and any module "Before Submitting" sections diff --git a/driver-core/CLAUDE.md b/driver-core/CLAUDE.md new file mode 100644 index 00000000000..5f77f7b4cc6 --- /dev/null +++ b/driver-core/CLAUDE.md @@ -0,0 +1,37 @@ +# CLAUDE.md - driver-core + +Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala). Largest and most complex module. + +**Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`, `mongodb-crypt` + +## Key Packages (Public API) + +- `com.mongodb.client.model` — Operation models: `Filters`, `Updates`, `Projections`, `Aggregates`, `Sorts`, `Indexes` +- `com.mongodb.client.model.search` — Atlas Search configuration +- `com.mongodb.client.result` — Operation result types (`InsertOneResult`, `DeleteResult`, etc.) +- `com.mongodb.connection` — `ClusterSettings`, `ClusterDescription` +- `com.mongodb.event` — Listeners for commands, connections, servers, cluster events +- `com.mongodb.session` — `ClientSession` interface +- `com.mongodb.bulk` — `WriteModel` hierarchy + +## Key Packages (Internal — Private API) + +- `com.mongodb.internal.connection` — Socket, wire protocol, command execution +- `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate, etc.) +- `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC +- `com.mongodb.internal.async` — Async operation framework +- `com.mongodb.internal.binding` — Server binding strategies +- `com.mongodb.internal.client` — MongoClient/MongoDatabase/MongoCollection implementations + +## Notes + +- Every package must have a `package-info.java` +- Most extensive test suite — JUnit 5 + Spock (Groovy) + Mockito. Match surrounding patterns carefully. +- `com.mongodb.internal.build.MongoDriverVersion` is auto-generated by the `com.github.gmazzo.buildconfig` Gradle plugin — run `./gradlew :driver-core:generateMongoDriverVersion` if missing +- Never block in async code paths + +## Key Patterns + +- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()` +- Fluent builders: `MongoClientSettings.builder()` is the primary entry point for configuring clients +- Abstract core with pluggable transports diff --git a/driver-kotlin-coroutine/CLAUDE.md b/driver-kotlin-coroutine/CLAUDE.md new file mode 100644 index 00000000000..b5a885791be --- /dev/null +++ b/driver-kotlin-coroutine/CLAUDE.md @@ -0,0 +1,15 @@ +# CLAUDE.md - driver-kotlin-coroutine + +Kotlin Coroutines driver providing `suspend` function-based async API. + +**Depends on:** `bson`, `driver-reactive-streams`, `bson-kotlin` + +## Key Packages + +- `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`, `MongoDatabase`, `MongoCollection`) + +## Notes + +- Formatting: ktfmt dropbox style, max width 120 +- Suspend functions wrapping `driver-reactive-streams` — never block +- Built on `kotlinx-coroutines` diff --git a/driver-kotlin-extensions/CLAUDE.md b/driver-kotlin-extensions/CLAUDE.md new file mode 100644 index 00000000000..7da92d6ed55 --- /dev/null +++ b/driver-kotlin-extensions/CLAUDE.md @@ -0,0 +1,15 @@ +# CLAUDE.md - driver-kotlin-extensions + +Kotlin extensions providing type-safe DSLs for query and update construction. + +**Depends on:** `driver-core`, optionally `driver-kotlin-sync`, `driver-kotlin-coroutine` + +## Key Packages + +- `com.mongodb.kotlin.client.model` — Type-safe DSL builders (`Filters`, `Updates`, `Aggregates`, `Sorts`, `Projections`, `Indexes`) +- `com.mongodb.kotlin.client.property` — `KPropertyPath` for property-based queries + +## Notes + +- Formatting: ktfmt dropbox style, max width 120 +- Works with both `driver-kotlin-sync` and `driver-kotlin-coroutine` diff --git a/driver-kotlin-sync/CLAUDE.md b/driver-kotlin-sync/CLAUDE.md new file mode 100644 index 00000000000..8dbdd3797f0 --- /dev/null +++ b/driver-kotlin-sync/CLAUDE.md @@ -0,0 +1,13 @@ +# CLAUDE.md - driver-kotlin-sync + +Kotlin synchronous (blocking) driver — idiomatic Kotlin wrapper over `driver-sync`. + +**Depends on:** `bson`, `driver-sync`, `bson-kotlin` + +## Key Packages + +- `com.mongodb.kotlin.client` — Blocking sync API (`MongoClient`, `MongoDatabase`, `MongoCollection`) + +## Notes + +- Formatting: ktfmt dropbox style, max width 120 diff --git a/driver-legacy/CLAUDE.md b/driver-legacy/CLAUDE.md new file mode 100644 index 00000000000..bcf21a029fe --- /dev/null +++ b/driver-legacy/CLAUDE.md @@ -0,0 +1,15 @@ +# CLAUDE.md - driver-legacy + +Legacy MongoDB Java driver API — backwards compatibility facade for the 3.x API. + +**Depends on:** `bson`, `driver-core`, `driver-sync` + +## Key Packages + +- `com.mongodb` — Legacy API (`MongoClient`, `DB`, `DBCollection`, `DBCursor`) — distinct from `driver-core` classes in the same namespace +- `com.mongodb.gridfs` — Legacy GridFS + +## Notes + +- Every package must have a `package-info.java` +- Do not add new features here — new functionality goes in `driver-sync` or `driver-core` diff --git a/driver-reactive-streams/CLAUDE.md b/driver-reactive-streams/CLAUDE.md new file mode 100644 index 00000000000..f42f153231f --- /dev/null +++ b/driver-reactive-streams/CLAUDE.md @@ -0,0 +1,20 @@ +# CLAUDE.md - driver-reactive-streams + +Reactive Streams driver implementing the [Reactive Streams specification](https://www.reactive-streams.org/). + +**Depends on:** `bson`, `driver-core` + +## Key Packages + +- `com.mongodb.reactivestreams.client` — Publisher-based API (`MongoClient`, `MongoDatabase`, `MongoCollection`) + +## Notes + +- Every package must have a `package-info.java` +- JUnit 5 + Spock (Groovy) + Project Reactor (test utilities) + +## Key Patterns + +- All operations return `Publisher` — never block +- Respect backpressure in all implementations +- `driver-kotlin-coroutine` and `driver-scala` both build on top of this module diff --git a/driver-scala/CLAUDE.md b/driver-scala/CLAUDE.md new file mode 100644 index 00000000000..10a2e976983 --- /dev/null +++ b/driver-scala/CLAUDE.md @@ -0,0 +1,22 @@ +# CLAUDE.md - driver-scala + +Scala async driver providing Observable-based API wrapping `driver-reactive-streams`. + +**Depends on:** `bson-scala`, `driver-reactive-streams` + +**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root `gradle.properties`). Default: 2.13. + +See [README.md](./README.md) for full details on directory layout, formatting, and testing commands. + +## Key Packages + +- `org.mongodb.scala` — Scala async driver (`MongoClient`, `MongoDatabase`, `MongoCollection`, Observable-based) +- `org.mongodb.scala.model` — Scala wrappers around filter/update builders + +## Before Submitting + +```bash +./gradlew spotlessApply # Fix formatting +./gradlew :driver-scala:scalaCheck # Static checks + tests (default Scala version) +./gradlew :driver-scala:scalaCheck -PscalaVersion= # Test specific Scala version +``` diff --git a/driver-sync/CLAUDE.md b/driver-sync/CLAUDE.md new file mode 100644 index 00000000000..bf0d13f2a40 --- /dev/null +++ b/driver-sync/CLAUDE.md @@ -0,0 +1,20 @@ +# CLAUDE.md - driver-sync + +Synchronous (blocking) Java driver — the most commonly used entry point for Java applications. + +**Depends on:** `bson`, `driver-core` + +## Key Packages + +- `com.mongodb.client` — Public sync API (`MongoClient`, `MongoDatabase`, `MongoCollection`) +- `com.mongodb.client.gridfs` — GridFS sync implementation +- `com.mongodb.client.vault` — Client-side field-level encryption client +- `com.mongodb.client.internal` — Implementation helpers (private API) + +## Notes + +- Every package must have a `package-info.java` +- JUnit 5 + Spock (Groovy). Spock is heavily used but do not add new Spock tests. +- Blocking wrapper over `driver-core` async infrastructure +- Primary entry point: `MongoClients.create()` or `MongoClients.create(MongoClientSettings)` +- Optional Micrometer integration for observability diff --git a/mongodb-crypt/CLAUDE.md b/mongodb-crypt/CLAUDE.md new file mode 100644 index 00000000000..b44d2c12d41 --- /dev/null +++ b/mongodb-crypt/CLAUDE.md @@ -0,0 +1,17 @@ +# CLAUDE.md - mongodb-crypt + +Client-side field-level encryption (CSFLE) support via JNA bindings to libmongocrypt. + +**Depends on:** `bson` + +## Key Packages + +- `com.mongodb.crypt.capi` — mongocryptd C API bindings (JNA) +- `com.mongodb.internal.crypt.capi` — Internal encryption state management + +## Notes + +- Every package must have a `package-info.java` +- Tests are primarily integration tests requiring libmongocrypt native libraries +- Build downloads JNA libs for multiple platforms, embedded in the JAR +- **Security-critical module — changes require careful review** diff --git a/testing/CLAUDE.md b/testing/CLAUDE.md new file mode 100644 index 00000000000..992c7838fc5 --- /dev/null +++ b/testing/CLAUDE.md @@ -0,0 +1,9 @@ +# CLAUDE.md - testing + +Shared test resources and MongoDB specification test data. + +## Notes + +- `resources/specifications/` — Git submodule containing MongoDB specification test data (CRUD, SDAM, auth, CSFLE, retryable ops, etc.) +- `resources/logback-test.xml` — Shared logback configuration for tests +- **Do not modify spec test data** — managed upstream. Update via `git submodule update`. From 9d2913260c51b07e05fbcdfe7558c3fb285e2e54 Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Tue, 24 Mar 2026 16:21:42 +0000 Subject: [PATCH 02/10] Updated to AGENTS.md --- CLAUDE.md => AGENTS.md | 118 +++++++++--------- bom/AGENTS.md | 12 ++ bson-kotlin/{CLAUDE.md => AGENTS.md} | 2 +- bson-kotlinx/{CLAUDE.md => AGENTS.md} | 2 +- bson-record-codec/{CLAUDE.md => AGENTS.md} | 2 +- bson-scala/{CLAUDE.md => AGENTS.md} | 2 +- bson/{CLAUDE.md => AGENTS.md} | 2 +- buildSrc/{CLAUDE.md => AGENTS.md} | 14 +-- driver-benchmarks/AGENTS.md | 20 +++ driver-core/{CLAUDE.md => AGENTS.md} | 2 +- .../{CLAUDE.md => AGENTS.md} | 2 +- .../{CLAUDE.md => AGENTS.md} | 2 +- driver-kotlin-sync/{CLAUDE.md => AGENTS.md} | 2 +- driver-lambda/AGENTS.md | 16 +++ driver-legacy/{CLAUDE.md => AGENTS.md} | 2 +- .../{CLAUDE.md => AGENTS.md} | 2 +- driver-scala/{CLAUDE.md => AGENTS.md} | 2 +- driver-sync/{CLAUDE.md => AGENTS.md} | 2 +- graalvm-native-image-app/AGENTS.md | 17 +++ gradle/AGENTS.md | 19 +++ mongodb-crypt/{CLAUDE.md => AGENTS.md} | 2 +- testing/{CLAUDE.md => AGENTS.md} | 2 +- 22 files changed, 168 insertions(+), 78 deletions(-) rename CLAUDE.md => AGENTS.md (53%) create mode 100644 bom/AGENTS.md rename bson-kotlin/{CLAUDE.md => AGENTS.md} (91%) rename bson-kotlinx/{CLAUDE.md => AGENTS.md} (92%) rename bson-record-codec/{CLAUDE.md => AGENTS.md} (88%) rename bson-scala/{CLAUDE.md => AGENTS.md} (97%) rename bson/{CLAUDE.md => AGENTS.md} (98%) rename buildSrc/{CLAUDE.md => AGENTS.md} (90%) create mode 100644 driver-benchmarks/AGENTS.md rename driver-core/{CLAUDE.md => AGENTS.md} (98%) rename driver-kotlin-coroutine/{CLAUDE.md => AGENTS.md} (92%) rename driver-kotlin-extensions/{CLAUDE.md => AGENTS.md} (93%) rename driver-kotlin-sync/{CLAUDE.md => AGENTS.md} (90%) create mode 100644 driver-lambda/AGENTS.md rename driver-legacy/{CLAUDE.md => AGENTS.md} (94%) rename driver-reactive-streams/{CLAUDE.md => AGENTS.md} (94%) rename driver-scala/{CLAUDE.md => AGENTS.md} (97%) rename driver-sync/{CLAUDE.md => AGENTS.md} (96%) create mode 100644 graalvm-native-image-app/AGENTS.md create mode 100644 gradle/AGENTS.md rename mongodb-crypt/{CLAUDE.md => AGENTS.md} (95%) rename testing/{CLAUDE.md => AGENTS.md} (94%) diff --git a/CLAUDE.md b/AGENTS.md similarity index 53% rename from CLAUDE.md rename to AGENTS.md index 0b40d8ad166..2ef0fe2aff6 100644 --- a/CLAUDE.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - MongoDB Java Driver +# AGENTS.md - MongoDB Java Driver Guidelines for AI agents working on the MongoDB Java Driver codebase. @@ -6,41 +6,45 @@ Guidelines for AI agents working on the MongoDB Java Driver codebase. This is the official MongoDB JVM driver monorepo, providing Java, Kotlin, and Scala drivers for MongoDB. The driver implements the -[MongoDB Driver Specifications](https://github.com/mongodb/specifications) -and follows semantic versioning. +[MongoDB Driver Specifications](https://github.com/mongodb/specifications) and follows +semantic versioning. ### Module Structure -| Module | Purpose | -|----------------------------|-----------------------------------------------------------| -| `bson` | BSON library (core serialization) | -| `bson-kotlin` | Kotlin BSON extensions | -| `bson-kotlinx` | Kotlin serialization BSON codec | -| `bson-record-codec` | Java record codec support | -| `bson-scala` | Scala BSON extensions | -| `driver-core` | Core driver internals (connections, protocol, operations) | -| `driver-sync` | Synchronous Java driver | -| `driver-legacy` | Legacy MongoDB Java driver API | -| `driver-reactive-streams` | Reactive Streams driver | -| `driver-kotlin-coroutine` | Kotlin Coroutines driver | -| `driver-kotlin-extensions` | Kotlin driver extensions | -| `driver-kotlin-sync` | Kotlin synchronous driver | -| `driver-scala` | Scala driver | -| `mongodb-crypt` | Client-side field-level encryption | -| `testing` | Shared test resources and MongoDB specifications | +| Module | Purpose | +| --- | --- | +| `bson` | BSON library (core serialization) | +| `bson-kotlin` | Kotlin BSON extensions | +| `bson-kotlinx` | Kotlin serialization BSON codec | +| `bson-record-codec` | Java record codec support | +| `bson-scala` | Scala BSON extensions | +| `driver-core` | Core driver internals (connections, protocol, operations) | +| `driver-sync` | Synchronous Java driver | +| `driver-legacy` | Legacy MongoDB Java driver API | +| `driver-reactive-streams` | Reactive Streams driver | +| `driver-kotlin-coroutine` | Kotlin Coroutines driver | +| `driver-kotlin-extensions` | Kotlin driver extensions | +| `driver-kotlin-sync` | Kotlin synchronous driver | +| `driver-scala` | Scala driver | +| `mongodb-crypt` | Client-side field-level encryption | +| `testing` | Shared test resources and MongoDB specifications | ### Internal API Convention -All code in `com.mongodb.internal.*` and `org.bson.internal.*` is private API. -It can change at any time without notice. Never expose internal types in -public APIs, and never advise users to depend on them. +All code in `com.mongodb.internal.*` and `org.bson.internal.*` is private API. It can +change at any time without notice. +Never expose internal types in public APIs, and never advise users to depend on them. ### API Stability Annotations -- `@Alpha` - Early development, may be removed. Not for production use. -- `@Beta` - Subject to change or removal. Libraries should not depend on these. -- `@Evolving` - May add abstract methods in future releases. Safe to use, but implementing/extending bears upgrade risk. -- `@Sealed` - Must not be extended or implemented by consumers. Safe to use, but not to subclass. +- `@Alpha` - Early development, may be removed. + Not for production use. +- `@Beta` - Subject to change or removal. + Libraries should not depend on these. +- `@Evolving` - May add abstract methods in future releases. + Safe to use, but implementing/extending bears upgrade risk. +- `@Sealed` - Must not be extended or implemented by consumers. + Safe to use, but not to subclass. - `@Deprecated` - Supported until next major release but should be migrated away from. ## General @@ -60,7 +64,7 @@ public APIs, and never advise users to depend on them. ### Essential Build Commands ```bash -# Full validation (static checks + unit tests + integration tests) +# Full validation (spotlessApply + static checks + unit tests + integration tests) ./gradlew check # Integration tests (requires running MongoDB) @@ -69,12 +73,6 @@ public APIs, and never advise users to depend on them. # Single module tests ./gradlew :driver-core:test -# Format check only -./gradlew spotlessCheck - -# Auto-fix formatting -./gradlew spotlessApply - # Test with alternative JDK ./gradlew test -PjavaVersion=11 ``` @@ -82,9 +80,9 @@ public APIs, and never advise users to depend on them. ## Code Style and Formatting Formatting is enforced automatically because the Gradle `check` task depends on -`./gradlew spotlessApply`, which formats sources. To run a check without modifying -files, invoke `./gradlew spotlessCheck` manually. Do not manually reformat files -outside the scope of your changes. +`./gradlew spotlessApply`, which formats sources. +To run a check without modifying files, invoke `./gradlew spotlessCheck` manually. +Do not manually reformat files outside the scope of your changes. ### Style Rules @@ -96,7 +94,8 @@ outside the scope of your changes. - **Final parameters:** Required (FinalParameters checkstyle rule) - **Braces:** Required for all control structures (NeedBraces) - **Else placement:** On its own line (not cuddled) -- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.` +- **Copyright header:** Every Java / Kotlin / Scala file must contain + `Copyright 2008-present MongoDB, Inc.` ### Prohibited Patterns @@ -114,28 +113,35 @@ outside the scope of your changes. ### Writing Tests -- **Every code change must include tests.** New code needs new tests; modified code needs updated tests. Do not reduce test coverage. +- **Every code change must include tests.** New code needs new tests; modified code + needs updated tests. Do not reduce test coverage. - Extend existing test patterns in the module you are modifying - Unit tests should not require a running MongoDB instance -- Test methods should be descriptive: - prefer `shouldReturnEmptyListWhenNoDocumentsMatch()` over `test1()`, - use `@DisplayName` for a human readable name +- Test methods should be descriptive: prefer + `shouldReturnEmptyListWhenNoDocumentsMatch()` over `test1()`, use `@DisplayName` for a + human readable name - Clean up test data in `@AfterEach` / `cleanup()` to prevent test pollution ### MongoDB Specifications and Specification Tests -The driver implements the [MongoDB Specifications](https://github.com/mongodb/specifications). Specification test data files live in -`testing/resources/specifications/` — a git submodule for test resources. When modifying driver specification-related behavior: do -not modify existing specification tests unless they test incorrect behavior. Create new tests instead. +The driver implements the +[MongoDB Specifications](https://github.com/mongodb/specifications). +Specification test data files live in `testing/resources/specifications/` — a git +submodule for test resources. +When modifying driver specification-related behavior: do not modify existing +specification tests unless they test incorrect behavior. +Create new tests instead. ## Core Development Principles ### Essential Rules -- **Read before modifying.** Understand existing code and patterns before making changes. +- **Read before modifying.** Understand existing code and patterns before making + changes. - **Minimal changes only.** No drive-by refactoring. - **Preserve existing comments.** Only remove comments that are provably incorrect. -- **No unrelated changes.** Do not fix formatting or refactor code outside the scope of the task. +- **No unrelated changes.** Do not fix formatting or refactor code outside the scope of + the task. - **No rewrites** without explicit permission. ### Search Before Implementing @@ -148,20 +154,19 @@ Before writing new code, search the codebase for existing implementations: ### API Design -- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers. +- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow + wrappers. - **Information hiding:** Bury complexity behind simple interfaces. - **Pull complexity downward:** Make the implementer work harder so callers work less. -- **General-purpose over special-case:** Fewer flexible methods over many specialized ones. -- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them. +- **General-purpose over special-case:** Fewer flexible methods over many specialized + ones. +- **Define errors out of existence:** Design APIs so errors cannot happen rather than + detecting and handling them. ## Dependency Management Dependencies are managed centrally via `gradle/libs.versions.toml`. - -- **Never add dependencies without justification.** Dependencies are liabilities. -- **Use dependencies for:** Security/crypto, complex protocols, battle-tested algorithms. -- **Write it yourself for:** fewer than 100 LOC of straightforward code, project-specific logic, performance-critical paths. -- Optional dependencies (Netty, Snappy, Zstd, AWS SDK, SLF4J) use `optionalImplementation` and must not be required at runtime. +Optional dependencies (Netty, Snappy, Zstd, AWS SDK, SLF4J) use `optionalImplementation` and must not be required at runtime. ## Safety Rules - Do Not Modify Without Review @@ -177,7 +182,8 @@ Dependencies are managed centrally via `gradle/libs.versions.toml`. ### Evergreen (MongoDB Internal CI) -Primary CI runs on MongoDB's Evergreen system. Configuration is in `.evergreen/`. +Primary CI runs on MongoDB’s Evergreen system. +Configuration is in `.evergreen/`. ### Before Submitting diff --git a/bom/AGENTS.md b/bom/AGENTS.md new file mode 100644 index 00000000000..50262893e75 --- /dev/null +++ b/bom/AGENTS.md @@ -0,0 +1,12 @@ +# AGENTS.md - bom + +Bill of Materials (BOM) POM for the MongoDB Java Driver, simplifying dependency version management. + +**Depends on:** All published driver modules (transitive version constraints only) + +## Notes + +- Java Platform plugin — no source code, only version constraints +- Automatically includes all supported Scala version variants for `bson-scala` and `driver-scala` +- Validates generated POM: all dependencies must be `org.mongodb`, no `` or `` elements +- Do not add non-MongoDB dependencies to this module diff --git a/bson-kotlin/CLAUDE.md b/bson-kotlin/AGENTS.md similarity index 91% rename from bson-kotlin/CLAUDE.md rename to bson-kotlin/AGENTS.md index e61e7156820..a69ba608446 100644 --- a/bson-kotlin/CLAUDE.md +++ b/bson-kotlin/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - bson-kotlin +# AGENTS.md - bson-kotlin Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support. diff --git a/bson-kotlinx/CLAUDE.md b/bson-kotlinx/AGENTS.md similarity index 92% rename from bson-kotlinx/CLAUDE.md rename to bson-kotlinx/AGENTS.md index 12ec24197ab..4c6e1718c38 100644 --- a/bson-kotlinx/CLAUDE.md +++ b/bson-kotlinx/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - bson-kotlinx +# AGENTS.md - bson-kotlinx Kotlinx serialization integration for BSON, providing a pluggable serialization format. diff --git a/bson-record-codec/CLAUDE.md b/bson-record-codec/AGENTS.md similarity index 88% rename from bson-record-codec/CLAUDE.md rename to bson-record-codec/AGENTS.md index ad2cc1904e5..743532f3a5c 100644 --- a/bson-record-codec/CLAUDE.md +++ b/bson-record-codec/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - bson-record-codec +# AGENTS.md - bson-record-codec Java record codec support for BSON serialization. **Requires Java 17+.** diff --git a/bson-scala/CLAUDE.md b/bson-scala/AGENTS.md similarity index 97% rename from bson-scala/CLAUDE.md rename to bson-scala/AGENTS.md index 68b89474276..42e31da9b2e 100644 --- a/bson-scala/CLAUDE.md +++ b/bson-scala/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - bson-scala +# AGENTS.md - bson-scala Scala extensions for the BSON library, providing Scala-idiomatic wrappers and macro-based codecs. diff --git a/bson/CLAUDE.md b/bson/AGENTS.md similarity index 98% rename from bson/CLAUDE.md rename to bson/AGENTS.md index 4bc297186e3..18c3529a570 100644 --- a/bson/CLAUDE.md +++ b/bson/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - bson +# AGENTS.md - bson Core BSON (Binary JSON) library. This is the foundation module — all other modules depend on it. diff --git a/buildSrc/CLAUDE.md b/buildSrc/AGENTS.md similarity index 90% rename from buildSrc/CLAUDE.md rename to buildSrc/AGENTS.md index 10ce1750e24..5d27db5170b 100644 --- a/buildSrc/CLAUDE.md +++ b/buildSrc/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - buildSrc +# AGENTS.md - buildSrc Gradle build infrastructure providing convention plugins and shared configuration for all modules. @@ -49,12 +49,12 @@ Gradle build infrastructure providing convention plugins and shared configuratio - `check` depends on `spotlessCheck` in buildSrc itself - Java toolchain is set to Java 17 -## Keeping CLAUDE.md Files in Sync +## Keeping AGENTS.md Files in Sync -When modifying buildSrc, you **must** update the relevant CLAUDE.md files if your changes affect: +When modifying buildSrc, you **must** update the relevant AGENTS.md files if your changes affect: -- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root `CLAUDE.md` "Code Style and Formatting" section and any module CLAUDE.md files that reference formatting rules -- **Convention plugins added or removed** — update this file's plugin table and the root `CLAUDE.md` if the change affects build commands or developer workflow -- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root `CLAUDE.md` "Testing" section and affected module CLAUDE.md files +- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root `AGENTS.md` "Code Style and Formatting" section and any module AGENTS.md files that reference formatting rules +- **Convention plugins added or removed** — update this file's plugin table and the root `AGENTS.md` if the change affects build commands or developer workflow +- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root `AGENTS.md` "Testing" section and affected module AGENTS.md files - **Project plugins added or removed** — update this file's project plugin table -- **Build commands or task names changed** — update the root `CLAUDE.md` "Essential Build Commands" and "Before Submitting" sections, and any module "Before Submitting" sections +- **Build commands or task names changed** — update the root `AGENTS.md` "Essential Build Commands" and "Before Submitting" sections, and any module "Before Submitting" sections diff --git a/driver-benchmarks/AGENTS.md b/driver-benchmarks/AGENTS.md new file mode 100644 index 00000000000..1bcaee4de24 --- /dev/null +++ b/driver-benchmarks/AGENTS.md @@ -0,0 +1,20 @@ +# AGENTS.md - driver-benchmarks + +Performance benchmarks for the MongoDB Java Driver using JMH and a custom benchmark framework. + +**Depends on:** `driver-sync`, `mongodb-crypt` + +## Key Packages + +- `com.mongodb.benchmark.benchmarks` — Benchmark suite and individual benchmarks (BSON, single/multi-doc, bulk operations) +- `com.mongodb.benchmark.benchmarks.bulk` — Bulk write benchmarks +- `com.mongodb.benchmark.benchmarks.netty` — Netty transport benchmarks +- `com.mongodb.benchmark.framework` — Custom benchmark harness +- `com.mongodb.benchmark.jmh` — JMH microbenchmarks + +## Notes + +- Not published — internal testing only +- Non-standard source layout: `src/main` (no `java` subdirectory) +- Run benchmarks: `./gradlew :driver-benchmarks:run` or `./gradlew :driver-benchmarks:jmh` +- Requires `-Dorg.mongodb.benchmarks.data` and `-Dorg.mongodb.benchmarks.output` system properties diff --git a/driver-core/CLAUDE.md b/driver-core/AGENTS.md similarity index 98% rename from driver-core/CLAUDE.md rename to driver-core/AGENTS.md index 5f77f7b4cc6..20b2a5de548 100644 --- a/driver-core/CLAUDE.md +++ b/driver-core/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - driver-core +# AGENTS.md - driver-core Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala). Largest and most complex module. diff --git a/driver-kotlin-coroutine/CLAUDE.md b/driver-kotlin-coroutine/AGENTS.md similarity index 92% rename from driver-kotlin-coroutine/CLAUDE.md rename to driver-kotlin-coroutine/AGENTS.md index b5a885791be..e8060ae053f 100644 --- a/driver-kotlin-coroutine/CLAUDE.md +++ b/driver-kotlin-coroutine/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - driver-kotlin-coroutine +# AGENTS.md - driver-kotlin-coroutine Kotlin Coroutines driver providing `suspend` function-based async API. diff --git a/driver-kotlin-extensions/CLAUDE.md b/driver-kotlin-extensions/AGENTS.md similarity index 93% rename from driver-kotlin-extensions/CLAUDE.md rename to driver-kotlin-extensions/AGENTS.md index 7da92d6ed55..972b22798ac 100644 --- a/driver-kotlin-extensions/CLAUDE.md +++ b/driver-kotlin-extensions/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - driver-kotlin-extensions +# AGENTS.md - driver-kotlin-extensions Kotlin extensions providing type-safe DSLs for query and update construction. diff --git a/driver-kotlin-sync/CLAUDE.md b/driver-kotlin-sync/AGENTS.md similarity index 90% rename from driver-kotlin-sync/CLAUDE.md rename to driver-kotlin-sync/AGENTS.md index 8dbdd3797f0..6ebbcdcb454 100644 --- a/driver-kotlin-sync/CLAUDE.md +++ b/driver-kotlin-sync/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - driver-kotlin-sync +# AGENTS.md - driver-kotlin-sync Kotlin synchronous (blocking) driver — idiomatic Kotlin wrapper over `driver-sync`. diff --git a/driver-lambda/AGENTS.md b/driver-lambda/AGENTS.md new file mode 100644 index 00000000000..29a83c6ed4d --- /dev/null +++ b/driver-lambda/AGENTS.md @@ -0,0 +1,16 @@ +# AGENTS.md - driver-lambda + +AWS Lambda test application for validating the MongoDB Java Driver in Lambda environments. + +**Depends on:** `bson`, `driver-sync` + +## Key Packages + +- `com.mongodb.lambdatest` — Lambda test application entry point + +## Notes + +- Not published — internal testing only +- Java 11 source/target compatibility +- Built as a shadow JAR for Lambda deployment +- Non-standard source layout: `src/main` (no `java` subdirectory) diff --git a/driver-legacy/CLAUDE.md b/driver-legacy/AGENTS.md similarity index 94% rename from driver-legacy/CLAUDE.md rename to driver-legacy/AGENTS.md index bcf21a029fe..3da7dd342cd 100644 --- a/driver-legacy/CLAUDE.md +++ b/driver-legacy/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - driver-legacy +# AGENTS.md - driver-legacy Legacy MongoDB Java driver API — backwards compatibility facade for the 3.x API. diff --git a/driver-reactive-streams/CLAUDE.md b/driver-reactive-streams/AGENTS.md similarity index 94% rename from driver-reactive-streams/CLAUDE.md rename to driver-reactive-streams/AGENTS.md index f42f153231f..1821ed57ae4 100644 --- a/driver-reactive-streams/CLAUDE.md +++ b/driver-reactive-streams/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - driver-reactive-streams +# AGENTS.md - driver-reactive-streams Reactive Streams driver implementing the [Reactive Streams specification](https://www.reactive-streams.org/). diff --git a/driver-scala/CLAUDE.md b/driver-scala/AGENTS.md similarity index 97% rename from driver-scala/CLAUDE.md rename to driver-scala/AGENTS.md index 10a2e976983..d33f4c87559 100644 --- a/driver-scala/CLAUDE.md +++ b/driver-scala/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - driver-scala +# AGENTS.md - driver-scala Scala async driver providing Observable-based API wrapping `driver-reactive-streams`. diff --git a/driver-sync/CLAUDE.md b/driver-sync/AGENTS.md similarity index 96% rename from driver-sync/CLAUDE.md rename to driver-sync/AGENTS.md index bf0d13f2a40..e59109baed7 100644 --- a/driver-sync/CLAUDE.md +++ b/driver-sync/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - driver-sync +# AGENTS.md - driver-sync Synchronous (blocking) Java driver — the most commonly used entry point for Java applications. diff --git a/graalvm-native-image-app/AGENTS.md b/graalvm-native-image-app/AGENTS.md new file mode 100644 index 00000000000..40de264de12 --- /dev/null +++ b/graalvm-native-image-app/AGENTS.md @@ -0,0 +1,17 @@ +# AGENTS.md - graalvm-native-image-app + +GraalVM Native Image test application verifying driver compatibility with native compilation. + +**Depends on:** `bson`, `driver-core`, `driver-sync`, `driver-legacy`, `driver-reactive-streams`, `mongodb-crypt` + +## Key Packages + +- `com.mongodb.internal.graalvm` — Native image test app, GraalVM substitutions, and custom DNS support + +## Notes + +- Not published — internal testing only +- Requires `-PincludeGraalvm` Gradle property to be included in the build +- Requires GraalVM JDK 21+ installed and detected by Gradle toolchains +- Reachability metadata in `src/main/resources/META-INF/native-image/` +- Non-standard source layout: `src/main` (no `java` subdirectory) diff --git a/gradle/AGENTS.md b/gradle/AGENTS.md new file mode 100644 index 00000000000..1ef61492375 --- /dev/null +++ b/gradle/AGENTS.md @@ -0,0 +1,19 @@ +# AGENTS.md - gradle + +Gradle configuration and infrastructure for the build system. + +## Key Files + +- `libs.versions.toml` — Central version catalog defining all dependency versions, library coordinates, bundles, and plugin versions +- `wrapper/` — Gradle wrapper JAR and properties (do not modify manually — use `./gradlew wrapper --gradle-version=`) +- `scala/lib/` — Bundled Scala Ant JAR for Scala compilation support + +## Notes + +- All dependency versions are managed in `libs.versions.toml` — never declare versions inline in `build.gradle.kts` files +- **Never add dependencies without justification.** Dependencies are liabilities. +- **Use dependencies for:** Security/crypto, complex protocols, battle-tested algorithms. +- **Write it yourself for:** fewer than 100 LOC of straightforward code, project-specific logic, performance-critical paths. +- The version catalog defines `[versions]`, `[libraries]`, `[bundles]`, and `[plugins]` sections +- Scala test libraries are declared per Scala version (v3, v2-v13, v2-v12, v2-v11) +- When adding or updating dependencies, modify `libs.versions.toml` and reference via `libs.` in build scripts diff --git a/mongodb-crypt/CLAUDE.md b/mongodb-crypt/AGENTS.md similarity index 95% rename from mongodb-crypt/CLAUDE.md rename to mongodb-crypt/AGENTS.md index b44d2c12d41..17d5447654b 100644 --- a/mongodb-crypt/CLAUDE.md +++ b/mongodb-crypt/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - mongodb-crypt +# AGENTS.md - mongodb-crypt Client-side field-level encryption (CSFLE) support via JNA bindings to libmongocrypt. diff --git a/testing/CLAUDE.md b/testing/AGENTS.md similarity index 94% rename from testing/CLAUDE.md rename to testing/AGENTS.md index 992c7838fc5..6d1b0d60502 100644 --- a/testing/CLAUDE.md +++ b/testing/AGENTS.md @@ -1,4 +1,4 @@ -# CLAUDE.md - testing +# AGENTS.md - testing Shared test resources and MongoDB specification test data. From 022bff8ef9b2e491d54855749ce333de896a14e0 Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Tue, 24 Mar 2026 16:52:25 +0000 Subject: [PATCH 03/10] Updated to move towards the open standard for AI agent instructions --- .agents/skills/api-design/SKILL.md | 42 +++++ .agents/skills/evergreen/SKILL.md | 33 ++++ .agents/skills/project-guide/SKILL.md | 64 +++++++ .agents/skills/spec-tests/SKILL.md | 43 +++++ .agents/skills/style-reference/SKILL.md | 45 +++++ .agents/skills/testing-guide/SKILL.md | 61 +++++++ .claude/skills | 1 + AGENTS.md | 219 +++++------------------- CLAUDE.md | 1 + bom/AGENTS.md | 9 +- bom/CLAUDE.md | 1 + bson-kotlin/AGENTS.md | 4 - bson-kotlin/CLAUDE.md | 1 + bson-kotlinx/AGENTS.md | 4 - bson-kotlinx/CLAUDE.md | 1 + bson-record-codec/AGENTS.md | 7 +- bson-record-codec/CLAUDE.md | 1 + bson-scala/AGENTS.md | 9 +- bson-scala/CLAUDE.md | 1 + bson/AGENTS.md | 12 +- bson/CLAUDE.md | 1 + buildSrc/AGENTS.md | 89 +++++----- buildSrc/CLAUDE.md | 1 + driver-benchmarks/AGENTS.md | 12 +- driver-benchmarks/CLAUDE.md | 1 + driver-core/AGENTS.md | 26 ++- driver-core/CLAUDE.md | 1 + driver-kotlin-coroutine/AGENTS.md | 4 +- driver-kotlin-coroutine/CLAUDE.md | 1 + driver-kotlin-extensions/AGENTS.md | 7 +- driver-kotlin-extensions/CLAUDE.md | 1 + driver-kotlin-sync/AGENTS.md | 7 +- driver-kotlin-sync/CLAUDE.md | 1 + driver-lambda/AGENTS.md | 3 +- driver-lambda/CLAUDE.md | 1 + driver-legacy/AGENTS.md | 8 +- driver-legacy/CLAUDE.md | 1 + driver-reactive-streams/AGENTS.md | 7 +- driver-reactive-streams/CLAUDE.md | 1 + driver-scala/AGENTS.md | 9 +- driver-scala/CLAUDE.md | 1 + driver-sync/AGENTS.md | 13 +- driver-sync/CLAUDE.md | 1 + graalvm-native-image-app/AGENTS.md | 9 +- graalvm-native-image-app/CLAUDE.md | 1 + gradle/AGENTS.md | 19 +- gradle/CLAUDE.md | 1 + mongodb-crypt/AGENTS.md | 1 - mongodb-crypt/CLAUDE.md | 1 + testing/AGENTS.md | 6 +- testing/CLAUDE.md | 1 + 51 files changed, 506 insertions(+), 289 deletions(-) create mode 100644 .agents/skills/api-design/SKILL.md create mode 100644 .agents/skills/evergreen/SKILL.md create mode 100644 .agents/skills/project-guide/SKILL.md create mode 100644 .agents/skills/spec-tests/SKILL.md create mode 100644 .agents/skills/style-reference/SKILL.md create mode 100644 .agents/skills/testing-guide/SKILL.md create mode 120000 .claude/skills create mode 100644 CLAUDE.md create mode 100644 bom/CLAUDE.md create mode 100644 bson-kotlin/CLAUDE.md create mode 100644 bson-kotlinx/CLAUDE.md create mode 100644 bson-record-codec/CLAUDE.md create mode 100644 bson-scala/CLAUDE.md create mode 100644 bson/CLAUDE.md create mode 100644 buildSrc/CLAUDE.md create mode 100644 driver-benchmarks/CLAUDE.md create mode 100644 driver-core/CLAUDE.md create mode 100644 driver-kotlin-coroutine/CLAUDE.md create mode 100644 driver-kotlin-extensions/CLAUDE.md create mode 100644 driver-kotlin-sync/CLAUDE.md create mode 100644 driver-lambda/CLAUDE.md create mode 100644 driver-legacy/CLAUDE.md create mode 100644 driver-reactive-streams/CLAUDE.md create mode 100644 driver-scala/CLAUDE.md create mode 100644 driver-sync/CLAUDE.md create mode 100644 graalvm-native-image-app/CLAUDE.md create mode 100644 gradle/CLAUDE.md create mode 100644 mongodb-crypt/CLAUDE.md create mode 100644 testing/CLAUDE.md diff --git a/.agents/skills/api-design/SKILL.md b/.agents/skills/api-design/SKILL.md new file mode 100644 index 00000000000..ada28dfebc7 --- /dev/null +++ b/.agents/skills/api-design/SKILL.md @@ -0,0 +1,42 @@ +--- +name: api-design +description: API stability annotations, design principles, and patterns for the MongoDB Java Driver. Use when adding or modifying public API surface — new classes, methods, interfaces, or changing method signatures. +--- + +# API Design + +## API Stability Annotations + +- `@Alpha` — Early development, may be removed. Not for production use. +- `@Beta` — Subject to change or removal. Libraries should not depend on these. +- `@Evolving` — May add abstract methods in future releases. Safe to use, but implementing/extending bears upgrade risk. +- `@Sealed` — Must not be extended or implemented by consumers. Safe to use, but not to subclass. +- `@Deprecated` — Supported until next major release but should be migrated away from. + +## Design Principles + +- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers. +- **Information hiding:** Bury complexity behind simple interfaces. +- **Pull complexity downward:** Make the implementer work harder so callers work less. +- **General-purpose over special-case:** Fewer flexible methods over many specialized ones. +- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them. + +## Search Before Implementing + +Before writing new code, search the codebase for existing implementations: + +- Check if a utility method already exists in `com.mongodb.internal.*` +- Check if a similar pattern is established elsewhere in the module +- Reuse existing well-tested infrastructure over creating duplicates + +## Key Patterns + +- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()` +- Fluent builders: `MongoClientSettings.builder()` is the primary entry point +- Abstract core with pluggable transports + +## Public API Rules + +- Breaking changes require a major version bump - ALWAYS warn if breaking binary compatibility +- All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in public APIs +- Every public package must have a `package-info.java` diff --git a/.agents/skills/evergreen/SKILL.md b/.agents/skills/evergreen/SKILL.md new file mode 100644 index 00000000000..eeb438567cd --- /dev/null +++ b/.agents/skills/evergreen/SKILL.md @@ -0,0 +1,33 @@ +--- +name: evergreen +description: Evergreen CI infrastructure, configuration validation. Use when modifying .evergreen/ config, preparing to submit changes or understanding the Evergreen test matrix. +--- + +# Evergreen + +## Evergreen (MongoDB Internal CI) + +Primary CI runs on MongoDB's Evergreen system. Configuration lives in `.evergreen/`. + +- Do not modify `.evergreen/` configuration without review +- Evergreen runs the full test matrix across MongoDB versions, OS platforms, and JDK versions + +## Validating Evergreen Configuration + +After modifying `.evergreen/` files, validate the config locally: + +```bash +evergreen validate $PROJECT_PATH/.evergreen/.evg.yml +``` + +Always run this before submitting changes to `.evergreen/` to catch syntax errors and invalid task definitions. + +## Testing with a Patch Build + +To test your changes on Evergreen before merging, create a patch build: + +```bash +evergreen patch -u +``` + +This uploads your uncommitted and committed local changes as a patch build on Evergreen, allowing you to run the full CI test matrix against your branch. diff --git a/.agents/skills/project-guide/SKILL.md b/.agents/skills/project-guide/SKILL.md new file mode 100644 index 00000000000..eeeb3b6b686 --- /dev/null +++ b/.agents/skills/project-guide/SKILL.md @@ -0,0 +1,64 @@ +--- +name: project-guide +description: Project structure, dependency graph, and guide for finding the right project to work in. Use when starting a task and unsure which project owns the relevant code, or when you need to understand cross-project dependencies. +--- + +# Project Guide + +## Project Structure + +| Project | Purpose | +| --- | --- | +| `bson` | BSON library (core serialization) | +| `bson-kotlin` | Kotlin BSON extensions | +| `bson-kotlinx` | Kotlin serialization BSON codec | +| `bson-record-codec` | Java record codec support | +| `bson-scala` | Scala BSON extensions | +| `driver-core` | Core driver internals (connections, protocol, operations) | +| `driver-sync` | Synchronous Java driver | +| `driver-legacy` | Legacy MongoDB Java driver API | +| `driver-reactive-streams` | Reactive Streams driver | +| `driver-kotlin-coroutine` | Kotlin Coroutines driver | +| `driver-kotlin-extensions` | Kotlin driver extensions | +| `driver-kotlin-sync` | Kotlin synchronous driver | +| `driver-scala` | Scala driver | +| `mongodb-crypt` | Client-side field-level encryption | +| `bom` | Bill of Materials for dependency management | +| `testing` | Shared test resources and MongoDB specifications | +| `buildSrc` | Gradle convention plugins and build infrastructure | +| `driver-benchmarks` | JMH and custom performance benchmarks (not published) | +| `driver-lambda` | AWS Lambda test application (not published) | +| `graalvm-native-image-app` | GraalVM Native Image compatibility testing (not published) | + +## Dependency Graph (simplified) + +``` +bson + ├── bson-kotlin + ├── bson-kotlinx + ├── bson-record-codec + ├── bson-scala + └── driver-core + ├── driver-sync + │ ├── driver-legacy + │ ├── driver-kotlin-sync + │ └── driver-lambda + ├── driver-reactive-streams + │ ├── driver-kotlin-coroutine + │ └── driver-scala + └── driver-kotlin-extensions +``` + +## Finding the Right Module + +- **BSON serialization/codecs:** `bson` (or `bson-kotlin`/`bson-kotlinx`/`bson-scala` for language-specific) +- **Query builders, filters, aggregates:** `driver-core` (`com.mongodb.client.model`) +- **Sync Java API:** `driver-sync` +- **Reactive API:** `driver-reactive-streams` +- **Kotlin coroutines:** `driver-kotlin-coroutine` +- **Kotlin DSL builders:** `driver-kotlin-extensions` +- **Scala driver:** `driver-scala` +- **Connection, protocol, auth internals:** `driver-core` (`com.mongodb.internal.*`) +- **Build plugins, formatting, test infra:** `buildSrc` + +Each module has its own `AGENTS.md` with module-specific packages, patterns, and notes. diff --git a/.agents/skills/spec-tests/SKILL.md b/.agents/skills/spec-tests/SKILL.md new file mode 100644 index 00000000000..9ae006d47ef --- /dev/null +++ b/.agents/skills/spec-tests/SKILL.md @@ -0,0 +1,43 @@ +--- +name: spec-tests +description: How to work with MongoDB specification tests — structure, rules, and adding new spec test support. Use when implementing or modifying behavior defined by the MongoDB Driver Specifications, or when working with the test data in testing/resources/specifications/. +--- + +# MongoDB Specification Tests + +## Overview + +The driver implements the +[MongoDB Driver Specifications](https://github.com/mongodb/specifications). Specification +test data files live in `testing/resources/specifications/` — a git submodule. + +## Rules + +- **Do not modify existing specification tests** unless they test incorrect behavior +- **Do not modify spec test data** — it is managed upstream +- Create new tests instead of modifying existing ones +- Update the submodule via `git submodule update` + +## Structure + +Spec test data is organized by specification area: + +- CRUD, SDAM, auth, CSFLE, retryable operations, and more +- Each spec area has JSON/YAML test data files defining inputs and expected outputs +- Driver test runners parse these files and execute against the driver + +## Test Data Location + +``` +testing/ + resources/ + specifications/ # Git submodule — do not edit directly + logback-test.xml # Shared logback configuration for tests +``` + +## Adding Spec Test Support + +1. Check `testing/resources/specifications/` for the relevant spec test data +2. Find existing test runners in the module (look for `*SpecificationTest*` or similar) +3. Extend existing patterns — each module handles spec tests slightly differently +4. Ensure tests run with `./gradlew check` or the module's test task diff --git a/.agents/skills/style-reference/SKILL.md b/.agents/skills/style-reference/SKILL.md new file mode 100644 index 00000000000..10002a0dbf0 --- /dev/null +++ b/.agents/skills/style-reference/SKILL.md @@ -0,0 +1,45 @@ +--- +name: style-reference +description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in the MongoDB Java Driver. Use when you need specific formatting rules beyond the basics in root AGENTS.md — e.g., line length, import ordering, brace style, or language-specific formatter configuration. Spotless auto-enforces most rules. +--- + +# Style Reference + +## Java Style Rules + +- **Max line length:** 140 characters +- **Indentation:** 4 spaces (no tabs) +- **Line endings:** LF (Unix) +- **Charset:** UTF-8 +- **Star imports:** Prohibited (AvoidStarImport) +- **Final parameters:** Required (FinalParameters checkstyle rule) +- **Braces:** Required for all control structures (NeedBraces) +- **Else placement:** On its own line (not cuddled) +- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.` +- **Formatter:** Palantir Java Format + +## Kotlin Style Rules + +- **Formatter:** ktfmt dropbox style, max width 120 +- **Static analysis:** detekt + +## Scala Style Rules + +- **Formatter:** scalafmt +- **Supported versions:** 2.11, 2.12, 2.13, 3 (default: 2.13) + +## Groovy Style Rules + +- **Static analysis:** CodeNarc + +## Prohibited Patterns + +- `System.out.println` / `System.err.println` — Use SLF4J logging +- `e.printStackTrace()` — Use proper logging/error handling + +## Formatting Commands + +```bash +./gradlew spotlessApply # Auto-fix all formatting +./gradlew spotlessCheck # Check without modifying +``` diff --git a/.agents/skills/testing-guide/SKILL.md b/.agents/skills/testing-guide/SKILL.md new file mode 100644 index 00000000000..731834018e0 --- /dev/null +++ b/.agents/skills/testing-guide/SKILL.md @@ -0,0 +1,61 @@ +--- +name: testing-guide +description: Testing frameworks, conventions, and commands for the MongoDB Java Driver. Use when writing or running tests — covers framework selection per module, test naming conventions, integration test setup, and how to run specific test subsets. +--- + +# Testing Guide + +## Frameworks + +| Framework | Usage | Notes | +| --- | --- | --- | +| JUnit 5 (Jupiter) | Primary unit test framework | All new tests | +| Spock (Groovy) | Legacy tests | Do not add new Spock tests | +| Mockito | Mocking | Use `mockito-junit-jupiter` integration | +| ScalaTest | Scala module testing | FlatSpec + ShouldMatchers | +| Project Reactor | Reactive test utilities | `driver-reactive-streams` tests | + +## Writing Tests + +- Every code change must include tests +- Extend existing test patterns in the module you are modifying +- Unit tests must not require a running MongoDB instance +- Descriptive method names: `shouldReturnEmptyListWhenNoDocumentsMatch()` not `test1()` +- Use `@DisplayName` for human-readable names +- Clean up test data in `@AfterEach` / `cleanup()` to prevent pollution + +## Running Tests + +```bash +# All tests (unit + integration) +./gradlew check + +# Single module +./gradlew :driver-core:test + +# Integration tests (requires MongoDB) +./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017" + +# Specific test class +./gradlew :driver-core:test --tests "com.mongodb.internal.operation.FindOperationTest" + +# Alternative JDK +./gradlew test -PjavaVersion=11 + +# Scala tests (all versions) +./gradlew scalaCheck +``` + +## Module-Specific Notes + +- **driver-core:** Largest test suite — JUnit 5 + Spock + Mockito +- **driver-sync:** JUnit 5 + Spock (heavy Spock usage, but don't add new) +- **driver-reactive-streams:** JUnit 5 + Spock + Project Reactor +- **bson-scala / driver-scala:** ScalaTest, test per Scala version +- **Kotlin modules:** JUnit 5 + mockito-kotlin + +## Integration Tests + +- Require a running MongoDB instance +- Set connection URI: `-Dorg.mongodb.test.uri="mongodb://localhost:27017"` +- Integration test source set configured via `conventions/testing-integration.gradle.kts` diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 00000000000..2b7a412b8fa --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 2ef0fe2aff6..6cb2e23ebc8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,194 +1,63 @@ # AGENTS.md - MongoDB Java Driver -Guidelines for AI agents working on the MongoDB Java Driver codebase. - -## Project Overview - -This is the official MongoDB JVM driver monorepo, providing Java, Kotlin, and Scala -drivers for MongoDB. The driver implements the -[MongoDB Driver Specifications](https://github.com/mongodb/specifications) and follows -semantic versioning. - -### Module Structure - -| Module | Purpose | -| --- | --- | -| `bson` | BSON library (core serialization) | -| `bson-kotlin` | Kotlin BSON extensions | -| `bson-kotlinx` | Kotlin serialization BSON codec | -| `bson-record-codec` | Java record codec support | -| `bson-scala` | Scala BSON extensions | -| `driver-core` | Core driver internals (connections, protocol, operations) | -| `driver-sync` | Synchronous Java driver | -| `driver-legacy` | Legacy MongoDB Java driver API | -| `driver-reactive-streams` | Reactive Streams driver | -| `driver-kotlin-coroutine` | Kotlin Coroutines driver | -| `driver-kotlin-extensions` | Kotlin driver extensions | -| `driver-kotlin-sync` | Kotlin synchronous driver | -| `driver-scala` | Scala driver | -| `mongodb-crypt` | Client-side field-level encryption | -| `testing` | Shared test resources and MongoDB specifications | - -### Internal API Convention - -All code in `com.mongodb.internal.*` and `org.bson.internal.*` is private API. It can -change at any time without notice. -Never expose internal types in public APIs, and never advise users to depend on them. - -### API Stability Annotations - -- `@Alpha` - Early development, may be removed. - Not for production use. -- `@Beta` - Subject to change or removal. - Libraries should not depend on these. -- `@Evolving` - May add abstract methods in future releases. - Safe to use, but implementing/extending bears upgrade risk. -- `@Sealed` - Must not be extended or implemented by consumers. - Safe to use, but not to subclass. -- `@Deprecated` - Supported until next major release but should be migrated away from. - -## General - -- Follow existing conventions. Keep it simple. -- When stuck: stop, explain the problem, propose alternatives, ask for guidance. -- When uncertain: ask rather than assume. Present options with trade-offs. - -## Build System - -- **Build tool:** Gradle with Kotlin DSL -- **Build JDK:** Java 17+ -- **Source compatibility (baseline):** Java 8 for most modules / main driver artifacts -- **Version catalog:** `gradle/libs.versions.toml` -- **Convention plugins:** `buildSrc/src/main/kotlin/conventions/` - -### Essential Build Commands +Official MongoDB JVM driver monorepo (Java, Kotlin, Scala). +Implements the +[MongoDB Driver Specifications](https://github.com/mongodb/specifications). +Each module has its own `AGENTS.md` with module-specific guidance. + +## Core Rules + +- Read before modifying. + Understand existing code and patterns first. +- Minimal changes only. + No drive-by refactoring or unrelated changes. +- Preserve existing comments. + Only remove if provably incorrect. +- No rewrites without explicit permission. +- When stuck or uncertain: stop, explain, propose alternatives, ask. +- All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in + public APIs. + +## Build + +- Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. +- Versions: `gradle/libs.versions.toml`. Plugins: + `buildSrc/src/main/kotlin/conventions/`. ```bash -# Full validation (spotlessApply + static checks + unit tests + integration tests) -./gradlew check - -# Integration tests (requires running MongoDB) +./gradlew check # Full validation (format + static checks + tests) +./gradlew :driver-core:test # Single module tests ./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017" - -# Single module tests -./gradlew :driver-core:test - -# Test with alternative JDK -./gradlew test -PjavaVersion=11 ``` -## Code Style and Formatting - -Formatting is enforced automatically because the Gradle `check` task depends on -`./gradlew spotlessApply`, which formats sources. -To run a check without modifying files, invoke `./gradlew spotlessCheck` manually. -Do not manually reformat files outside the scope of your changes. - -### Style Rules - -- **Max line length:** 140 characters -- **Indentation:** 4 spaces (no tabs) -- **Line endings:** LF (Unix) -- **Charset:** UTF-8 -- **Star imports:** Prohibited (AvoidStarImport) -- **Final parameters:** Required (FinalParameters checkstyle rule) -- **Braces:** Required for all control structures (NeedBraces) -- **Else placement:** On its own line (not cuddled) -- **Copyright header:** Every Java / Kotlin / Scala file must contain - `Copyright 2008-present MongoDB, Inc.` +## Formatting -### Prohibited Patterns +`check` runs `spotlessApply` automatically. +Do not reformat outside your changes. -- `System.out.println` / `System.err.println` — Use SLF4J logging -- `e.printStackTrace()` — Use proper logging/error handling +- No `System.out.println` / `System.err.println` — use SLF4J +- No `e.printStackTrace()` — use proper error handling +- Copyright header required: `Copyright 2008-present MongoDB, Inc.` +- Every public package must have a `package-info.java` ## Testing -### Frameworks +- Every code change must include tests. + Do not reduce coverage. +- JUnit 5 primary. Spock is legacy — do not add new Spock tests. +- Unit tests must not require a running MongoDB instance. +- Descriptive method names or `@DisplayName`. Clean up in `@AfterEach`. -- **JUnit 5** (Jupiter) - Primary unit test framework -- **Spock** (Groovy) - Legacy, do not add new Spock tests. -- **Mockito** - Mocking -- **ScalaTest** - Scala module testing +## Safety — Do Not Modify Without Review -### Writing Tests - -- **Every code change must include tests.** New code needs new tests; modified code - needs updated tests. Do not reduce test coverage. -- Extend existing test patterns in the module you are modifying -- Unit tests should not require a running MongoDB instance -- Test methods should be descriptive: prefer - `shouldReturnEmptyListWhenNoDocumentsMatch()` over `test1()`, use `@DisplayName` for a - human readable name -- Clean up test data in `@AfterEach` / `cleanup()` to prevent test pollution - -### MongoDB Specifications and Specification Tests - -The driver implements the -[MongoDB Specifications](https://github.com/mongodb/specifications). -Specification test data files live in `testing/resources/specifications/` — a git -submodule for test resources. -When modifying driver specification-related behavior: do not modify existing -specification tests unless they test incorrect behavior. -Create new tests instead. - -## Core Development Principles - -### Essential Rules - -- **Read before modifying.** Understand existing code and patterns before making - changes. -- **Minimal changes only.** No drive-by refactoring. -- **Preserve existing comments.** Only remove comments that are provably incorrect. -- **No unrelated changes.** Do not fix formatting or refactor code outside the scope of - the task. -- **No rewrites** without explicit permission. - -### Search Before Implementing - -Before writing new code, search the codebase for existing implementations: - -- Check if a utility method already exists in `com.mongodb.internal.*` -- Check if a similar pattern is established elsewhere in the module -- Reuse existing well-tested infrastructure over creating duplicates - -### API Design - -- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow - wrappers. -- **Information hiding:** Bury complexity behind simple interfaces. -- **Pull complexity downward:** Make the implementer work harder so callers work less. -- **General-purpose over special-case:** Fewer flexible methods over many specialized - ones. -- **Define errors out of existence:** Design APIs so errors cannot happen rather than - detecting and handling them. - -## Dependency Management - -Dependencies are managed centrally via `gradle/libs.versions.toml`. -Optional dependencies (Netty, Snappy, Zstd, AWS SDK, SLF4J) use `optionalImplementation` and must not be required at runtime. - -## Safety Rules - Do Not Modify Without Review - -- Wire protocol implementation (connection/authentication handshakes) -- Security-critical authentication and encryption code -- Public API contracts (breaking changes require major version bump) +- Wire protocol / authentication handshakes +- Security-critical encryption code +- Public API contracts (breaking changes need major version bump) - BSON specification compliance -- Configuration files containing credentials or secrets -- CI/CD pipeline configurations in `.evergreen/` -- Release and publishing scripts - -## CI/CD - -### Evergreen (MongoDB Internal CI) - -Primary CI runs on MongoDB’s Evergreen system. -Configuration is in `.evergreen/`. - -### Before Submitting +- Credentials, secrets, `.evergreen/` config, release scripts -Run locally at minimum: +## Before Submitting ```bash -./gradlew doc check scalaCheck # Generates docs, runs static checks + tests +./gradlew doc check scalaCheck ``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/bom/AGENTS.md b/bom/AGENTS.md index 50262893e75..7f5f8b928e6 100644 --- a/bom/AGENTS.md +++ b/bom/AGENTS.md @@ -1,12 +1,15 @@ # AGENTS.md - bom -Bill of Materials (BOM) POM for the MongoDB Java Driver, simplifying dependency version management. +Bill of Materials (BOM) POM for the MongoDB Java Driver, simplifying dependency version +management. **Depends on:** All published driver modules (transitive version constraints only) ## Notes - Java Platform plugin — no source code, only version constraints -- Automatically includes all supported Scala version variants for `bson-scala` and `driver-scala` -- Validates generated POM: all dependencies must be `org.mongodb`, no `` or `` elements +- Automatically includes all supported Scala version variants for `bson-scala` and + `driver-scala` +- Validates generated POM: all dependencies must be `org.mongodb`, no `` or + `` elements - Do not add non-MongoDB dependencies to this module diff --git a/bom/CLAUDE.md b/bom/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/bom/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/bson-kotlin/AGENTS.md b/bson-kotlin/AGENTS.md index a69ba608446..a78b47573c2 100644 --- a/bson-kotlin/AGENTS.md +++ b/bson-kotlin/AGENTS.md @@ -7,7 +7,3 @@ Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support ## Key Packages - `org.bson.codecs.kotlin` — Kotlin-specific codecs with inline reified functions - -## Notes - -- Formatting: ktfmt dropbox style, max width 120 diff --git a/bson-kotlin/CLAUDE.md b/bson-kotlin/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/bson-kotlin/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/bson-kotlinx/AGENTS.md b/bson-kotlinx/AGENTS.md index 4c6e1718c38..352650c6ee1 100644 --- a/bson-kotlinx/AGENTS.md +++ b/bson-kotlinx/AGENTS.md @@ -8,7 +8,3 @@ Kotlinx serialization integration for BSON, providing a pluggable serialization - `org.bson.codecs.kotlinx` — Kotlinx serialization BSON format support - `org.bson.codecs.kotlinx.utils` — Helper utilities - -## Notes - -- Formatting: ktfmt dropbox style, max width 120 diff --git a/bson-kotlinx/CLAUDE.md b/bson-kotlinx/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/bson-kotlinx/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/bson-record-codec/AGENTS.md b/bson-record-codec/AGENTS.md index 743532f3a5c..28fb1ae5a1e 100644 --- a/bson-record-codec/AGENTS.md +++ b/bson-record-codec/AGENTS.md @@ -1,13 +1,10 @@ # AGENTS.md - bson-record-codec -Java record codec support for BSON serialization. **Requires Java 17+.** +Java record codec support for BSON serialization. +**Requires Java 17+.** **Depends on:** `bson` ## Key Packages - `org.bson.codecs.record` — `RecordCodecProvider` and record field accessors - -## Notes - -- Every package must have a `package-info.java` diff --git a/bson-record-codec/CLAUDE.md b/bson-record-codec/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/bson-record-codec/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/bson-scala/AGENTS.md b/bson-scala/AGENTS.md index 42e31da9b2e..82508c31278 100644 --- a/bson-scala/AGENTS.md +++ b/bson-scala/AGENTS.md @@ -1,12 +1,15 @@ # AGENTS.md - bson-scala -Scala extensions for the BSON library, providing Scala-idiomatic wrappers and macro-based codecs. +Scala extensions for the BSON library, providing Scala-idiomatic wrappers and +macro-based codecs. **Depends on:** `bson` -**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root `gradle.properties`). Default: 2.13. +**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root +`gradle.properties`). Default: 2.13. -See [README.md](./README.md) for full details on directory layout, formatting, and testing commands. +See [README.md](./README.md) for full details on directory layout, formatting, and +testing commands. ## Key Packages diff --git a/bson-scala/CLAUDE.md b/bson-scala/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/bson-scala/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/bson/AGENTS.md b/bson/AGENTS.md index 18c3529a570..d0427c5510f 100644 --- a/bson/AGENTS.md +++ b/bson/AGENTS.md @@ -1,12 +1,17 @@ # AGENTS.md - bson -Core BSON (Binary JSON) library. This is the foundation module — all other modules depend on it. +Core BSON (Binary JSON) library. +This is the foundation module — all other modules depend on it. + +**Depends on:** None (foundation module) ## Key Packages -- `org.bson` — Core BSON value types (`BsonDocument`, `BsonValue`, `BsonReader`, `BsonWriter`) +- `org.bson` — Core BSON value types (`BsonDocument`, `BsonValue`, `BsonReader`, + `BsonWriter`) - `org.bson.codecs` — Codec framework (`Encoder`, `Decoder`, `Codec`) -- `org.bson.codecs.configuration` — Codec registry and provider infrastructure (`CodecRegistry`, `CodecProvider`) +- `org.bson.codecs.configuration` — Codec registry and provider infrastructure + (`CodecRegistry`, `CodecProvider`) - `org.bson.codecs.pojo` — POJO codec support with conventions and property modeling - `org.bson.codecs.jsr310` — Java 8+ date/time codec support - `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`, `JsonMode`) @@ -16,7 +21,6 @@ Core BSON (Binary JSON) library. This is the foundation module — all other mod ## Notes -- Every package must have a `package-info.java` - JUnit 5 + Spock (Groovy) tests in both unit and functional dirs ## Key Patterns diff --git a/bson/CLAUDE.md b/bson/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/bson/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/buildSrc/AGENTS.md b/buildSrc/AGENTS.md index 5d27db5170b..214def88fc3 100644 --- a/buildSrc/AGENTS.md +++ b/buildSrc/AGENTS.md @@ -1,60 +1,71 @@ # AGENTS.md - buildSrc -Gradle build infrastructure providing convention plugins and shared configuration for all modules. +Gradle build infrastructure providing convention plugins and shared configuration for +all modules. ## Key Directories -- `src/main/kotlin/conventions/` — Convention plugins applied by modules (formatting, testing, publishing, static analysis) +- `src/main/kotlin/conventions/` — Convention plugins applied by modules (formatting, + testing, publishing, static analysis) - `src/main/kotlin/project/` — Base project plugins for Java, Kotlin, and Scala modules - `src/main/kotlin/ProjectExtensions.kt` — Shared Gradle extension utilities ## Convention Plugins -| Plugin | Purpose | -|-----------------------------------------|-----------------------------------------------------------------------------------| -| `spotless` | Code formatting (Java: Palantir; Kotlin: ktfmt dropbox, max 120; Scala: scalafmt) | -| `codenarc` | Groovy static analysis | -| `detekt` | Kotlin static analysis | -| `spotbugs` | Java bug detection | -| `bnd` | OSGi bundle metadata | -| `dokka` | Kotlin documentation generation | -| `javadoc` | Java documentation generation | -| `scaladoc` | Scala documentation generation | -| `publishing` | Maven Central publishing configuration | -| `git-version` | Version derivation from git tags | -| `optional` | Optional dependency support (`optionalImplementation`) | -| `testing-base` | Shared test configuration | -| `testing-integration` | Integration test source set and tasks | -| `testing-junit` | JUnit 5 test setup | -| `testing-junit-vintage` | JUnit 4 compatibility | -| `testing-spock` | Spock framework setup | -| `testing-spock-exclude-slow` | Spock with slow test exclusion | -| `testing-mockito` | Mockito setup | -| `test-artifacts` | Test artifact sharing between modules | -| `test-artifacts-runtime-dependencies` | Runtime dependency sharing for tests | -| `test-include-optionals` | Include optional dependencies in tests | +| Plugin | Purpose | +| --- | --- | +| `spotless` | Code formatting (Java: Palantir; Kotlin: ktfmt dropbox, max 120; Scala: scalafmt) | +| `codenarc` | Groovy static analysis | +| `detekt` | Kotlin static analysis | +| `spotbugs` | Java bug detection | +| `bnd` | OSGi bundle metadata | +| `dokka` | Kotlin documentation generation | +| `javadoc` | Java documentation generation | +| `scaladoc` | Scala documentation generation | +| `publishing` | Maven Central publishing configuration | +| `git-version` | Version derivation from git tags | +| `optional` | Optional dependency support (`optionalImplementation`) | +| `testing-base` | Shared test configuration | +| `testing-integration` | Integration test source set and tasks | +| `testing-junit` | JUnit 5 test setup | +| `testing-junit-vintage` | JUnit 4 compatibility | +| `testing-spock` | Spock framework setup | +| `testing-spock-exclude-slow` | Spock with slow test exclusion | +| `testing-mockito` | Mockito setup | +| `test-artifacts` | Test artifact sharing between modules | +| `test-artifacts-runtime-dependencies` | Runtime dependency sharing for tests | +| `test-include-optionals` | Include optional dependencies in tests | ## Project Plugins -| Plugin | Purpose | -|------------------|------------------------------------------------------------| -| `project/base` | Common settings for all modules | -| `project/java` | Java module conventions (source compatibility, checkstyle) | -| `project/kotlin` | Kotlin module conventions | -| `project/scala` | Scala module conventions (multi-version support) | +| Plugin | Purpose | +| --- | --- | +| `project/base` | Common settings for all modules | +| `project/java` | Java module conventions (source compatibility, checkstyle) | +| `project/kotlin` | Kotlin module conventions | +| `project/scala` | Scala module conventions (multi-version support) | ## Notes -- Formatting: ktfmt dropbox style, max width 120 (for buildSrc's own code) +- Formatting: ktfmt dropbox style, max width 120 (for buildSrc’s own code) - `check` depends on `spotlessCheck` in buildSrc itself - Java toolchain is set to Java 17 -## Keeping AGENTS.md Files in Sync +## Keeping AGENTS.md and Skills in Sync -When modifying buildSrc, you **must** update the relevant AGENTS.md files if your changes affect: +When modifying buildSrc, you **must** update the relevant AGENTS.md files and skills (in +`.agents/skills/`) if your changes affect: -- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root `AGENTS.md` "Code Style and Formatting" section and any module AGENTS.md files that reference formatting rules -- **Convention plugins added or removed** — update this file's plugin table and the root `AGENTS.md` if the change affects build commands or developer workflow -- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root `AGENTS.md` "Testing" section and affected module AGENTS.md files -- **Project plugins added or removed** — update this file's project plugin table -- **Build commands or task names changed** — update the root `AGENTS.md` "Essential Build Commands" and "Before Submitting" sections, and any module "Before Submitting" sections +- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root + `AGENTS.md` “Formatting” section, the `style-reference` skill, and any module + AGENTS.md files that reference formatting rules +- **Convention plugins added or removed** — update this file’s plugin table and the root + `AGENTS.md` if the change affects build commands or developer workflow +- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root + `AGENTS.md` “Testing” section, the `testing-guide` skill, and affected module + AGENTS.md files +- **Project plugins added or removed** — update this file’s project plugin table +- **Build commands or task names changed** — update the root `AGENTS.md` “Build” and + “Before Submitting” sections, the `evergreen` skill, and any module “Before + Submitting” sections +- **CI/CD or publishing changes** — update the `evergreen` skill diff --git a/buildSrc/CLAUDE.md b/buildSrc/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/buildSrc/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-benchmarks/AGENTS.md b/driver-benchmarks/AGENTS.md index 1bcaee4de24..0de4eeef3cd 100644 --- a/driver-benchmarks/AGENTS.md +++ b/driver-benchmarks/AGENTS.md @@ -1,12 +1,14 @@ # AGENTS.md - driver-benchmarks -Performance benchmarks for the MongoDB Java Driver using JMH and a custom benchmark framework. +Performance benchmarks for the MongoDB Java Driver using JMH and a custom benchmark +framework. **Depends on:** `driver-sync`, `mongodb-crypt` ## Key Packages -- `com.mongodb.benchmark.benchmarks` — Benchmark suite and individual benchmarks (BSON, single/multi-doc, bulk operations) +- `com.mongodb.benchmark.benchmarks` — Benchmark suite and individual benchmarks (BSON, + single/multi-doc, bulk operations) - `com.mongodb.benchmark.benchmarks.bulk` — Bulk write benchmarks - `com.mongodb.benchmark.benchmarks.netty` — Netty transport benchmarks - `com.mongodb.benchmark.framework` — Custom benchmark harness @@ -16,5 +18,7 @@ Performance benchmarks for the MongoDB Java Driver using JMH and a custom benchm - Not published — internal testing only - Non-standard source layout: `src/main` (no `java` subdirectory) -- Run benchmarks: `./gradlew :driver-benchmarks:run` or `./gradlew :driver-benchmarks:jmh` -- Requires `-Dorg.mongodb.benchmarks.data` and `-Dorg.mongodb.benchmarks.output` system properties +- Run benchmarks: `./gradlew :driver-benchmarks:run` or + `./gradlew :driver-benchmarks:jmh` +- Requires `-Dorg.mongodb.benchmarks.data` and `-Dorg.mongodb.benchmarks.output` system + properties diff --git a/driver-benchmarks/CLAUDE.md b/driver-benchmarks/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-benchmarks/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-core/AGENTS.md b/driver-core/AGENTS.md index 20b2a5de548..3ef92eea5e1 100644 --- a/driver-core/AGENTS.md +++ b/driver-core/AGENTS.md @@ -1,14 +1,18 @@ # AGENTS.md - driver-core -Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala). Largest and most complex module. +Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala). +Largest and most complex module. -**Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`, `mongodb-crypt` +**Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`, +`mongodb-crypt` ## Key Packages (Public API) -- `com.mongodb.client.model` — Operation models: `Filters`, `Updates`, `Projections`, `Aggregates`, `Sorts`, `Indexes` +- `com.mongodb.client.model` — Operation models: `Filters`, `Updates`, `Projections`, + `Aggregates`, `Sorts`, `Indexes` - `com.mongodb.client.model.search` — Atlas Search configuration -- `com.mongodb.client.result` — Operation result types (`InsertOneResult`, `DeleteResult`, etc.) +- `com.mongodb.client.result` — Operation result types (`InsertOneResult`, + `DeleteResult`, etc.) - `com.mongodb.connection` — `ClusterSettings`, `ClusterDescription` - `com.mongodb.event` — Listeners for commands, connections, servers, cluster events - `com.mongodb.session` — `ClientSession` interface @@ -21,17 +25,21 @@ Core driver internals shared by all driver variants (sync, reactive, Kotlin, Sca - `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC - `com.mongodb.internal.async` — Async operation framework - `com.mongodb.internal.binding` — Server binding strategies -- `com.mongodb.internal.client` — MongoClient/MongoDatabase/MongoCollection implementations +- `com.mongodb.internal.client` — MongoClient/MongoDatabase/MongoCollection + implementations ## Notes -- Every package must have a `package-info.java` -- Most extensive test suite — JUnit 5 + Spock (Groovy) + Mockito. Match surrounding patterns carefully. -- `com.mongodb.internal.build.MongoDriverVersion` is auto-generated by the `com.github.gmazzo.buildconfig` Gradle plugin — run `./gradlew :driver-core:generateMongoDriverVersion` if missing +- Most extensive test suite — JUnit 5 + Spock (Groovy) + Mockito. + Match surrounding patterns carefully. +- `com.mongodb.internal.build.MongoDriverVersion` is auto-generated by the + `com.github.gmazzo.buildconfig` Gradle plugin — run + `./gradlew :driver-core:generateMongoDriverVersion` if missing - Never block in async code paths ## Key Patterns - Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()` -- Fluent builders: `MongoClientSettings.builder()` is the primary entry point for configuring clients +- Fluent builders: `MongoClientSettings.builder()` is the primary entry point for + configuring clients - Abstract core with pluggable transports diff --git a/driver-core/CLAUDE.md b/driver-core/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-core/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-kotlin-coroutine/AGENTS.md b/driver-kotlin-coroutine/AGENTS.md index e8060ae053f..fd8c06544e5 100644 --- a/driver-kotlin-coroutine/AGENTS.md +++ b/driver-kotlin-coroutine/AGENTS.md @@ -6,10 +6,10 @@ Kotlin Coroutines driver providing `suspend` function-based async API. ## Key Packages -- `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`, `MongoDatabase`, `MongoCollection`) +- `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`, + `MongoDatabase`, `MongoCollection`) ## Notes -- Formatting: ktfmt dropbox style, max width 120 - Suspend functions wrapping `driver-reactive-streams` — never block - Built on `kotlinx-coroutines` diff --git a/driver-kotlin-coroutine/CLAUDE.md b/driver-kotlin-coroutine/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-kotlin-coroutine/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-kotlin-extensions/AGENTS.md b/driver-kotlin-extensions/AGENTS.md index 972b22798ac..3f5940ef47b 100644 --- a/driver-kotlin-extensions/AGENTS.md +++ b/driver-kotlin-extensions/AGENTS.md @@ -2,14 +2,15 @@ Kotlin extensions providing type-safe DSLs for query and update construction. -**Depends on:** `driver-core`, optionally `driver-kotlin-sync`, `driver-kotlin-coroutine` +**Depends on:** `driver-core`, optionally `driver-kotlin-sync`, +`driver-kotlin-coroutine` ## Key Packages -- `com.mongodb.kotlin.client.model` — Type-safe DSL builders (`Filters`, `Updates`, `Aggregates`, `Sorts`, `Projections`, `Indexes`) +- `com.mongodb.kotlin.client.model` — Type-safe DSL builders (`Filters`, `Updates`, + `Aggregates`, `Sorts`, `Projections`, `Indexes`) - `com.mongodb.kotlin.client.property` — `KPropertyPath` for property-based queries ## Notes -- Formatting: ktfmt dropbox style, max width 120 - Works with both `driver-kotlin-sync` and `driver-kotlin-coroutine` diff --git a/driver-kotlin-extensions/CLAUDE.md b/driver-kotlin-extensions/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-kotlin-extensions/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-kotlin-sync/AGENTS.md b/driver-kotlin-sync/AGENTS.md index 6ebbcdcb454..fabaec95677 100644 --- a/driver-kotlin-sync/AGENTS.md +++ b/driver-kotlin-sync/AGENTS.md @@ -6,8 +6,5 @@ Kotlin synchronous (blocking) driver — idiomatic Kotlin wrapper over `driver-s ## Key Packages -- `com.mongodb.kotlin.client` — Blocking sync API (`MongoClient`, `MongoDatabase`, `MongoCollection`) - -## Notes - -- Formatting: ktfmt dropbox style, max width 120 +- `com.mongodb.kotlin.client` — Blocking sync API (`MongoClient`, `MongoDatabase`, + `MongoCollection`) diff --git a/driver-kotlin-sync/CLAUDE.md b/driver-kotlin-sync/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-kotlin-sync/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-lambda/AGENTS.md b/driver-lambda/AGENTS.md index 29a83c6ed4d..15a92935465 100644 --- a/driver-lambda/AGENTS.md +++ b/driver-lambda/AGENTS.md @@ -1,6 +1,7 @@ # AGENTS.md - driver-lambda -AWS Lambda test application for validating the MongoDB Java Driver in Lambda environments. +AWS Lambda test application for validating the MongoDB Java Driver in Lambda +environments. **Depends on:** `bson`, `driver-sync` diff --git a/driver-lambda/CLAUDE.md b/driver-lambda/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-lambda/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-legacy/AGENTS.md b/driver-legacy/AGENTS.md index 3da7dd342cd..7ff4cef4c5a 100644 --- a/driver-legacy/AGENTS.md +++ b/driver-legacy/AGENTS.md @@ -6,10 +6,12 @@ Legacy MongoDB Java driver API — backwards compatibility facade for the 3.x AP ## Key Packages -- `com.mongodb` — Legacy API (`MongoClient`, `DB`, `DBCollection`, `DBCursor`) — distinct from `driver-core` classes in the same namespace +- `com.mongodb` — Legacy API (`MongoClient`, `DB`, `DBCollection`, `DBCursor`) — + distinct from `driver-core` classes in the same namespace - `com.mongodb.gridfs` — Legacy GridFS ## Notes -- Every package must have a `package-info.java` -- Do not add new features here — new functionality goes in `driver-sync` or `driver-core` +- Do not add new features here — new functionality goes in `driver-sync` or + `driver-core` +- Do not add new Spock tests diff --git a/driver-legacy/CLAUDE.md b/driver-legacy/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-legacy/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-reactive-streams/AGENTS.md b/driver-reactive-streams/AGENTS.md index 1821ed57ae4..366433d38c5 100644 --- a/driver-reactive-streams/AGENTS.md +++ b/driver-reactive-streams/AGENTS.md @@ -1,16 +1,17 @@ # AGENTS.md - driver-reactive-streams -Reactive Streams driver implementing the [Reactive Streams specification](https://www.reactive-streams.org/). +Reactive Streams driver implementing the +[Reactive Streams specification](https://www.reactive-streams.org/). **Depends on:** `bson`, `driver-core` ## Key Packages -- `com.mongodb.reactivestreams.client` — Publisher-based API (`MongoClient`, `MongoDatabase`, `MongoCollection`) +- `com.mongodb.reactivestreams.client` — Publisher-based API (`MongoClient`, + `MongoDatabase`, `MongoCollection`) ## Notes -- Every package must have a `package-info.java` - JUnit 5 + Spock (Groovy) + Project Reactor (test utilities) ## Key Patterns diff --git a/driver-reactive-streams/CLAUDE.md b/driver-reactive-streams/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-reactive-streams/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-scala/AGENTS.md b/driver-scala/AGENTS.md index d33f4c87559..69c5d3a4ab3 100644 --- a/driver-scala/AGENTS.md +++ b/driver-scala/AGENTS.md @@ -4,13 +4,16 @@ Scala async driver providing Observable-based API wrapping `driver-reactive-stre **Depends on:** `bson-scala`, `driver-reactive-streams` -**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root `gradle.properties`). Default: 2.13. +**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root +`gradle.properties`). Default: 2.13. -See [README.md](./README.md) for full details on directory layout, formatting, and testing commands. +See [README.md](./README.md) for full details on directory layout, formatting, and +testing commands. ## Key Packages -- `org.mongodb.scala` — Scala async driver (`MongoClient`, `MongoDatabase`, `MongoCollection`, Observable-based) +- `org.mongodb.scala` — Scala async driver (`MongoClient`, `MongoDatabase`, + `MongoCollection`, Observable-based) - `org.mongodb.scala.model` — Scala wrappers around filter/update builders ## Before Submitting diff --git a/driver-scala/CLAUDE.md b/driver-scala/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-scala/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/driver-sync/AGENTS.md b/driver-sync/AGENTS.md index e59109baed7..00a8cf0e65d 100644 --- a/driver-sync/AGENTS.md +++ b/driver-sync/AGENTS.md @@ -1,20 +1,23 @@ # AGENTS.md - driver-sync -Synchronous (blocking) Java driver — the most commonly used entry point for Java applications. +Synchronous (blocking) Java driver — the most commonly used entry point for Java +applications. **Depends on:** `bson`, `driver-core` ## Key Packages -- `com.mongodb.client` — Public sync API (`MongoClient`, `MongoDatabase`, `MongoCollection`) +- `com.mongodb.client` — Public sync API (`MongoClient`, `MongoDatabase`, + `MongoCollection`) - `com.mongodb.client.gridfs` — GridFS sync implementation - `com.mongodb.client.vault` — Client-side field-level encryption client - `com.mongodb.client.internal` — Implementation helpers (private API) ## Notes -- Every package must have a `package-info.java` -- JUnit 5 + Spock (Groovy). Spock is heavily used but do not add new Spock tests. +- JUnit 5 + Spock (Groovy). + Spock is heavily used but do not add new Spock tests. - Blocking wrapper over `driver-core` async infrastructure -- Primary entry point: `MongoClients.create()` or `MongoClients.create(MongoClientSettings)` +- Primary entry point: `MongoClients.create()` or + `MongoClients.create(MongoClientSettings)` - Optional Micrometer integration for observability diff --git a/driver-sync/CLAUDE.md b/driver-sync/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/driver-sync/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/graalvm-native-image-app/AGENTS.md b/graalvm-native-image-app/AGENTS.md index 40de264de12..24a9d3cbf3f 100644 --- a/graalvm-native-image-app/AGENTS.md +++ b/graalvm-native-image-app/AGENTS.md @@ -1,12 +1,15 @@ # AGENTS.md - graalvm-native-image-app -GraalVM Native Image test application verifying driver compatibility with native compilation. +GraalVM Native Image test application verifying driver compatibility with native +compilation. -**Depends on:** `bson`, `driver-core`, `driver-sync`, `driver-legacy`, `driver-reactive-streams`, `mongodb-crypt` +**Depends on:** `bson`, `driver-core`, `driver-sync`, `driver-legacy`, +`driver-reactive-streams`, `mongodb-crypt` ## Key Packages -- `com.mongodb.internal.graalvm` — Native image test app, GraalVM substitutions, and custom DNS support +- `com.mongodb.internal.graalvm` — Native image test app, GraalVM substitutions, and + custom DNS support ## Notes diff --git a/graalvm-native-image-app/CLAUDE.md b/graalvm-native-image-app/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/graalvm-native-image-app/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/gradle/AGENTS.md b/gradle/AGENTS.md index 1ef61492375..f0ff385650e 100644 --- a/gradle/AGENTS.md +++ b/gradle/AGENTS.md @@ -4,16 +4,19 @@ Gradle configuration and infrastructure for the build system. ## Key Files -- `libs.versions.toml` — Central version catalog defining all dependency versions, library coordinates, bundles, and plugin versions -- `wrapper/` — Gradle wrapper JAR and properties (do not modify manually — use `./gradlew wrapper --gradle-version=`) +- `libs.versions.toml` — Central version catalog defining all dependency versions, + library coordinates, bundles, and plugin versions +- `wrapper/` — Gradle wrapper JAR and properties (do not modify manually — use + `./gradlew wrapper --gradle-version=`) - `scala/lib/` — Bundled Scala Ant JAR for Scala compilation support ## Notes -- All dependency versions are managed in `libs.versions.toml` — never declare versions inline in `build.gradle.kts` files -- **Never add dependencies without justification.** Dependencies are liabilities. -- **Use dependencies for:** Security/crypto, complex protocols, battle-tested algorithms. -- **Write it yourself for:** fewer than 100 LOC of straightforward code, project-specific logic, performance-critical paths. -- The version catalog defines `[versions]`, `[libraries]`, `[bundles]`, and `[plugins]` sections +- All dependency versions are managed in `libs.versions.toml` — never declare versions + inline in `build.gradle.kts` files +- Never add dependencies without justification +- The version catalog defines `[versions]`, `[libraries]`, `[bundles]`, and `[plugins]` + sections - Scala test libraries are declared per Scala version (v3, v2-v13, v2-v12, v2-v11) -- When adding or updating dependencies, modify `libs.versions.toml` and reference via `libs.` in build scripts +- When adding or updating dependencies, modify `libs.versions.toml` and reference via + `libs.` in build scripts diff --git a/gradle/CLAUDE.md b/gradle/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/gradle/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/mongodb-crypt/AGENTS.md b/mongodb-crypt/AGENTS.md index 17d5447654b..8bd66334bb2 100644 --- a/mongodb-crypt/AGENTS.md +++ b/mongodb-crypt/AGENTS.md @@ -11,7 +11,6 @@ Client-side field-level encryption (CSFLE) support via JNA bindings to libmongoc ## Notes -- Every package must have a `package-info.java` - Tests are primarily integration tests requiring libmongocrypt native libraries - Build downloads JNA libs for multiple platforms, embedded in the JAR - **Security-critical module — changes require careful review** diff --git a/mongodb-crypt/CLAUDE.md b/mongodb-crypt/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/mongodb-crypt/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/testing/AGENTS.md b/testing/AGENTS.md index 6d1b0d60502..6c1518edd80 100644 --- a/testing/AGENTS.md +++ b/testing/AGENTS.md @@ -4,6 +4,8 @@ Shared test resources and MongoDB specification test data. ## Notes -- `resources/specifications/` — Git submodule containing MongoDB specification test data (CRUD, SDAM, auth, CSFLE, retryable ops, etc.) +- `resources/specifications/` — Git submodule containing MongoDB specification test data + (CRUD, SDAM, auth, CSFLE, retryable ops, etc.) - `resources/logback-test.xml` — Shared logback configuration for tests -- **Do not modify spec test data** — managed upstream. Update via `git submodule update`. +- **Do not modify spec test data** — managed upstream. + Update via `git submodule update`. diff --git a/testing/CLAUDE.md b/testing/CLAUDE.md new file mode 100644 index 00000000000..43c994c2d36 --- /dev/null +++ b/testing/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From e91b646983a2a19d24f2322d7084bf409c350533 Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Tue, 24 Mar 2026 17:07:24 +0000 Subject: [PATCH 04/10] Further agents improvements - feedback from glean --- .gitignore | 3 ++ AGENTS.md | 48 ++++++++++++++++++-------- README.md | 12 +++++++ bson-kotlin/AGENTS.md | 11 ++++++ bson-kotlinx/AGENTS.md | 11 ++++++ bson-record-codec/AGENTS.md | 11 ++++++ bson-scala/AGENTS.md | 20 +++++------ bson/AGENTS.md | 37 +++++++++----------- driver-core/AGENTS.md | 55 +++++++++++++----------------- driver-kotlin-coroutine/AGENTS.md | 13 +++++-- driver-kotlin-extensions/AGENTS.md | 16 ++++++--- driver-kotlin-sync/AGENTS.md | 12 +++++++ driver-legacy/AGENTS.md | 15 +++++--- driver-reactive-streams/AGENTS.md | 15 +++++--- driver-scala/AGENTS.md | 21 +++++++----- driver-sync/AGENTS.md | 26 ++++++++------ mongodb-crypt/AGENTS.md | 23 ++++++++++--- 17 files changed, 233 insertions(+), 116 deletions(-) diff --git a/.gitignore b/.gitignore index 6398e8490e8..2241cf34717 100644 --- a/.gitignore +++ b/.gitignore @@ -55,6 +55,9 @@ local.properties # security-sensitive files *.gpg +# per-developer agent overrides +.AGENTS.md + # bin build directories **/bin diff --git a/AGENTS.md b/AGENTS.md index 6cb2e23ebc8..e8514518e1a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,14 @@ # AGENTS.md - MongoDB Java Driver Official MongoDB JVM driver monorepo (Java, Kotlin, Scala). -Implements the -[MongoDB Driver Specifications](https://github.com/mongodb/specifications). -Each module has its own `AGENTS.md` with module-specific guidance. +All changes require human review. +Breaking changes to public API require a major version bump — always warn if binary +compatibility is affected. +Also consult `.AGENTS.md` / `~/.AGENTS.md` if present for local agent settings. + +See [`.agents/skills/project-guide`](.agents/skills/project-guide/SKILL.md) for module +structure and dependency graph. +Each module has its own `AGENTS.md`. ## Core Rules @@ -15,14 +20,11 @@ Each module has its own `AGENTS.md` with module-specific guidance. Only remove if provably incorrect. - No rewrites without explicit permission. - When stuck or uncertain: stop, explain, propose alternatives, ask. -- All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in - public APIs. ## Build -- Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. -- Versions: `gradle/libs.versions.toml`. Plugins: - `buildSrc/src/main/kotlin/conventions/`. +Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in +`gradle/libs.versions.toml`. ```bash ./gradlew check # Full validation (format + static checks + tests) @@ -30,10 +32,12 @@ Each module has its own `AGENTS.md` with module-specific guidance. ./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017" ``` -## Formatting +## Style -`check` runs `spotlessApply` automatically. +`check` runs `spotlessApply` automatically — formatting is enforced. Do not reformat outside your changes. +See [`.agents/skills/style-reference`](.agents/skills/style-reference/SKILL.md) for full +rules. - No `System.out.println` / `System.err.println` — use SLF4J - No `e.printStackTrace()` — use proper error handling @@ -48,16 +52,30 @@ Do not reformat outside your changes. - Unit tests must not require a running MongoDB instance. - Descriptive method names or `@DisplayName`. Clean up in `@AfterEach`. -## Safety — Do Not Modify Without Review +## API + +All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in +public APIs. See [`.agents/skills/api-design`](.agents/skills/api-design/SKILL.md) for +stability annotations and design principles. + +## Do Not Modify Without Human Approval -- Wire protocol / authentication handshakes -- Security-critical encryption code +- Wire protocol / authentication handshakes (`com.mongodb.internal.connection`) +- Connection pool core code (`com.mongodb.internal.connection.pool`) +- Security-critical encryption code / JNA bindings (`mongodb-crypt`) - Public API contracts (breaking changes need major version bump) - BSON specification compliance -- Credentials, secrets, `.evergreen/` config, release scripts +- Spec test data submodule (`testing/resources/specifications/`) +- Release/versioning scripts, `.evergreen/` config, credentials/secrets + +See [`.agents/skills/evergreen`](.agents/skills/evergreen/SKILL.md) for CI validation +and patch builds. ## Before Submitting ```bash -./gradlew doc check scalaCheck +./gradlew doc check scalaCheck # Docs + formatting (spotlessApply) + static checks + all tests ``` + +Note: `check` includes `spotlessApply` for all modules. +`buildSrc` uses `spotlessCheck` instead (no auto-fix). diff --git a/README.md b/README.md index 7cf774eb9fb..659ae409e52 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,18 @@ $ mongod --dbpath ./data/db --logpath ./data/mongod.log --port 27017 --logappend If you encounter `"Too many open files"` errors when running the tests then you will need to increase the number of available file descriptors prior to starting mongod as described in [https://www.mongodb.com/docs/manual/reference/ulimit/](https://www.mongodb.com/docs/manual/reference/ulimit/) +## AI Agent Configuration + +This repository uses [agentskills.io](https://agentskills.io) conventions for AI coding agent +instructions. `AGENTS.md` is the canonical source of truth — tool-specific files like `CLAUDE.md` +are generated references. + +### Adding a nested AGENTS.md + +1. Create an `AGENTS.md` in the target directory. +2. Run `scripts/symlink-claude-md.sh` to generate the companion `CLAUDE.md`. +3. Stage and commit both files. + ## IntelliJ IDEA A couple of manual configuration steps are required to run the code in IntelliJ: diff --git a/bson-kotlin/AGENTS.md b/bson-kotlin/AGENTS.md index a78b47573c2..1842209daf2 100644 --- a/bson-kotlin/AGENTS.md +++ b/bson-kotlin/AGENTS.md @@ -4,6 +4,17 @@ Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support **Depends on:** `bson` +- Work here if: modifying Kotlin-specific BSON codecs or inline reified functions + ## Key Packages - `org.bson.codecs.kotlin` — Kotlin-specific codecs with inline reified functions + +## Build & Test + +```bash +./gradlew :bson-kotlin:test +./gradlew :bson-kotlin:check +``` + +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/bson-kotlinx/AGENTS.md b/bson-kotlinx/AGENTS.md index 352650c6ee1..39035e80c7c 100644 --- a/bson-kotlinx/AGENTS.md +++ b/bson-kotlinx/AGENTS.md @@ -4,7 +4,18 @@ Kotlinx serialization integration for BSON, providing a pluggable serialization **Depends on:** `bson` +- Work here if: modifying the kotlinx-serialization BSON codec integration + ## Key Packages - `org.bson.codecs.kotlinx` — Kotlinx serialization BSON format support - `org.bson.codecs.kotlinx.utils` — Helper utilities + +## Build & Test + +```bash +./gradlew :bson-kotlinx:test +./gradlew :bson-kotlinx:check +``` + +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/bson-record-codec/AGENTS.md b/bson-record-codec/AGENTS.md index 28fb1ae5a1e..3cc0ef41262 100644 --- a/bson-record-codec/AGENTS.md +++ b/bson-record-codec/AGENTS.md @@ -5,6 +5,17 @@ Java record codec support for BSON serialization. **Depends on:** `bson` +- Work here if: modifying Java record serialization support + ## Key Packages - `org.bson.codecs.record` — `RecordCodecProvider` and record field accessors + +## Build & Test + +```bash +./gradlew :bson-record-codec:test +./gradlew :bson-record-codec:check +``` + +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/bson-scala/AGENTS.md b/bson-scala/AGENTS.md index 82508c31278..2bd52c3236a 100644 --- a/bson-scala/AGENTS.md +++ b/bson-scala/AGENTS.md @@ -5,23 +5,23 @@ macro-based codecs. **Depends on:** `bson` -**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root -`gradle.properties`). Default: 2.13. +**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root +`gradle.properties`). -See [README.md](./README.md) for full details on directory layout, formatting, and -testing commands. +- Work here if: modifying Scala BSON wrappers, macro codecs, or Scala collection support ## Key Packages - `org.mongodb.scala.bson` — Core Scala BSON wrappers - `org.mongodb.scala.bson.codecs` — Macro-based codecs (Scala 2/3) -- `org.mongodb.scala.bson.collection` — Immutable/mutable collection support -- `org.mongodb.scala.bson.annotations` — Field annotations -## Before Submitting +## Build & Test ```bash -./gradlew spotlessApply # Fix formatting -./gradlew :bson-scala:scalaCheck # Static checks + tests (default Scala version) -./gradlew :bson-scala:scalaCheck -PscalaVersion= # Test specific Scala version +./gradlew :bson-scala:test +./gradlew :bson-scala:scalaCheck # Static checks + tests (default Scala version) +./gradlew :bson-scala:scalaCheck -PscalaVersion= # Test specific Scala version ``` + +For global rules see [root AGENTS.md](../AGENTS.md). +See [README.md](./README.md) for directory layout details. diff --git a/bson/AGENTS.md b/bson/AGENTS.md index d0427c5510f..1da3b8ec9d3 100644 --- a/bson/AGENTS.md +++ b/bson/AGENTS.md @@ -1,30 +1,27 @@ # AGENTS.md - bson -Core BSON (Binary JSON) library. -This is the foundation module — all other modules depend on it. +Core BSON (Binary JSON) library — the foundation module. +All other modules depend on it. **Depends on:** None (foundation module) -## Key Packages +- Work here if: adding/modifying BSON types, codecs, JSON conversion, or binary I/O +- Do not: expose `org.bson.internal` types in public API -- `org.bson` — Core BSON value types (`BsonDocument`, `BsonValue`, `BsonReader`, - `BsonWriter`) -- `org.bson.codecs` — Codec framework (`Encoder`, `Decoder`, `Codec`) -- `org.bson.codecs.configuration` — Codec registry and provider infrastructure - (`CodecRegistry`, `CodecProvider`) -- `org.bson.codecs.pojo` — POJO codec support with conventions and property modeling -- `org.bson.codecs.jsr310` — Java 8+ date/time codec support -- `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`, `JsonMode`) -- `org.bson.io` — Binary I/O (`ByteBuffer`, `OutputBuffer`) -- `org.bson.types` — Legacy types (`ObjectId`, `Decimal128`, etc.) -- `org.bson.internal` — Private API (vector support, encoding utilities) +## Key Packages -## Notes +- `org.bson` — Core types (`BsonDocument`, `BsonValue`, `BsonReader`, `BsonWriter`) +- `org.bson.codecs` — Codec framework (`Encoder`, `Decoder`, `Codec`, `CodecRegistry`) +- `org.bson.codecs.pojo` — POJO codec support +- `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`) +- `org.bson.internal` — Private API — do not expose -- JUnit 5 + Spock (Groovy) tests in both unit and functional dirs +## Build & Test -## Key Patterns +```bash +./gradlew :bson:test +./gradlew :bson:check +``` -- Codec-based serialization with type-safe `BsonValue` hierarchy -- `BsonDocument` implements `Map` -- All public types in `org.bson` — internal types in `org.bson.internal` +For global rules see [root AGENTS.md](../AGENTS.md). +For API design see [api-design skill](../.agents/skills/api-design/SKILL.md). diff --git a/driver-core/AGENTS.md b/driver-core/AGENTS.md index 3ef92eea5e1..a44bb7fa10f 100644 --- a/driver-core/AGENTS.md +++ b/driver-core/AGENTS.md @@ -6,40 +6,31 @@ Largest and most complex module. **Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`, `mongodb-crypt` -## Key Packages (Public API) - -- `com.mongodb.client.model` — Operation models: `Filters`, `Updates`, `Projections`, - `Aggregates`, `Sorts`, `Indexes` -- `com.mongodb.client.model.search` — Atlas Search configuration -- `com.mongodb.client.result` — Operation result types (`InsertOneResult`, - `DeleteResult`, etc.) -- `com.mongodb.connection` — `ClusterSettings`, `ClusterDescription` -- `com.mongodb.event` — Listeners for commands, connections, servers, cluster events -- `com.mongodb.session` — `ClientSession` interface -- `com.mongodb.bulk` — `WriteModel` hierarchy - -## Key Packages (Internal — Private API) - -- `com.mongodb.internal.connection` — Socket, wire protocol, command execution -- `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate, etc.) -- `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC -- `com.mongodb.internal.async` — Async operation framework -- `com.mongodb.internal.binding` — Server binding strategies -- `com.mongodb.internal.client` — MongoClient/MongoDatabase/MongoCollection - implementations +- Work here if: modifying query builders (`Filters`, `Updates`, `Aggregates`), + connection handling, wire protocol, server selection, or operation execution +- Do not: block in async code paths, modify wire protocol or auth without human approval + +## Key Packages + +- `com.mongodb.client.model` — `Filters`, `Updates`, `Projections`, `Aggregates`, + `Sorts`, `Indexes` +- `com.mongodb.internal.connection` — Wire protocol, command execution (safety-critical) +- `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate) +- `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC (safety-critical) + +## Build & Test + +```bash +./gradlew :driver-core:test +./gradlew :driver-core:check +./gradlew :driver-core:generateMongoDriverVersion # If MongoDriverVersion is missing +``` ## Notes -- Most extensive test suite — JUnit 5 + Spock (Groovy) + Mockito. +- Most extensive test suite — JUnit 5 + Spock + Mockito. Match surrounding patterns carefully. -- `com.mongodb.internal.build.MongoDriverVersion` is auto-generated by the - `com.github.gmazzo.buildconfig` Gradle plugin — run - `./gradlew :driver-core:generateMongoDriverVersion` if missing -- Never block in async code paths - -## Key Patterns +- `MongoDriverVersion` is auto-generated by the `com.github.gmazzo.buildconfig` plugin -- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()` -- Fluent builders: `MongoClientSettings.builder()` is the primary entry point for - configuring clients -- Abstract core with pluggable transports +For global rules see [root AGENTS.md](../AGENTS.md). +For API design see [api-design skill](../.agents/skills/api-design/SKILL.md). diff --git a/driver-kotlin-coroutine/AGENTS.md b/driver-kotlin-coroutine/AGENTS.md index fd8c06544e5..6c22260f113 100644 --- a/driver-kotlin-coroutine/AGENTS.md +++ b/driver-kotlin-coroutine/AGENTS.md @@ -4,12 +4,19 @@ Kotlin Coroutines driver providing `suspend` function-based async API. **Depends on:** `bson`, `driver-reactive-streams`, `bson-kotlin` +- Work here if: modifying the Kotlin coroutine-based driver API +- Do not: block in any code path — all suspend functions wrap `driver-reactive-streams` + ## Key Packages - `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`, `MongoDatabase`, `MongoCollection`) -## Notes +## Build & Test + +```bash +./gradlew :driver-kotlin-coroutine:test +./gradlew :driver-kotlin-coroutine:check +``` -- Suspend functions wrapping `driver-reactive-streams` — never block -- Built on `kotlinx-coroutines` +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/driver-kotlin-extensions/AGENTS.md b/driver-kotlin-extensions/AGENTS.md index 3f5940ef47b..0dea5d2b907 100644 --- a/driver-kotlin-extensions/AGENTS.md +++ b/driver-kotlin-extensions/AGENTS.md @@ -5,12 +5,20 @@ Kotlin extensions providing type-safe DSLs for query and update construction. **Depends on:** `driver-core`, optionally `driver-kotlin-sync`, `driver-kotlin-coroutine` +- Work here if: adding or modifying Kotlin type-safe DSL builders for `Filters`, + `Updates`, `Aggregates`, etc. +- Works with both `driver-kotlin-sync` and `driver-kotlin-coroutine` + ## Key Packages -- `com.mongodb.kotlin.client.model` — Type-safe DSL builders (`Filters`, `Updates`, - `Aggregates`, `Sorts`, `Projections`, `Indexes`) +- `com.mongodb.kotlin.client.model` — Type-safe DSL builders - `com.mongodb.kotlin.client.property` — `KPropertyPath` for property-based queries -## Notes +## Build & Test -- Works with both `driver-kotlin-sync` and `driver-kotlin-coroutine` +```bash +./gradlew :driver-kotlin-extensions:test +./gradlew :driver-kotlin-extensions:check +``` + +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/driver-kotlin-sync/AGENTS.md b/driver-kotlin-sync/AGENTS.md index fabaec95677..e8ef0e86081 100644 --- a/driver-kotlin-sync/AGENTS.md +++ b/driver-kotlin-sync/AGENTS.md @@ -4,7 +4,19 @@ Kotlin synchronous (blocking) driver — idiomatic Kotlin wrapper over `driver-s **Depends on:** `bson`, `driver-sync`, `bson-kotlin` +- Work here if: modifying the Kotlin blocking API surface +- Do not: add internal connection/protocol code (that belongs in `driver-core`) + ## Key Packages - `com.mongodb.kotlin.client` — Blocking sync API (`MongoClient`, `MongoDatabase`, `MongoCollection`) + +## Build & Test + +```bash +./gradlew :driver-kotlin-sync:test +./gradlew :driver-kotlin-sync:check +``` + +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/driver-legacy/AGENTS.md b/driver-legacy/AGENTS.md index 7ff4cef4c5a..91fe5000e18 100644 --- a/driver-legacy/AGENTS.md +++ b/driver-legacy/AGENTS.md @@ -4,14 +4,21 @@ Legacy MongoDB Java driver API — backwards compatibility facade for the 3.x AP **Depends on:** `bson`, `driver-core`, `driver-sync` +- Work here if: fixing bugs in the legacy 3.x API compatibility layer +- Do not: add new features (new functionality goes in `driver-sync` or `driver-core`) +- Do not: add new Spock tests + ## Key Packages - `com.mongodb` — Legacy API (`MongoClient`, `DB`, `DBCollection`, `DBCursor`) — distinct from `driver-core` classes in the same namespace - `com.mongodb.gridfs` — Legacy GridFS -## Notes +## Build & Test + +```bash +./gradlew :driver-legacy:test +./gradlew :driver-legacy:check +``` -- Do not add new features here — new functionality goes in `driver-sync` or - `driver-core` -- Do not add new Spock tests +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/driver-reactive-streams/AGENTS.md b/driver-reactive-streams/AGENTS.md index 366433d38c5..f6f8e86216c 100644 --- a/driver-reactive-streams/AGENTS.md +++ b/driver-reactive-streams/AGENTS.md @@ -5,17 +5,24 @@ Reactive Streams driver implementing the **Depends on:** `bson`, `driver-core` +- Work here if: modifying the Publisher-based async API +- Do not: block in any code path, break backpressure contracts + ## Key Packages - `com.mongodb.reactivestreams.client` — Publisher-based API (`MongoClient`, `MongoDatabase`, `MongoCollection`) -## Notes +## Build & Test -- JUnit 5 + Spock (Groovy) + Project Reactor (test utilities) +```bash +./gradlew :driver-reactive-streams:test +./gradlew :driver-reactive-streams:check +``` -## Key Patterns +## Notes - All operations return `Publisher` — never block -- Respect backpressure in all implementations - `driver-kotlin-coroutine` and `driver-scala` both build on top of this module + +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/driver-scala/AGENTS.md b/driver-scala/AGENTS.md index 69c5d3a4ab3..106c43230f8 100644 --- a/driver-scala/AGENTS.md +++ b/driver-scala/AGENTS.md @@ -4,22 +4,25 @@ Scala async driver providing Observable-based API wrapping `driver-reactive-stre **Depends on:** `bson-scala`, `driver-reactive-streams` -**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root -`gradle.properties`). Default: 2.13. +**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root +`gradle.properties`). -See [README.md](./README.md) for full details on directory layout, formatting, and -testing commands. +- Work here if: modifying the Scala Observable-based driver API or Scala model wrappers +- Do not: block in any code path ## Key Packages - `org.mongodb.scala` — Scala async driver (`MongoClient`, `MongoDatabase`, - `MongoCollection`, Observable-based) + `MongoCollection`) - `org.mongodb.scala.model` — Scala wrappers around filter/update builders -## Before Submitting +## Build & Test ```bash -./gradlew spotlessApply # Fix formatting -./gradlew :driver-scala:scalaCheck # Static checks + tests (default Scala version) -./gradlew :driver-scala:scalaCheck -PscalaVersion= # Test specific Scala version +./gradlew :driver-scala:test +./gradlew :driver-scala:scalaCheck # Static checks + tests (default Scala version) +./gradlew :driver-scala:scalaCheck -PscalaVersion= # Test specific Scala version ``` + +For global rules see [root AGENTS.md](../AGENTS.md). +See [README.md](./README.md) for directory layout details. diff --git a/driver-sync/AGENTS.md b/driver-sync/AGENTS.md index 00a8cf0e65d..6bd02c1b61c 100644 --- a/driver-sync/AGENTS.md +++ b/driver-sync/AGENTS.md @@ -5,19 +5,25 @@ applications. **Depends on:** `bson`, `driver-core` +- Work here if: modifying the blocking Java API surface (`MongoClient`, `MongoDatabase`, + `MongoCollection`), GridFS, or CSFLE vault client +- Do not: add new Spock tests (legacy only), add internal connection/protocol code (that + belongs in `driver-core`) + ## Key Packages -- `com.mongodb.client` — Public sync API (`MongoClient`, `MongoDatabase`, - `MongoCollection`) +- `com.mongodb.client` — Public sync API - `com.mongodb.client.gridfs` — GridFS sync implementation - `com.mongodb.client.vault` — Client-side field-level encryption client -- `com.mongodb.client.internal` — Implementation helpers (private API) -## Notes +## Build & Test + +```bash +./gradlew :driver-sync:test +./gradlew :driver-sync:check +``` + +Primary entry point: `MongoClients.create()` or +`MongoClients.create(MongoClientSettings)`. -- JUnit 5 + Spock (Groovy). - Spock is heavily used but do not add new Spock tests. -- Blocking wrapper over `driver-core` async infrastructure -- Primary entry point: `MongoClients.create()` or - `MongoClients.create(MongoClientSettings)` -- Optional Micrometer integration for observability +For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/mongodb-crypt/AGENTS.md b/mongodb-crypt/AGENTS.md index 8bd66334bb2..d324bafe214 100644 --- a/mongodb-crypt/AGENTS.md +++ b/mongodb-crypt/AGENTS.md @@ -4,13 +4,26 @@ Client-side field-level encryption (CSFLE) support via JNA bindings to libmongoc **Depends on:** `bson` +- Work here if: modifying CSFLE encryption/decryption logic or JNA bindings +- Do not: move, re-expose, or refactor JNA/libmongocrypt bindings without human approval + — this is security-critical code +- Do not: modify the C API binding layer without understanding the libmongocrypt + contract + ## Key Packages -- `com.mongodb.crypt.capi` — mongocryptd C API bindings (JNA) +- `com.mongodb.crypt.capi` — mongocryptd C API bindings (JNA) — **security-critical, do + not modify without human review** - `com.mongodb.internal.crypt.capi` — Internal encryption state management -## Notes +## Build & Test + +```bash +./gradlew :mongodb-crypt:test +./gradlew :mongodb-crypt:check +``` + +Tests are primarily integration tests requiring libmongocrypt native libraries. +Build downloads JNA libs for multiple platforms, embedded in the JAR. -- Tests are primarily integration tests requiring libmongocrypt native libraries -- Build downloads JNA libs for multiple platforms, embedded in the JAR -- **Security-critical module — changes require careful review** +For global rules see [root AGENTS.md](../AGENTS.md). From 2ecdd140640fb5193c8f62d92c8b43530e5486b8 Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Tue, 24 Mar 2026 17:20:08 +0000 Subject: [PATCH 05/10] More polishing of agents and skills --- .agents/skills/api-design/SKILL.md | 13 ++- .agents/skills/evergreen/SKILL.md | 7 +- .agents/skills/project-guide/SKILL.md | 1 - .agents/skills/spec-tests/SKILL.md | 8 +- .agents/skills/style-reference/SKILL.md | 1 - .agents/skills/testing-guide/SKILL.md | 3 +- AGENTS.md | 32 ++---- README.md | 136 ++++++++++++++---------- bom/AGENTS.md | 9 +- bson-scala/AGENTS.md | 6 +- buildSrc/AGENTS.md | 30 +++--- driver-benchmarks/AGENTS.md | 13 +-- driver-core/AGENTS.md | 10 +- driver-kotlin-coroutine/AGENTS.md | 3 +- driver-kotlin-extensions/AGENTS.md | 6 +- driver-kotlin-sync/AGENTS.md | 3 +- driver-lambda/AGENTS.md | 3 +- driver-legacy/AGENTS.md | 4 +- driver-reactive-streams/AGENTS.md | 6 +- driver-scala/AGENTS.md | 6 +- driver-sync/AGENTS.md | 13 +-- graalvm-native-image-app/AGENTS.md | 9 +- gradle/AGENTS.md | 14 ++- mongodb-crypt/AGENTS.md | 11 +- testing/AGENTS.md | 4 +- 25 files changed, 168 insertions(+), 183 deletions(-) diff --git a/.agents/skills/api-design/SKILL.md b/.agents/skills/api-design/SKILL.md index ada28dfebc7..f6642cf83bd 100644 --- a/.agents/skills/api-design/SKILL.md +++ b/.agents/skills/api-design/SKILL.md @@ -2,15 +2,18 @@ name: api-design description: API stability annotations, design principles, and patterns for the MongoDB Java Driver. Use when adding or modifying public API surface — new classes, methods, interfaces, or changing method signatures. --- - # API Design ## API Stability Annotations -- `@Alpha` — Early development, may be removed. Not for production use. -- `@Beta` — Subject to change or removal. Libraries should not depend on these. -- `@Evolving` — May add abstract methods in future releases. Safe to use, but implementing/extending bears upgrade risk. -- `@Sealed` — Must not be extended or implemented by consumers. Safe to use, but not to subclass. +- `@Alpha` — Early development, may be removed. + Not for production use. +- `@Beta` — Subject to change or removal. + Libraries should not depend on these. +- `@Evolving` — May add abstract methods in future releases. + Safe to use, but implementing/extending bears upgrade risk. +- `@Sealed` — Must not be extended or implemented by consumers. + Safe to use, but not to subclass. - `@Deprecated` — Supported until next major release but should be migrated away from. ## Design Principles diff --git a/.agents/skills/evergreen/SKILL.md b/.agents/skills/evergreen/SKILL.md index eeb438567cd..603beeb9c60 100644 --- a/.agents/skills/evergreen/SKILL.md +++ b/.agents/skills/evergreen/SKILL.md @@ -2,12 +2,12 @@ name: evergreen description: Evergreen CI infrastructure, configuration validation. Use when modifying .evergreen/ config, preparing to submit changes or understanding the Evergreen test matrix. --- - # Evergreen ## Evergreen (MongoDB Internal CI) -Primary CI runs on MongoDB's Evergreen system. Configuration lives in `.evergreen/`. +Primary CI runs on MongoDB’s Evergreen system. +Configuration lives in `.evergreen/`. - Do not modify `.evergreen/` configuration without review - Evergreen runs the full test matrix across MongoDB versions, OS platforms, and JDK versions @@ -30,4 +30,5 @@ To test your changes on Evergreen before merging, create a patch build: evergreen patch -u ``` -This uploads your uncommitted and committed local changes as a patch build on Evergreen, allowing you to run the full CI test matrix against your branch. +This uploads your uncommitted and committed local changes as a patch build on Evergreen, allowing you to run the full CI +test matrix against your branch. diff --git a/.agents/skills/project-guide/SKILL.md b/.agents/skills/project-guide/SKILL.md index eeeb3b6b686..a068414426e 100644 --- a/.agents/skills/project-guide/SKILL.md +++ b/.agents/skills/project-guide/SKILL.md @@ -2,7 +2,6 @@ name: project-guide description: Project structure, dependency graph, and guide for finding the right project to work in. Use when starting a task and unsure which project owns the relevant code, or when you need to understand cross-project dependencies. --- - # Project Guide ## Project Structure diff --git a/.agents/skills/spec-tests/SKILL.md b/.agents/skills/spec-tests/SKILL.md index 9ae006d47ef..6c07b7d7f5e 100644 --- a/.agents/skills/spec-tests/SKILL.md +++ b/.agents/skills/spec-tests/SKILL.md @@ -2,14 +2,12 @@ name: spec-tests description: How to work with MongoDB specification tests — structure, rules, and adding new spec test support. Use when implementing or modifying behavior defined by the MongoDB Driver Specifications, or when working with the test data in testing/resources/specifications/. --- - # MongoDB Specification Tests ## Overview -The driver implements the -[MongoDB Driver Specifications](https://github.com/mongodb/specifications). Specification -test data files live in `testing/resources/specifications/` — a git submodule. +The driver implements the [MongoDB Driver Specifications](https://github.com/mongodb/specifications). +Specification test data files live in `testing/resources/specifications/` — a git submodule. ## Rules @@ -40,4 +38,4 @@ testing/ 1. Check `testing/resources/specifications/` for the relevant spec test data 2. Find existing test runners in the module (look for `*SpecificationTest*` or similar) 3. Extend existing patterns — each module handles spec tests slightly differently -4. Ensure tests run with `./gradlew check` or the module's test task +4. Ensure tests run with `./gradlew check` or the module’s test task diff --git a/.agents/skills/style-reference/SKILL.md b/.agents/skills/style-reference/SKILL.md index 10002a0dbf0..962da49c7bd 100644 --- a/.agents/skills/style-reference/SKILL.md +++ b/.agents/skills/style-reference/SKILL.md @@ -2,7 +2,6 @@ name: style-reference description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in the MongoDB Java Driver. Use when you need specific formatting rules beyond the basics in root AGENTS.md — e.g., line length, import ordering, brace style, or language-specific formatter configuration. Spotless auto-enforces most rules. --- - # Style Reference ## Java Style Rules diff --git a/.agents/skills/testing-guide/SKILL.md b/.agents/skills/testing-guide/SKILL.md index 731834018e0..73b7c6c4b2f 100644 --- a/.agents/skills/testing-guide/SKILL.md +++ b/.agents/skills/testing-guide/SKILL.md @@ -2,7 +2,6 @@ name: testing-guide description: Testing frameworks, conventions, and commands for the MongoDB Java Driver. Use when writing or running tests — covers framework selection per module, test naming conventions, integration test setup, and how to run specific test subsets. --- - # Testing Guide ## Frameworks @@ -49,7 +48,7 @@ description: Testing frameworks, conventions, and commands for the MongoDB Java ## Module-Specific Notes - **driver-core:** Largest test suite — JUnit 5 + Spock + Mockito -- **driver-sync:** JUnit 5 + Spock (heavy Spock usage, but don't add new) +- **driver-sync:** JUnit 5 + Spock (heavy Spock usage, but don’t add new) - **driver-reactive-streams:** JUnit 5 + Spock + Project Reactor - **bson-scala / driver-scala:** ScalaTest, test per Scala version - **Kotlin modules:** JUnit 5 + mockito-kotlin diff --git a/AGENTS.md b/AGENTS.md index e8514518e1a..d062489202a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,10 @@ # AGENTS.md - MongoDB Java Driver -Official MongoDB JVM driver monorepo (Java, Kotlin, Scala). All changes require human review. -Breaking changes to public API require a major version bump — always warn if binary -compatibility is affected. +Breaking changes to public API require a major version bump — always warn if binary compatibility is affected. Also consult `.AGENTS.md` / `~/.AGENTS.md` if present for local agent settings. -See [`.agents/skills/project-guide`](.agents/skills/project-guide/SKILL.md) for module -structure and dependency graph. +See [`.agents/skills/project-guide`](.agents/skills/project-guide/SKILL.md) for module structure and dependency graph. Each module has its own `AGENTS.md`. ## Core Rules @@ -23,8 +20,7 @@ Each module has its own `AGENTS.md`. ## Build -Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in -`gradle/libs.versions.toml`. +Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in `gradle/libs.versions.toml`. ```bash ./gradlew check # Full validation (format + static checks + tests) @@ -36,8 +32,7 @@ Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in `check` runs `spotlessApply` automatically — formatting is enforced. Do not reformat outside your changes. -See [`.agents/skills/style-reference`](.agents/skills/style-reference/SKILL.md) for full -rules. +See [`.agents/skills/style-reference`](.agents/skills/style-reference/SKILL.md) for full rules. - No `System.out.println` / `System.err.println` — use SLF4J - No `e.printStackTrace()` — use proper error handling @@ -48,15 +43,14 @@ rules. - Every code change must include tests. Do not reduce coverage. -- JUnit 5 primary. Spock is legacy — do not add new Spock tests. -- Unit tests must not require a running MongoDB instance. -- Descriptive method names or `@DisplayName`. Clean up in `@AfterEach`. +- See [`.agents/skills/testing-guide`](.agents/skills/testing-guide/SKILL.md) for framework details and running specific + tests. +- See [`.agents/skills/spec-tests`](.agents/skills/spec-tests/SKILL.md) for MongoDB specification test conventions. ## API -All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in -public APIs. See [`.agents/skills/api-design`](.agents/skills/api-design/SKILL.md) for -stability annotations and design principles. +All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in public APIs. +See [`.agents/skills/api-design`](.agents/skills/api-design/SKILL.md) for stability annotations and design principles. ## Do Not Modify Without Human Approval @@ -68,14 +62,10 @@ stability annotations and design principles. - Spec test data submodule (`testing/resources/specifications/`) - Release/versioning scripts, `.evergreen/` config, credentials/secrets -See [`.agents/skills/evergreen`](.agents/skills/evergreen/SKILL.md) for CI validation -and patch builds. +See [`.agents/skills/evergreen`](.agents/skills/evergreen/SKILL.md) for CI validation and patch builds. ## Before Submitting ```bash -./gradlew doc check scalaCheck # Docs + formatting (spotlessApply) + static checks + all tests +./gradlew spotlessApply doc check scalaCheck # formatting + Docs + static checks + all tests ``` - -Note: `check` includes `spotlessApply` for all modules. -`buildSrc` uses `spotlessCheck` instead (no auto-fix). diff --git a/README.md b/README.md index 659ae409e52..2af3ad5adcf 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,60 @@ ## Release Notes -Release notes are available [here](https://github.com/mongodb/mongo-java-driver/releases). +Release notes are available +[here](https://github.com/mongodb/mongo-java-driver/releases). ## Documentation -Reference and API documentation for the Java driver is available [here](https://www.mongodb.com/docs/drivers/java/sync/current/). +Reference and API documentation for the Java driver is available +[here](https://www.mongodb.com/docs/drivers/java/sync/current/). -Reference and API documentation for the Kotlin driver is available [here](https://www.mongodb.com/docs/drivers/kotlin/coroutine/current/). +Reference and API documentation for the Kotlin driver is available +[here](https://www.mongodb.com/docs/drivers/kotlin/coroutine/current/). -Reference and API documentation for the Scala driver is available [here](https://www.mongodb.com/docs/languages/scala/scala-driver/current/). +Reference and API documentation for the Scala driver is available +[here](https://www.mongodb.com/docs/languages/scala/scala-driver/current/). ## Tutorials / Training -For tutorials on how to use the MongoDB JVM Drivers, please reference [MongoDB University](https://learn.mongodb.com/). Additional tutorials, videos, and code examples using both the Java Driver and the Kotlin Driver can also be found in the [MongoDB Developer Center](https://www.mongodb.com/developer/). +For tutorials on how to use the MongoDB JVM Drivers, please reference +[MongoDB University](https://learn.mongodb.com/). Additional tutorials, videos, and code +examples using both the Java Driver and the Kotlin Driver can also be found in the +[MongoDB Developer Center](https://www.mongodb.com/developer/). ## Support / Feedback -For issues with, questions about, or feedback for the MongoDB Java, Kotlin, and Scala drivers, please look into -our [support channels](https://www.mongodb.com/docs/manual/support/). Please -do not email any of the driver developers directly with issues or -questions - you're more likely to get an answer on the [MongoDB Community Forums](https://community.mongodb.com/tags/c/drivers-odms-connectors/7/java-driver) or [StackOverflow](https://stackoverflow.com/questions/tagged/mongodb+java). - -At a minimum, please include in your description the exact version of the driver that you are using. If you are having -connectivity issues, it's often also useful to paste in the line of code where you construct the MongoClient instance, -along with the values of all parameters that you pass to the constructor. You should also check your application logs for -any connectivity-related exceptions and post those as well. +For issues with, questions about, or feedback for the MongoDB Java, Kotlin, and Scala +drivers, please look into our +[support channels](https://www.mongodb.com/docs/manual/support/). Please do not email +any of the driver developers directly with issues or questions - you’re more likely to +get an answer on the +[MongoDB Community Forums](https://community.mongodb.com/tags/c/drivers-odms-connectors/7/java-driver) +or [StackOverflow](https://stackoverflow.com/questions/tagged/mongodb+java). + +At a minimum, please include in your description the exact version of the driver that +you are using. If you are having connectivity issues, it’s often also useful to paste in +the line of code where you construct the MongoClient instance, along with the values of +all parameters that you pass to the constructor. +You should also check your application logs for any connectivity-related exceptions and +post those as well. ## Bugs / Feature Requests -Think you’ve found a bug in the Java, Kotlin, or Scala drivers? Want to see a new feature in the drivers? Please open a -case in our issue management tool, JIRA: +Think you’ve found a bug in the Java, Kotlin, or Scala drivers? +Want to see a new feature in the drivers? +Please open a case in our issue management tool, JIRA: - [Create an account and login](https://jira.mongodb.org). - Navigate to [the JAVA project](https://jira.mongodb.org/browse/JAVA). -- Click **Create Issue** - Please provide as much information as possible about the issue type, which driver you are using, and how to reproduce your issue. +- Click **Create Issue** - Please provide as much information as possible about the + issue type, which driver you are using, and how to reproduce your issue. -Bug reports in JIRA for the driver and the Core Server (i.e. SERVER) project are **public**. +Bug reports in JIRA for the driver and the Core Server (i.e. SERVER) project are +**public**. -If you’ve identified a security vulnerability in a driver or any other -MongoDB project, please report it according to the [instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). +If you’ve identified a security vulnerability in a driver or any other MongoDB project, +please report it according to the +[instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). ## Versioning @@ -46,30 +62,35 @@ We follow [semantic versioning](https://semver.org/spec/v2.0.0.html) when releas #### @Alpha -APIs marked with the `@Alpha` annotation are in the early stages of development, subject to incompatible changes, -or even removal, in a future release and may lack some intended features. An APIs bearing `@Alpha` annotation may -contain known issues affecting functionality, performance, and stability. They are also exempt from any compatibility -guarantees made by its containing library. +APIs marked with the `@Alpha` annotation are in the early stages of development, subject +to incompatible changes, or even removal, in a future release and may lack some intended +features. An APIs bearing `@Alpha` annotation may contain known issues affecting +functionality, performance, and stability. +They are also exempt from any compatibility guarantees made by its containing library. -It is inadvisable for applications to use Alpha APIs in production environments or for libraries -(which get included on users' CLASSPATHs, outside the library developers' control) to depend on these APIs. Alpha APIs -are intended for experimental purposes only. +It is inadvisable for applications to use Alpha APIs in production environments +or for libraries (which get included on users’ CLASSPATHs, outside the library +developers’ control) to depend on these APIs. +Alpha APIs are intended for experimental purposes only. #### @Beta -APIs marked with the `@Beta` annotation at the class or method level are subject to change. They can be modified in any way, or even -removed, at any time. If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your own control), you should not -use beta APIs, unless you repackage them (e.g. by using shading, etc). +APIs marked with the `@Beta` annotation at the class or method level are subject to +change. They can be modified in any way, or even removed, at any time. +If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your +own control), you should not use beta APIs, unless you repackage them (e.g. by using +shading, etc). #### @Deprecated -APIs marked with the `@Deprecated` annotation at the class or method level will remain supported until the next major release but it is -recommended to stop using them. +APIs marked with the `@Deprecated` annotation at the class or method level will remain +supported until the next major release but it is recommended to stop using them. #### com.mongodb.internal.* -All code inside the `com.mongodb.internal.*` packages is considered private API and should not be relied upon at all. It can change at any -time. +All code inside the `com.mongodb.internal.*` packages is considered private API and +should not be relied upon at all. +It can change at any time. ## Binaries @@ -85,6 +106,7 @@ Example for Maven: x.y.z ``` + Snapshot builds are also published regularly via Sonatype. Example for Maven: @@ -107,7 +129,8 @@ Example for Maven: ## Build -Java 17+ and git is required to build and compile the source. To build and test the driver: +Java 17+ and git is required to build and compile the source. +To build and test the driver: ``` $ git clone --recurse-submodules https://github.com/mongodb/mongo-java-driver.git @@ -115,21 +138,23 @@ $ cd mongo-java-driver $ ./gradlew check ``` -The test suite requires mongod to be running with [`enableTestCommands`](https://www.mongodb.com/docs/manual/reference/parameters/#param.enableTestCommands), which may be set with the `--setParameter enableTestCommands=1` -command-line parameter: +The test suite requires mongod to be running with +[`enableTestCommands`](https://www.mongodb.com/docs/manual/reference/parameters/#param.enableTestCommands), +which may be set with the `--setParameter enableTestCommands=1` command-line parameter: ``` $ mkdir -p data/db $ mongod --dbpath ./data/db --logpath ./data/mongod.log --port 27017 --logappend --fork --setParameter enableTestCommands=1 ``` -If you encounter `"Too many open files"` errors when running the tests then you will need to increase -the number of available file descriptors prior to starting mongod as described in [https://www.mongodb.com/docs/manual/reference/ulimit/](https://www.mongodb.com/docs/manual/reference/ulimit/) +If you encounter `"Too many open files"` errors when running the tests then you will +need to increase the number of available file descriptors prior to starting mongod as +described in https://www.mongodb.com/docs/manual/reference/ulimit/ ## AI Agent Configuration -This repository uses [agentskills.io](https://agentskills.io) conventions for AI coding agent -instructions. `AGENTS.md` is the canonical source of truth — tool-specific files like `CLAUDE.md` -are generated references. +This repository uses [agentskills.io](https://agentskills.io) conventions for AI coding +agent instructions. `AGENTS.md` is the canonical source of truth — tool-specific files +like `CLAUDE.md` are generated references. ### Adding a nested AGENTS.md @@ -143,15 +168,18 @@ A couple of manual configuration steps are required to run the code in IntelliJ: - Java 17+ is required to build and compile the source. -- **Error:** `java: cannot find symbol: class SNIHostName location: package javax.net.ssl`
- **Fix:** Settings/Preferences > Build, Execution, Deployment > Compiler > Java Compiler - untick "Use '--release' option for - cross-compilation (Java 9 and later)" - -- **Error:** `java: package com.mongodb.internal.build does not exist`
- **Fixes:** Any of the following:
- - Run the `generateBuildConfig` task: eg: `./gradlew generateBuildConfig` or via Gradle > driver-core > Tasks > buildconfig > - generateBuildConfig - - Set `generateBuildConfig` to execute Before Build. via Gradle > Tasks > buildconfig > right click generateBuildConfig - click on - "Execute Before Build" - - Delegate all build actions to Gradle: Settings/Preferences > Build, Execution, Deployment > Build Tools > Gradle > Build and run - using/Run tests using - select "Gradle" +- **Error:** + `java: cannot find symbol: class SNIHostName location: package javax.net.ssl`
+ **Fix:** Settings/Preferences > Build, Execution, Deployment > Compiler > Java + Compiler - untick “Use '--release' option for cross-compilation (Java 9 and later)” + +- **Error:** `java: package com.mongodb.internal.build does not exist`
**Fixes:** + Any of the following:
+ - Run the `generateBuildConfig` task: eg: `./gradlew generateBuildConfig` or via + Gradle > driver-core > Tasks > buildconfig > generateBuildConfig + - Set `generateBuildConfig` to execute Before Build. + via Gradle > Tasks > buildconfig > right click generateBuildConfig - click on + “Execute Before Build” + - Delegate all build actions to Gradle: Settings/Preferences > Build, Execution, + Deployment > Build Tools > Gradle > Build and run using/Run tests using - select + “Gradle” diff --git a/bom/AGENTS.md b/bom/AGENTS.md index 7f5f8b928e6..50262893e75 100644 --- a/bom/AGENTS.md +++ b/bom/AGENTS.md @@ -1,15 +1,12 @@ # AGENTS.md - bom -Bill of Materials (BOM) POM for the MongoDB Java Driver, simplifying dependency version -management. +Bill of Materials (BOM) POM for the MongoDB Java Driver, simplifying dependency version management. **Depends on:** All published driver modules (transitive version constraints only) ## Notes - Java Platform plugin — no source code, only version constraints -- Automatically includes all supported Scala version variants for `bson-scala` and - `driver-scala` -- Validates generated POM: all dependencies must be `org.mongodb`, no `` or - `` elements +- Automatically includes all supported Scala version variants for `bson-scala` and `driver-scala` +- Validates generated POM: all dependencies must be `org.mongodb`, no `` or `` elements - Do not add non-MongoDB dependencies to this module diff --git a/bson-scala/AGENTS.md b/bson-scala/AGENTS.md index 2bd52c3236a..e2a3fc8e4c6 100644 --- a/bson-scala/AGENTS.md +++ b/bson-scala/AGENTS.md @@ -1,12 +1,10 @@ # AGENTS.md - bson-scala -Scala extensions for the BSON library, providing Scala-idiomatic wrappers and -macro-based codecs. +Scala extensions for the BSON library, providing Scala-idiomatic wrappers and macro-based codecs. **Depends on:** `bson` -**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root -`gradle.properties`). +**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root `gradle.properties`). - Work here if: modifying Scala BSON wrappers, macro codecs, or Scala collection support diff --git a/buildSrc/AGENTS.md b/buildSrc/AGENTS.md index 214def88fc3..b4812d93d77 100644 --- a/buildSrc/AGENTS.md +++ b/buildSrc/AGENTS.md @@ -1,12 +1,11 @@ # AGENTS.md - buildSrc -Gradle build infrastructure providing convention plugins and shared configuration for -all modules. +Gradle build infrastructure providing convention plugins and shared configuration for all modules. ## Key Directories -- `src/main/kotlin/conventions/` — Convention plugins applied by modules (formatting, - testing, publishing, static analysis) +- `src/main/kotlin/conventions/` — Convention plugins applied by modules (formatting, testing, publishing, static + analysis) - `src/main/kotlin/project/` — Base project plugins for Java, Kotlin, and Scala modules - `src/main/kotlin/ProjectExtensions.kt` — Shared Gradle extension utilities @@ -53,19 +52,16 @@ all modules. ## Keeping AGENTS.md and Skills in Sync -When modifying buildSrc, you **must** update the relevant AGENTS.md files and skills (in -`.agents/skills/`) if your changes affect: +When modifying buildSrc, you **must** update the relevant AGENTS.md files and skills (in `.agents/skills/`) if your +changes affect: -- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root - `AGENTS.md` “Formatting” section, the `style-reference` skill, and any module - AGENTS.md files that reference formatting rules -- **Convention plugins added or removed** — update this file’s plugin table and the root - `AGENTS.md` if the change affects build commands or developer workflow -- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root - `AGENTS.md` “Testing” section, the `testing-guide` skill, and affected module - AGENTS.md files +- **Formatting conventions** (e.g., changes to `spotless.gradle.kts`) — update the root `AGENTS.md` “Formatting” + section, the `style-reference` skill, and any module AGENTS.md files that reference formatting rules +- **Convention plugins added or removed** — update this file’s plugin table and the root `AGENTS.md` if the change + affects build commands or developer workflow +- **Testing conventions** (e.g., changes to `testing-*.gradle.kts`) — update the root `AGENTS.md` “Testing” section, the + `testing-guide` skill, and affected module AGENTS.md files - **Project plugins added or removed** — update this file’s project plugin table -- **Build commands or task names changed** — update the root `AGENTS.md` “Build” and - “Before Submitting” sections, the `evergreen` skill, and any module “Before - Submitting” sections +- **Build commands or task names changed** — update the root `AGENTS.md` “Build” and “Before Submitting” sections, the + `evergreen` skill, and any module “Before Submitting” sections - **CI/CD or publishing changes** — update the `evergreen` skill diff --git a/driver-benchmarks/AGENTS.md b/driver-benchmarks/AGENTS.md index 0de4eeef3cd..75c9ff42c87 100644 --- a/driver-benchmarks/AGENTS.md +++ b/driver-benchmarks/AGENTS.md @@ -1,14 +1,13 @@ # AGENTS.md - driver-benchmarks -Performance benchmarks for the MongoDB Java Driver using JMH and a custom benchmark -framework. +Performance benchmarks for the MongoDB Java Driver using JMH and a custom benchmark framework. **Depends on:** `driver-sync`, `mongodb-crypt` ## Key Packages -- `com.mongodb.benchmark.benchmarks` — Benchmark suite and individual benchmarks (BSON, - single/multi-doc, bulk operations) +- `com.mongodb.benchmark.benchmarks` — Benchmark suite and individual benchmarks (BSON, single/multi-doc, bulk + operations) - `com.mongodb.benchmark.benchmarks.bulk` — Bulk write benchmarks - `com.mongodb.benchmark.benchmarks.netty` — Netty transport benchmarks - `com.mongodb.benchmark.framework` — Custom benchmark harness @@ -18,7 +17,5 @@ framework. - Not published — internal testing only - Non-standard source layout: `src/main` (no `java` subdirectory) -- Run benchmarks: `./gradlew :driver-benchmarks:run` or - `./gradlew :driver-benchmarks:jmh` -- Requires `-Dorg.mongodb.benchmarks.data` and `-Dorg.mongodb.benchmarks.output` system - properties +- Run benchmarks: `./gradlew :driver-benchmarks:run` or `./gradlew :driver-benchmarks:jmh` +- Requires `-Dorg.mongodb.benchmarks.data` and `-Dorg.mongodb.benchmarks.output` system properties diff --git a/driver-core/AGENTS.md b/driver-core/AGENTS.md index a44bb7fa10f..72839e445e8 100644 --- a/driver-core/AGENTS.md +++ b/driver-core/AGENTS.md @@ -3,17 +3,15 @@ Core driver internals shared by all driver variants (sync, reactive, Kotlin, Scala). Largest and most complex module. -**Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`, -`mongodb-crypt` +**Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`, `mongodb-crypt` -- Work here if: modifying query builders (`Filters`, `Updates`, `Aggregates`), - connection handling, wire protocol, server selection, or operation execution +- Work here if: modifying query builders (`Filters`, `Updates`, `Aggregates`), connection handling, wire protocol, + server selection, or operation execution - Do not: block in async code paths, modify wire protocol or auth without human approval ## Key Packages -- `com.mongodb.client.model` — `Filters`, `Updates`, `Projections`, `Aggregates`, - `Sorts`, `Indexes` +- `com.mongodb.client.model` — `Filters`, `Updates`, `Projections`, `Aggregates`, `Sorts`, `Indexes` - `com.mongodb.internal.connection` — Wire protocol, command execution (safety-critical) - `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate) - `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC (safety-critical) diff --git a/driver-kotlin-coroutine/AGENTS.md b/driver-kotlin-coroutine/AGENTS.md index 6c22260f113..471ee61fde2 100644 --- a/driver-kotlin-coroutine/AGENTS.md +++ b/driver-kotlin-coroutine/AGENTS.md @@ -9,8 +9,7 @@ Kotlin Coroutines driver providing `suspend` function-based async API. ## Key Packages -- `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`, - `MongoDatabase`, `MongoCollection`) +- `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`, `MongoDatabase`, `MongoCollection`) ## Build & Test diff --git a/driver-kotlin-extensions/AGENTS.md b/driver-kotlin-extensions/AGENTS.md index 0dea5d2b907..009b49e45c8 100644 --- a/driver-kotlin-extensions/AGENTS.md +++ b/driver-kotlin-extensions/AGENTS.md @@ -2,11 +2,9 @@ Kotlin extensions providing type-safe DSLs for query and update construction. -**Depends on:** `driver-core`, optionally `driver-kotlin-sync`, -`driver-kotlin-coroutine` +**Depends on:** `driver-core`, optionally `driver-kotlin-sync`, `driver-kotlin-coroutine` -- Work here if: adding or modifying Kotlin type-safe DSL builders for `Filters`, - `Updates`, `Aggregates`, etc. +- Work here if: adding or modifying Kotlin type-safe DSL builders for `Filters`, `Updates`, `Aggregates`, etc. - Works with both `driver-kotlin-sync` and `driver-kotlin-coroutine` ## Key Packages diff --git a/driver-kotlin-sync/AGENTS.md b/driver-kotlin-sync/AGENTS.md index e8ef0e86081..5f6d7ef32b0 100644 --- a/driver-kotlin-sync/AGENTS.md +++ b/driver-kotlin-sync/AGENTS.md @@ -9,8 +9,7 @@ Kotlin synchronous (blocking) driver — idiomatic Kotlin wrapper over `driver-s ## Key Packages -- `com.mongodb.kotlin.client` — Blocking sync API (`MongoClient`, `MongoDatabase`, - `MongoCollection`) +- `com.mongodb.kotlin.client` — Blocking sync API (`MongoClient`, `MongoDatabase`, `MongoCollection`) ## Build & Test diff --git a/driver-lambda/AGENTS.md b/driver-lambda/AGENTS.md index 15a92935465..29a83c6ed4d 100644 --- a/driver-lambda/AGENTS.md +++ b/driver-lambda/AGENTS.md @@ -1,7 +1,6 @@ # AGENTS.md - driver-lambda -AWS Lambda test application for validating the MongoDB Java Driver in Lambda -environments. +AWS Lambda test application for validating the MongoDB Java Driver in Lambda environments. **Depends on:** `bson`, `driver-sync` diff --git a/driver-legacy/AGENTS.md b/driver-legacy/AGENTS.md index 91fe5000e18..16c142ac1c4 100644 --- a/driver-legacy/AGENTS.md +++ b/driver-legacy/AGENTS.md @@ -10,8 +10,8 @@ Legacy MongoDB Java driver API — backwards compatibility facade for the 3.x AP ## Key Packages -- `com.mongodb` — Legacy API (`MongoClient`, `DB`, `DBCollection`, `DBCursor`) — - distinct from `driver-core` classes in the same namespace +- `com.mongodb` — Legacy API (`MongoClient`, `DB`, `DBCollection`, `DBCursor`) — distinct from `driver-core` classes in + the same namespace - `com.mongodb.gridfs` — Legacy GridFS ## Build & Test diff --git a/driver-reactive-streams/AGENTS.md b/driver-reactive-streams/AGENTS.md index f6f8e86216c..15e452358ac 100644 --- a/driver-reactive-streams/AGENTS.md +++ b/driver-reactive-streams/AGENTS.md @@ -1,7 +1,6 @@ # AGENTS.md - driver-reactive-streams -Reactive Streams driver implementing the -[Reactive Streams specification](https://www.reactive-streams.org/). +Reactive Streams driver implementing the [Reactive Streams specification](https://www.reactive-streams.org/). **Depends on:** `bson`, `driver-core` @@ -10,8 +9,7 @@ Reactive Streams driver implementing the ## Key Packages -- `com.mongodb.reactivestreams.client` — Publisher-based API (`MongoClient`, - `MongoDatabase`, `MongoCollection`) +- `com.mongodb.reactivestreams.client` — Publisher-based API (`MongoClient`, `MongoDatabase`, `MongoCollection`) ## Build & Test diff --git a/driver-scala/AGENTS.md b/driver-scala/AGENTS.md index 106c43230f8..b71b7e2c4de 100644 --- a/driver-scala/AGENTS.md +++ b/driver-scala/AGENTS.md @@ -4,16 +4,14 @@ Scala async driver providing Observable-based API wrapping `driver-reactive-stre **Depends on:** `bson-scala`, `driver-reactive-streams` -**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root -`gradle.properties`). +**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root `gradle.properties`). - Work here if: modifying the Scala Observable-based driver API or Scala model wrappers - Do not: block in any code path ## Key Packages -- `org.mongodb.scala` — Scala async driver (`MongoClient`, `MongoDatabase`, - `MongoCollection`) +- `org.mongodb.scala` — Scala async driver (`MongoClient`, `MongoDatabase`, `MongoCollection`) - `org.mongodb.scala.model` — Scala wrappers around filter/update builders ## Build & Test diff --git a/driver-sync/AGENTS.md b/driver-sync/AGENTS.md index 6bd02c1b61c..a02ad511c64 100644 --- a/driver-sync/AGENTS.md +++ b/driver-sync/AGENTS.md @@ -1,14 +1,12 @@ # AGENTS.md - driver-sync -Synchronous (blocking) Java driver — the most commonly used entry point for Java -applications. +Synchronous (blocking) Java driver — the most commonly used entry point for Java applications. **Depends on:** `bson`, `driver-core` -- Work here if: modifying the blocking Java API surface (`MongoClient`, `MongoDatabase`, - `MongoCollection`), GridFS, or CSFLE vault client -- Do not: add new Spock tests (legacy only), add internal connection/protocol code (that - belongs in `driver-core`) +- Work here if: modifying the blocking Java API surface (`MongoClient`, `MongoDatabase`, `MongoCollection`), GridFS, or + CSFLE vault client +- Do not: add new Spock tests (legacy only), add internal connection/protocol code (that belongs in `driver-core`) ## Key Packages @@ -23,7 +21,6 @@ applications. ./gradlew :driver-sync:check ``` -Primary entry point: `MongoClients.create()` or -`MongoClients.create(MongoClientSettings)`. +Primary entry point: `MongoClients.create()` or `MongoClients.create(MongoClientSettings)`. For global rules see [root AGENTS.md](../AGENTS.md). diff --git a/graalvm-native-image-app/AGENTS.md b/graalvm-native-image-app/AGENTS.md index 24a9d3cbf3f..40de264de12 100644 --- a/graalvm-native-image-app/AGENTS.md +++ b/graalvm-native-image-app/AGENTS.md @@ -1,15 +1,12 @@ # AGENTS.md - graalvm-native-image-app -GraalVM Native Image test application verifying driver compatibility with native -compilation. +GraalVM Native Image test application verifying driver compatibility with native compilation. -**Depends on:** `bson`, `driver-core`, `driver-sync`, `driver-legacy`, -`driver-reactive-streams`, `mongodb-crypt` +**Depends on:** `bson`, `driver-core`, `driver-sync`, `driver-legacy`, `driver-reactive-streams`, `mongodb-crypt` ## Key Packages -- `com.mongodb.internal.graalvm` — Native image test app, GraalVM substitutions, and - custom DNS support +- `com.mongodb.internal.graalvm` — Native image test app, GraalVM substitutions, and custom DNS support ## Notes diff --git a/gradle/AGENTS.md b/gradle/AGENTS.md index f0ff385650e..7bdb8910d0f 100644 --- a/gradle/AGENTS.md +++ b/gradle/AGENTS.md @@ -4,19 +4,17 @@ Gradle configuration and infrastructure for the build system. ## Key Files -- `libs.versions.toml` — Central version catalog defining all dependency versions, - library coordinates, bundles, and plugin versions +- `libs.versions.toml` — Central version catalog defining all dependency versions, library coordinates, bundles, and + plugin versions - `wrapper/` — Gradle wrapper JAR and properties (do not modify manually — use `./gradlew wrapper --gradle-version=`) - `scala/lib/` — Bundled Scala Ant JAR for Scala compilation support ## Notes -- All dependency versions are managed in `libs.versions.toml` — never declare versions - inline in `build.gradle.kts` files +- All dependency versions are managed in `libs.versions.toml` — never declare versions inline in `build.gradle.kts` + files - Never add dependencies without justification -- The version catalog defines `[versions]`, `[libraries]`, `[bundles]`, and `[plugins]` - sections +- The version catalog defines `[versions]`, `[libraries]`, `[bundles]`, and `[plugins]` sections - Scala test libraries are declared per Scala version (v3, v2-v13, v2-v12, v2-v11) -- When adding or updating dependencies, modify `libs.versions.toml` and reference via - `libs.` in build scripts +- When adding or updating dependencies, modify `libs.versions.toml` and reference via `libs.` in build scripts diff --git a/mongodb-crypt/AGENTS.md b/mongodb-crypt/AGENTS.md index d324bafe214..7d7323b3a7c 100644 --- a/mongodb-crypt/AGENTS.md +++ b/mongodb-crypt/AGENTS.md @@ -5,15 +5,14 @@ Client-side field-level encryption (CSFLE) support via JNA bindings to libmongoc **Depends on:** `bson` - Work here if: modifying CSFLE encryption/decryption logic or JNA bindings -- Do not: move, re-expose, or refactor JNA/libmongocrypt bindings without human approval - — this is security-critical code -- Do not: modify the C API binding layer without understanding the libmongocrypt - contract +- Do not: move, re-expose, or refactor JNA/libmongocrypt bindings without human approval — this is security-critical + code +- Do not: modify the C API binding layer without understanding the libmongocrypt contract ## Key Packages -- `com.mongodb.crypt.capi` — mongocryptd C API bindings (JNA) — **security-critical, do - not modify without human review** +- `com.mongodb.crypt.capi` — mongocryptd C API bindings (JNA) — **security-critical, do not modify without human + review** - `com.mongodb.internal.crypt.capi` — Internal encryption state management ## Build & Test diff --git a/testing/AGENTS.md b/testing/AGENTS.md index 6c1518edd80..ea168df20ac 100644 --- a/testing/AGENTS.md +++ b/testing/AGENTS.md @@ -4,8 +4,8 @@ Shared test resources and MongoDB specification test data. ## Notes -- `resources/specifications/` — Git submodule containing MongoDB specification test data - (CRUD, SDAM, auth, CSFLE, retryable ops, etc.) +- `resources/specifications/` — Git submodule containing MongoDB specification test data (CRUD, SDAM, auth, CSFLE, + retryable ops, etc.) - `resources/logback-test.xml` — Shared logback configuration for tests - **Do not modify spec test data** — managed upstream. Update via `git submodule update`. From 62666c68bdbb0bbb998e0c3aca8df423d4438b50 Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Tue, 24 Mar 2026 17:25:15 +0000 Subject: [PATCH 06/10] Reverted README.md formatting changes --- README.md | 130 +++++++++++++++++++++--------------------------------- 1 file changed, 51 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 2af3ad5adcf..8a28cd89cb2 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,44 @@ ## Release Notes -Release notes are available -[here](https://github.com/mongodb/mongo-java-driver/releases). +Release notes are available [here](https://github.com/mongodb/mongo-java-driver/releases). ## Documentation -Reference and API documentation for the Java driver is available -[here](https://www.mongodb.com/docs/drivers/java/sync/current/). +Reference and API documentation for the Java driver is available [here](https://www.mongodb.com/docs/drivers/java/sync/current/). -Reference and API documentation for the Kotlin driver is available -[here](https://www.mongodb.com/docs/drivers/kotlin/coroutine/current/). +Reference and API documentation for the Kotlin driver is available [here](https://www.mongodb.com/docs/drivers/kotlin/coroutine/current/). -Reference and API documentation for the Scala driver is available -[here](https://www.mongodb.com/docs/languages/scala/scala-driver/current/). +Reference and API documentation for the Scala driver is available [here](https://www.mongodb.com/docs/languages/scala/scala-driver/current/). ## Tutorials / Training -For tutorials on how to use the MongoDB JVM Drivers, please reference -[MongoDB University](https://learn.mongodb.com/). Additional tutorials, videos, and code -examples using both the Java Driver and the Kotlin Driver can also be found in the -[MongoDB Developer Center](https://www.mongodb.com/developer/). +For tutorials on how to use the MongoDB JVM Drivers, please reference [MongoDB University](https://learn.mongodb.com/). Additional tutorials, videos, and code examples using both the Java Driver and the Kotlin Driver can also be found in the [MongoDB Developer Center](https://www.mongodb.com/developer/). ## Support / Feedback -For issues with, questions about, or feedback for the MongoDB Java, Kotlin, and Scala -drivers, please look into our -[support channels](https://www.mongodb.com/docs/manual/support/). Please do not email -any of the driver developers directly with issues or questions - you’re more likely to -get an answer on the -[MongoDB Community Forums](https://community.mongodb.com/tags/c/drivers-odms-connectors/7/java-driver) -or [StackOverflow](https://stackoverflow.com/questions/tagged/mongodb+java). - -At a minimum, please include in your description the exact version of the driver that -you are using. If you are having connectivity issues, it’s often also useful to paste in -the line of code where you construct the MongoClient instance, along with the values of -all parameters that you pass to the constructor. -You should also check your application logs for any connectivity-related exceptions and -post those as well. +For issues with, questions about, or feedback for the MongoDB Java, Kotlin, and Scala drivers, please look into +our [support channels](https://www.mongodb.com/docs/manual/support/). Please +do not email any of the driver developers directly with issues or +questions - you're more likely to get an answer on the [MongoDB Community Forums](https://community.mongodb.com/tags/c/drivers-odms-connectors/7/java-driver) or [StackOverflow](https://stackoverflow.com/questions/tagged/mongodb+java). + +At a minimum, please include in your description the exact version of the driver that you are using. If you are having +connectivity issues, it's often also useful to paste in the line of code where you construct the MongoClient instance, +along with the values of all parameters that you pass to the constructor. You should also check your application logs for +any connectivity-related exceptions and post those as well. ## Bugs / Feature Requests -Think you’ve found a bug in the Java, Kotlin, or Scala drivers? -Want to see a new feature in the drivers? -Please open a case in our issue management tool, JIRA: +Think you’ve found a bug in the Java, Kotlin, or Scala drivers? Want to see a new feature in the drivers? Please open a +case in our issue management tool, JIRA: - [Create an account and login](https://jira.mongodb.org). - Navigate to [the JAVA project](https://jira.mongodb.org/browse/JAVA). -- Click **Create Issue** - Please provide as much information as possible about the - issue type, which driver you are using, and how to reproduce your issue. +- Click **Create Issue** - Please provide as much information as possible about the issue type, which driver you are using, and how to reproduce your issue. -Bug reports in JIRA for the driver and the Core Server (i.e. SERVER) project are -**public**. +Bug reports in JIRA for the driver and the Core Server (i.e. SERVER) project are **public**. -If you’ve identified a security vulnerability in a driver or any other MongoDB project, -please report it according to the -[instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). +If you’ve identified a security vulnerability in a driver or any other +MongoDB project, please report it according to the [instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report). ## Versioning @@ -62,35 +46,30 @@ We follow [semantic versioning](https://semver.org/spec/v2.0.0.html) when releas #### @Alpha -APIs marked with the `@Alpha` annotation are in the early stages of development, subject -to incompatible changes, or even removal, in a future release and may lack some intended -features. An APIs bearing `@Alpha` annotation may contain known issues affecting -functionality, performance, and stability. -They are also exempt from any compatibility guarantees made by its containing library. +APIs marked with the `@Alpha` annotation are in the early stages of development, subject to incompatible changes, +or even removal, in a future release and may lack some intended features. An APIs bearing `@Alpha` annotation may +contain known issues affecting functionality, performance, and stability. They are also exempt from any compatibility +guarantees made by its containing library. -It is inadvisable for applications to use Alpha APIs in production environments -or for libraries (which get included on users’ CLASSPATHs, outside the library -developers’ control) to depend on these APIs. -Alpha APIs are intended for experimental purposes only. +It is inadvisable for applications to use Alpha APIs in production environments or for libraries +(which get included on users' CLASSPATHs, outside the library developers' control) to depend on these APIs. Alpha APIs +are intended for experimental purposes only. #### @Beta -APIs marked with the `@Beta` annotation at the class or method level are subject to -change. They can be modified in any way, or even removed, at any time. -If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your -own control), you should not use beta APIs, unless you repackage them (e.g. by using -shading, etc). +APIs marked with the `@Beta` annotation at the class or method level are subject to change. They can be modified in any way, or even +removed, at any time. If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your own control), you should not +use beta APIs, unless you repackage them (e.g. by using shading, etc). #### @Deprecated -APIs marked with the `@Deprecated` annotation at the class or method level will remain -supported until the next major release but it is recommended to stop using them. +APIs marked with the `@Deprecated` annotation at the class or method level will remain supported until the next major release but it is +recommended to stop using them. #### com.mongodb.internal.* -All code inside the `com.mongodb.internal.*` packages is considered private API and -should not be relied upon at all. -It can change at any time. +All code inside the `com.mongodb.internal.*` packages is considered private API and should not be relied upon at all. It can change at any +time. ## Binaries @@ -106,7 +85,6 @@ Example for Maven: x.y.z ``` - Snapshot builds are also published regularly via Sonatype. Example for Maven: @@ -129,8 +107,7 @@ Example for Maven: ## Build -Java 17+ and git is required to build and compile the source. -To build and test the driver: +Java 17+ and git is required to build and compile the source. To build and test the driver: ``` $ git clone --recurse-submodules https://github.com/mongodb/mongo-java-driver.git @@ -138,17 +115,15 @@ $ cd mongo-java-driver $ ./gradlew check ``` -The test suite requires mongod to be running with -[`enableTestCommands`](https://www.mongodb.com/docs/manual/reference/parameters/#param.enableTestCommands), -which may be set with the `--setParameter enableTestCommands=1` command-line parameter: +The test suite requires mongod to be running with [`enableTestCommands`](https://www.mongodb.com/docs/manual/reference/parameters/#param.enableTestCommands), which may be set with the `--setParameter enableTestCommands=1` +command-line parameter: ``` $ mkdir -p data/db $ mongod --dbpath ./data/db --logpath ./data/mongod.log --port 27017 --logappend --fork --setParameter enableTestCommands=1 ``` -If you encounter `"Too many open files"` errors when running the tests then you will -need to increase the number of available file descriptors prior to starting mongod as -described in https://www.mongodb.com/docs/manual/reference/ulimit/ +If you encounter `"Too many open files"` errors when running the tests then you will need to increase +the number of available file descriptors prior to starting mongod as described in [https://www.mongodb.com/docs/manual/reference/ulimit/](https://www.mongodb.com/docs/manual/reference/ulimit/) ## AI Agent Configuration @@ -168,18 +143,15 @@ A couple of manual configuration steps are required to run the code in IntelliJ: - Java 17+ is required to build and compile the source. -- **Error:** - `java: cannot find symbol: class SNIHostName location: package javax.net.ssl`
- **Fix:** Settings/Preferences > Build, Execution, Deployment > Compiler > Java - Compiler - untick “Use '--release' option for cross-compilation (Java 9 and later)” - -- **Error:** `java: package com.mongodb.internal.build does not exist`
**Fixes:** - Any of the following:
- - Run the `generateBuildConfig` task: eg: `./gradlew generateBuildConfig` or via - Gradle > driver-core > Tasks > buildconfig > generateBuildConfig - - Set `generateBuildConfig` to execute Before Build. - via Gradle > Tasks > buildconfig > right click generateBuildConfig - click on - “Execute Before Build” - - Delegate all build actions to Gradle: Settings/Preferences > Build, Execution, - Deployment > Build Tools > Gradle > Build and run using/Run tests using - select - “Gradle” +- **Error:** `java: cannot find symbol: class SNIHostName location: package javax.net.ssl`
+ **Fix:** Settings/Preferences > Build, Execution, Deployment > Compiler > Java Compiler - untick "Use '--release' option for + cross-compilation (Java 9 and later)" + +- **Error:** `java: package com.mongodb.internal.build does not exist`
+ **Fixes:** Any of the following:
+ - Run the `generateBuildConfig` task: eg: `./gradlew generateBuildConfig` or via Gradle > driver-core > Tasks > buildconfig > + generateBuildConfig + - Set `generateBuildConfig` to execute Before Build. via Gradle > Tasks > buildconfig > right click generateBuildConfig - click on + "Execute Before Build" + - Delegate all build actions to Gradle: Settings/Preferences > Build, Execution, Deployment > Build Tools > Gradle > Build and run + using/Run tests using - select "Gradle" From 18d6af6c39e422584aa16c07f91168c5f22fd06c Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Tue, 24 Mar 2026 17:32:11 +0000 Subject: [PATCH 07/10] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .agents/skills/style-reference/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/style-reference/SKILL.md b/.agents/skills/style-reference/SKILL.md index 962da49c7bd..0ac14435419 100644 --- a/.agents/skills/style-reference/SKILL.md +++ b/.agents/skills/style-reference/SKILL.md @@ -13,7 +13,7 @@ description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in th - **Star imports:** Prohibited (AvoidStarImport) - **Final parameters:** Required (FinalParameters checkstyle rule) - **Braces:** Required for all control structures (NeedBraces) -- **Else placement:** On its own line (not cuddled) +- **Else placement:** `} else {` on the same line (Palantir Java Format default) - **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.` - **Formatter:** Palantir Java Format From 733a55740e33074788c1cf5cc8c00b535b7676bd Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Tue, 24 Mar 2026 17:32:59 +0000 Subject: [PATCH 08/10] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d062489202a..73572bf9223 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,7 +30,7 @@ Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in `gr ## Style -`check` runs `spotlessApply` automatically — formatting is enforced. +`check` runs `spotlessCheck` to verify formatting — run `./gradlew spotlessApply` to auto-format when needed. Do not reformat outside your changes. See [`.agents/skills/style-reference`](.agents/skills/style-reference/SKILL.md) for full rules. From f4984dc5d750b7584a1b68c982ca8c6a2e5f172c Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Tue, 24 Mar 2026 19:02:18 +0000 Subject: [PATCH 09/10] Added ./scripts/symlink-claude-md.sh --- scripts/symlink-claude-md.sh | 105 +++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100755 scripts/symlink-claude-md.sh diff --git a/scripts/symlink-claude-md.sh b/scripts/symlink-claude-md.sh new file mode 100755 index 00000000000..95a060eaf41 --- /dev/null +++ b/scripts/symlink-claude-md.sh @@ -0,0 +1,105 @@ +#!/usr/bin/env bash +# 1. Ensure every staged AGENTS.md has a companion CLAUDE.md containing +# "@AGENTS.md" (a Claude Code import reference). +# 2. Ensure .claude/skills is a symlink to .agents/skills. + +set -euo pipefail + +claude_file_for_agents() { + local agents_file="$1" + local dir + + dir=$(dirname "$agents_file") + + if [ "$dir" = "." ]; then + printf 'CLAUDE.md\n' + else + printf '%s/CLAUDE.md\n' "$dir" + fi +} + +remove_generated_file() { + local generated_file="$1" + + if git ls-files --error-unmatch -- "$generated_file" > /dev/null 2>&1 || [ -e "$generated_file" ]; then + rm -f "$generated_file" + git add -u -- "$generated_file" + echo "auto-removed: $generated_file" + fi +} + +sync_claude_skills_dir() { + local claude_skills_dir=".claude/skills" + local expected_target="../.agents/skills" + local current_target + + if [ -L "$claude_skills_dir" ]; then + current_target=$(readlink "$claude_skills_dir") + if [ "$current_target" = "$expected_target" ]; then + return + fi + + rm -f "$claude_skills_dir" + elif [ -e "$claude_skills_dir" ]; then + rm -rf "$claude_skills_dir" + fi + + mkdir -p .claude + ln -s "$expected_target" "$claude_skills_dir" + git add "$claude_skills_dir" + echo "auto-synced: $claude_skills_dir -> $expected_target" +} + +sync_claude_skills_dir + +staged_agents=() +deleted_agents=() + +while IFS=$'\t ' read -r status first_path second_path; do + [ -n "$status" ] || continue + + case "$status" in + R*) + if [[ "$first_path" =~ (^|/)AGENTS\.md$ ]]; then + deleted_agents+=("$first_path") + fi + if [[ "$second_path" =~ (^|/)AGENTS\.md$ ]]; then + staged_agents+=("$second_path") + fi + ;; + D) + if [[ "$first_path" =~ (^|/)AGENTS\.md$ ]]; then + deleted_agents+=("$first_path") + fi + ;; + *) + if [[ "$first_path" =~ (^|/)AGENTS\.md$ ]]; then + staged_agents+=("$first_path") + fi + ;; + esac +done < <(git diff --cached --name-status --find-renames --diff-filter=ADMR) + +# --- CLAUDE.md sync --- +if [ "${#staged_agents[@]}" -gt 0 ]; then + for agents_file in "${staged_agents[@]}"; do + claude_file=$(claude_file_for_agents "$agents_file") + + # Skip if already a regular file with the correct content + if [ -f "$claude_file" ] && ! [ -L "$claude_file" ] && [ "$(cat "$claude_file")" = "@AGENTS.md" ]; then + continue + fi + + # Remove symlink if present, then write the reference file + rm -f "$claude_file" + printf '@AGENTS.md\n' > "$claude_file" + git add "$claude_file" + echo "auto-created: $claude_file with @AGENTS.md reference" + done +fi + +if [ "${#deleted_agents[@]}" -gt 0 ]; then + for agents_file in "${deleted_agents[@]}"; do + remove_generated_file "$(claude_file_for_agents "$agents_file")" + done +fi From d8b85e38de0081dc99a94f6f411c6ac1d04a9897 Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Mon, 13 Apr 2026 13:00:11 +0100 Subject: [PATCH 10/10] Claude self review updates --- .agents/skills/api-design/SKILL.md | 18 +---- .agents/skills/evergreen/SKILL.md | 4 +- .agents/skills/spec-tests/SKILL.md | 7 +- .agents/skills/style-reference/SKILL.md | 13 +++- .agents/skills/sync-agents-docs/SKILL.md | 27 ++++++++ .agents/skills/testing-guide/SKILL.md | 9 +++ .agents/skills/testing-guide/examples.md | 88 ++++++++++++++++++++++++ .gitignore | 4 +- AGENTS.md | 32 +++++++++ bom/AGENTS.md | 12 ---- bom/CLAUDE.md | 1 - bson-kotlin/AGENTS.md | 2 - bson-kotlinx/AGENTS.md | 2 - bson-record-codec/AGENTS.md | 4 +- bson-scala/AGENTS.md | 1 - bson/AGENTS.md | 3 - buildSrc/AGENTS.md | 17 +---- driver-core/AGENTS.md | 3 - driver-kotlin-coroutine/AGENTS.md | 2 - driver-kotlin-extensions/AGENTS.md | 2 - driver-kotlin-sync/AGENTS.md | 2 - driver-lambda/AGENTS.md | 16 ----- driver-lambda/CLAUDE.md | 1 - driver-legacy/AGENTS.md | 2 - driver-reactive-streams/AGENTS.md | 2 - driver-scala/AGENTS.md | 1 - driver-sync/AGENTS.md | 2 - graalvm-native-image-app/AGENTS.md | 17 ----- graalvm-native-image-app/CLAUDE.md | 1 - mongodb-crypt/AGENTS.md | 2 - 30 files changed, 183 insertions(+), 114 deletions(-) create mode 100644 .agents/skills/sync-agents-docs/SKILL.md create mode 100644 .agents/skills/testing-guide/examples.md delete mode 100644 bom/AGENTS.md delete mode 100644 bom/CLAUDE.md delete mode 100644 driver-lambda/AGENTS.md delete mode 100644 driver-lambda/CLAUDE.md delete mode 100644 graalvm-native-image-app/AGENTS.md delete mode 100644 graalvm-native-image-app/CLAUDE.md diff --git a/.agents/skills/api-design/SKILL.md b/.agents/skills/api-design/SKILL.md index f6642cf83bd..23e89ebe457 100644 --- a/.agents/skills/api-design/SKILL.md +++ b/.agents/skills/api-design/SKILL.md @@ -7,9 +7,9 @@ description: API stability annotations, design principles, and patterns for the ## API Stability Annotations - `@Alpha` — Early development, may be removed. - Not for production use. + Not recommended for production use. - `@Beta` — Subject to change or removal. - Libraries should not depend on these. + It's not recommended for Libraries to depend on these APIs. - `@Evolving` — May add abstract methods in future releases. Safe to use, but implementing/extending bears upgrade risk. - `@Sealed` — Must not be extended or implemented by consumers. @@ -24,22 +24,8 @@ description: API stability annotations, design principles, and patterns for the - **General-purpose over special-case:** Fewer flexible methods over many specialized ones. - **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them. -## Search Before Implementing - -Before writing new code, search the codebase for existing implementations: - -- Check if a utility method already exists in `com.mongodb.internal.*` -- Check if a similar pattern is established elsewhere in the module -- Reuse existing well-tested infrastructure over creating duplicates - ## Key Patterns - Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()` - Fluent builders: `MongoClientSettings.builder()` is the primary entry point - Abstract core with pluggable transports - -## Public API Rules - -- Breaking changes require a major version bump - ALWAYS warn if breaking binary compatibility -- All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in public APIs -- Every public package must have a `package-info.java` diff --git a/.agents/skills/evergreen/SKILL.md b/.agents/skills/evergreen/SKILL.md index 603beeb9c60..37b73a03f78 100644 --- a/.agents/skills/evergreen/SKILL.md +++ b/.agents/skills/evergreen/SKILL.md @@ -1,6 +1,8 @@ --- name: evergreen description: Evergreen CI infrastructure, configuration validation. Use when modifying .evergreen/ config, preparing to submit changes or understanding the Evergreen test matrix. +disable-model-invocation: true +allowed-tools: Bash(evergreen *) --- # Evergreen @@ -17,7 +19,7 @@ Configuration lives in `.evergreen/`. After modifying `.evergreen/` files, validate the config locally: ```bash -evergreen validate $PROJECT_PATH/.evergreen/.evg.yml +evergreen validate .evergreen/.evg.yml ``` Always run this before submitting changes to `.evergreen/` to catch syntax errors and invalid task definitions. diff --git a/.agents/skills/spec-tests/SKILL.md b/.agents/skills/spec-tests/SKILL.md index 6c07b7d7f5e..5ba9041cfbc 100644 --- a/.agents/skills/spec-tests/SKILL.md +++ b/.agents/skills/spec-tests/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-tests -description: How to work with MongoDB specification tests — structure, rules, and adding new spec test support. Use when implementing or modifying behavior defined by the MongoDB Driver Specifications, or when working with the test data in testing/resources/specifications/. +description: How to work with MongoDB specification tests — structure, rules, and adding new spec test support. Use when implementing or modifying behavior defined by the MongoDB Driver Specifications. --- # MongoDB Specification Tests @@ -11,9 +11,8 @@ Specification test data files live in `testing/resources/specifications/` — a ## Rules -- **Do not modify existing specification tests** unless they test incorrect behavior -- **Do not modify spec test data** — it is managed upstream -- Create new tests instead of modifying existing ones +- **Do not modify spec test data files** (JSON/YAML in `testing/resources/specifications/`) — managed upstream +- Test runners (Java code) may be modified to fix bugs or add support for new spec tests - Update the submodule via `git submodule update` ## Structure diff --git a/.agents/skills/style-reference/SKILL.md b/.agents/skills/style-reference/SKILL.md index 0ac14435419..fa9adfe85f2 100644 --- a/.agents/skills/style-reference/SKILL.md +++ b/.agents/skills/style-reference/SKILL.md @@ -1,6 +1,6 @@ --- name: style-reference -description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in the MongoDB Java Driver. Use when you need specific formatting rules beyond the basics in root AGENTS.md — e.g., line length, import ordering, brace style, or language-specific formatter configuration. Spotless auto-enforces most rules. +description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in the MongoDB Java Driver. Use when you need specific formatting rules beyond the basics in root AGENTS.md — e.g., line length, import ordering, brace style. --- # Style Reference @@ -31,6 +31,17 @@ description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in th - **Static analysis:** CodeNarc +## Javadoc / KDoc / Scaladoc + +- All public classes and interfaces **must** have class-level Javadoc (enforced by checkstyle) +- Public methods should have Javadoc with `@param`, `@return`, and `@since` tags +- Use `@since X.Y` to indicate the version when the API was introduced +- Use `@mongodb.driver.manual