{"owner":"mongodb","repo":"mongo-go-driver","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI agents when working with code in this repository.\n\n## Project\n\nOfficial MongoDB Go Driver (`go.mongodb.org/mongo-driver/v2`). Correctness, backward compatibility, and conformance to [MongoDB Driver Specifications](https://github.com/mongodb/specifications) are top priorities.\n\n- Module: `go.mongodb.org/mongo-driver/v2`\n- Issue tracker: [JIRA GODRIVER project](https://jira.mongodb.org/browse/GODRIVER) — GitHub Issues is not used for bugs/features\n- Active major version: v2 on `master`. v1 lives on `release/1.x` branches.\n\n## Build, test, and lint\n\nUses **[Task](https://taskfile.dev/)**, not make.\n\n```\ntask                 # default: build + check-license + check-fmt + check-modules + lint + test-short\ntask fmt             # gofumpt -w . — use this, not plain gofmt\ntask build           # includes compilecheck-min (Go min-version compat)\ntask lint            # golangci-lint across linux/{386,arm,arm64,amd64,ppc64le,s390x}\ntask test-short      # race detector, ~60s timeout — fast feedback\ntask test            # full suite, serial (-p 1), 1800s timeout, requires mongod\ntask api-report      # required when public API changes — include output in PR description\n```\n\n**Tests require a running `mongod`** on `localhost:27017` (or `MONGODB_URI`). The full test suite is **serial** (`-p 1`) — integration tests share server state. Do not parallelize.\n\n## Go version requirements\n\n- **Go 1.25**: minimum to compile/use the driver. The Go Driver supports the last two Go minor versions. Public packages (`mongo/`, `bson/`, `event/`, `tag/`) must build on 1.25. `compilecheck-min` enforces this at build time.\n- **Go 1.26+**: required to run the test suite and develop the driver.\n\n## Gotchas\n\n1. **`x/` packages are importable but not semver-covered.** Users do import `x/mongo/driver` etc. Flag breaking changes explicitly in PR descriptions even though semver doesn't require it.\n1. **Atomic alignment on 32-bit.** `int64`/`uint64` fields accessed via `sync/atomic` must be at struct start or use `atomic.Int64`. The lint pass on `GOARCH=386` catches this — don't skip cross-arch lint.\n1. **GridFS lives in `mongo/`.** v2 merged `gridfs.Bucket` into `mongo.GridFSBucket`. Don't resurrect the old `gridfs` import path.\n1. **CSOT timeouts.** Use context deadlines; do not introduce per-call wall-clock timers that race with the user's context.\n1. **Command monitoring redacts credentials.** When adding commands that handle credentials (`authenticate`, `saslStart`, etc.), add them to the redaction list.\n1. **`libmongocrypt` required for CSFLE/QE tests.** Install with `task install-libmongocrypt`. CSFLE code requires the `cse` build tag.\n\n## Code conventions\n\n- **Formatter**: `gofumpt` (stricter superset of gofmt). Always use `task fmt`, never plain gofmt.\n- **Errors**: `fmt.Errorf(\"…: %w\", err)` for wrapping. Use `errors.Is`/`errors.As` for comparisons — never `strings.Contains` on error messages. Sentinel errors live in the `mongo` package (`mongo.ErrNoDocuments`, etc.).\n- **Context**: Every blocking public method takes `context.Context` as its first argument. Use `mongo.SessionFromContext(ctx)` (v2 pattern) — not the old `mongo.SessionContext`.\n- **BSON**: `bson.D` for ordered documents and commands. `bson.M` only when order genuinely doesn't matter. `bsoncore.Document` in hot paths (zero-copy, byte-slice-backed).\n- **Exported names**: Full words, not abbreviations (`ClientBulkWriteResult`, not `CBWResult`). Doc comments required on all exported identifiers using the \"name is subject\" convention.\n- **New options**: Follow the setter pattern: `func (o *XxxOptionsBuilder) SetFoo(v T) *XxxOptionsBuilder`.\n\n## Tests\n\n- Use `internal/assert` (wraps testify) for assertions. Prefer `assert.ErrorIs` over `assert.ErrorContains`.\n- Integration tests: use `internal/integration/mtest` for topology-aware setup, fail-point injection, and event capture.\n- Spec tests: JSON/YAML fixtures under `testdata/` (git submodule — run `task init-submodule` after cloning if missing).\n- Prose tests: number them to match the spec (e.g., `\"3. bulkWrite batch splits…\"`) for cross-referencing.\n- Unit tests live next to the code (`foo.go` ↔ `foo_test.go`). Integration tests live in `internal/integration/`.\n\n## PR and commit conventions\n\n- **JIRA prefix required**: `GODRIVER-1234 Short description` for all commit messages and PR titles.\n- Features → `master`. Bug fixes → latest stable release branch (e.g., `release/2.5`). The \"Merge up\" GitHub Action propagates fixes to newer branches automatically.\n- Run `task` (default target) before every PR.\n- Changed public API (`mongo/`, `bson/`, `event/`, `tag/`)? Run `task api-report` and include the output in the PR description.\n- User-visible breaking change? Update `docs/migration-2.0.md`.\n- Spec compliance changes? Quote the relevant spec requirement in the PR description.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI agents when working with code in this repository.\n\n## Project\n\nOfficial MongoDB Go Driver (`go.mongodb.org/mongo-driver/v2`). Correctness, backward compatibility, and conformance to [MongoDB Driver Specifications](https://github.com/mongodb/specifications) are top priorities.\n\n- Module: `go.mongodb.org/mongo-driver/v2`\n- Issue tracker: [JIRA GODRIVER project](https://jira.mongodb.org/browse/GODRIVER) — GitHub Issues is not used for bugs/features\n- Active major version: v2 on `master`. v1 lives on `release/1.x` branches.\n\n## Build, test, and lint\n\nUses **[Task](https://taskfile.dev/)**, not make.\n\n```\ntask                 # default: build + check-license + check-fmt + check-modules + lint + test-short\ntask fmt             # gofumpt -w . — use this, not plain gofmt\ntask build           # includes compilecheck-min (Go min-version compat)\ntask lint            # golangci-lint across linux/{386,arm,arm64,amd64,ppc64le,s390x}\ntask test-short      # race detector, ~60s timeout — fast feedback\ntask test            # full suite, serial (-p 1), 1800s timeout, requires mongod\ntask api-report      # required when public API changes — include output in PR description\n```\n\n**Tests require a running `mongod`** on `localhost:27017` (or `MONGODB_URI`). The full test suite is **serial** (`-p 1`) — integration tests share server state. Do not parallelize.\n\n## Go version requirements\n\n- **Go 1.25**: minimum to compile/use the driver. The Go Driver supports the last two Go minor versions. Public packages (`mongo/`, `bson/`, `event/`, `tag/`) must build on 1.25. `compilecheck-min` enforces this at build time.\n- **Go 1.26+**: required to run the test suite and develop the driver.\n\n## Gotchas\n\n1. **`x/` packages are importable but not semver-covered.** Users do import `x/mongo/driver` etc. Flag breaking changes explicitly in PR descriptions even though semver doesn't require it.\n1. **Atomic alignment on 32-bit.** `int64`/`uint64` fields accessed via `sync/atomic` must be at struct start or use `atomic.Int64`. The lint pass on `GOARCH=386` catches this — don't skip cross-arch lint.\n1. **GridFS lives in `mongo/`.** v2 merged `gridfs.Bucket` into `mongo.GridFSBucket`. Don't resurrect the old `gridfs` import path.\n1. **CSOT timeouts.** Use context deadlines; do not introduce per-call wall-clock timers that race with the user's context.\n1. **Command monitoring redacts credentials.** When adding commands that handle credentials (`authenticate`, `saslStart`, etc.), add them to the redaction list.\n1. **`libmongocrypt` required for CSFLE/QE tests.** Install with `task install-libmongocrypt`. CSFLE code requires the `cse` build tag.\n\n## Code conventions\n\n- **Formatter**: `gofumpt` (stricter superset of gofmt). Always use `task fmt`, never plain gofmt.\n- **Errors**: `fmt.Errorf(\"…: %w\", err)` for wrapping. Use `errors.Is`/`errors.As` for comparisons — never `strings.Contains` on error messages. Sentinel errors live in the `mongo` package (`mongo.ErrNoDocuments`, etc.).\n- **Context**: Every blocking public method takes `context.Context` as its first argument. Use `mongo.SessionFromContext(ctx)` (v2 pattern) — not the old `mongo.SessionContext`.\n- **BSON**: `bson.D` for ordered documents and commands. `bson.M` only when order genuinely doesn't matter. `bsoncore.Document` in hot paths (zero-copy, byte-slice-backed).\n- **Exported names**: Full words, not abbreviations (`ClientBulkWriteResult`, not `CBWResult`). Doc comments required on all exported identifiers using the \"name is subject\" convention.\n- **New options**: Follow the setter pattern: `func (o *XxxOptionsBuilder) SetFoo(v T) *XxxOptionsBuilder`.\n\n## Tests\n\n- Use `internal/assert` (wraps testify) for assertions. Prefer `assert.ErrorIs` over `assert.ErrorContains`.\n- Integration tests: use `internal/integration/mtest` for topology-aware setup, fail-point injection, and event capture.\n- Spec tests: JSON/YAML fixtures under `testdata/` (git submodule — run `task init-submodule` after cloning if missing).\n- Prose tests: number them to match the spec (e.g., `\"3. bulkWrite batch splits…\"`) for cross-referencing.\n- Unit tests live next to the code (`foo.go` ↔ `foo_test.go`). Integration tests live in `internal/integration/`.\n\n## PR and commit conventions\n\n- **JIRA prefix required**: `GODRIVER-1234 Short description` for all commit messages and PR titles.\n- Features → `master`. Bug fixes → latest stable release branch (e.g., `release/2.5`). The \"Merge up\" GitHub Action propagates fixes to newer branches automatically.\n- Run `task` (default target) before every PR.\n- Changed public API (`mongo/`, `bson/`, `event/`, `tag/`)? Run `task api-report` and include the output in the PR description.\n- User-visible breaking change? Update `docs/migration-2.0.md`.\n- Spec compliance changes? Quote the relevant spec requirement in the PR description.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance to AI agents when working with code in this repository.\n\n## Project\n\nOfficial MongoDB Go Driver (`go.mongodb.org/mongo-driver/v2`). Correctness, backward compatibility, and conformance to [MongoDB Driver Specifications](https://github.com/mongodb/specifications) are top priorities.\n\n- Module: `go.mongodb.org/mongo-driver/v2`\n- Issue tracker: [JIRA GODRIVER project](https://jira.mongodb.org/browse/GODRIVER) — GitHub Issues is not used for bugs/features\n- Active major version: v2 on `master`. v1 lives on `release/1.x` branches.\n\n## Build, test, and lint\n\nUses **[Task](https://taskfile.dev/)**, not make.\n\n```\ntask                 # default: build + check-license + check-fmt + check-modules + lint + test-short\ntask fmt             # gofumpt -w . — use this, not plain gofmt\ntask build           # includes compilecheck-min (Go min-version compat)\ntask lint            # golangci-lint across linux/{386,arm,arm64,amd64,ppc64le,s390x}\ntask test-short      # race detector, ~60s timeout — fast feedback\ntask test            # full suite, serial (-p 1), 1800s timeout, requires mongod\ntask api-report      # required when public API changes — include output in PR description\n```\n\n**Tests require a running `mongod`** on `localhost:27017` (or `MONGODB_URI`). The full test suite is **serial** (`-p 1`) — integration tests share server state. Do not parallelize.\n\n## Go version requirements\n\n- **Go 1.25**: minimum to compile/use the driver. The Go Driver supports the last two Go minor versions. Public packages (`mongo/`, `bson/`, `event/`, `tag/`) must build on 1.25. `compilecheck-min` enforces this at build time.\n- **Go 1.26+**: required to run the test suite and develop the driver.\n\n## Gotchas\n\n1. **`x/` packages are importable but not semver-covered.** Users do import `x/mongo/driver` etc. Flag breaking changes explicitly in PR descriptions even though semver doesn't require it.\n1. **Atomic alignment on 32-bit.** `int64`/`uint64` fields accessed via `sync/atomic` must be at struct start or use `atomic.Int64`. The lint pass on `GOARCH=386` catches this — don't skip cross-arch lint.\n1. **GridFS lives in `mongo/`.** v2 merged `gridfs.Bucket` into `mongo.GridFSBucket`. Don't resurrect the old `gridfs` import path.\n1. **CSOT timeouts.** Use context deadlines; do not introduce per-call wall-clock timers that race with the user's context.\n1. **Command monitoring redacts credentials.** When adding commands that handle credentials (`authenticate`, `saslStart`, etc.), add them to the redaction list.\n1. **`libmongocrypt` required for CSFLE/QE tests.** Install with `task install-libmongocrypt`. CSFLE code requires the `cse` build tag.\n\n## Code conventions\n\n- **Formatter**: `gofumpt` (stricter superset of gofmt). Always use `task fmt`, never plain gofmt.\n- **Errors**: `fmt.Errorf(\"…: %w\", err)` for wrapping. Use `errors.Is`/`errors.As` for comparisons — never `strings.Contains` on error messages. Sentinel errors live in the `mongo` package (`mongo.ErrNoDocuments`, etc.).\n- **Context**: Every blocking public method takes `context.Context` as its first argument. Use `mongo.SessionFromContext(ctx)` (v2 pattern) — not the old `mongo.SessionContext`.\n- **BSON**: `bson.D` for ordered documents and commands. `bson.M` only when order genuinely doesn't matter. `bsoncore.Document` in hot paths (zero-copy, byte-slice-backed).\n- **Exported names**: Full words, not abbreviations (`ClientBulkWriteResult`, not `CBWResult`). Doc comments required on all exported identifiers using the \"name is subject\" convention.\n- **New options**: Follow the setter pattern: `func (o *XxxOptionsBuilder) SetFoo(v T) *XxxOptionsBuilder`.\n\n## Tests\n\n- Use `internal/assert` (wraps testify) for assertions. Prefer `assert.ErrorIs` over `assert.ErrorContains`.\n- Integration tests: use `internal/integration/mtest` for topology-aware setup, fail-point injection, and event capture.\n- Spec tests: JSON/YAML fixtures under `testdata/` (git submodule — run `task init-submodule` after cloning if missing).\n- Prose tests: number them to match the spec (e.g., `\"3. bulkWrite batch splits…\"`) for cross-referencing.\n- Unit tests live next to the code (`foo.go` ↔ `foo_test.go`). Integration tests live in `internal/integration/`.\n\n## PR and commit conventions\n\n- **JIRA prefix required**: `GODRIVER-1234 Short description` for all commit messages and PR titles.\n- Features → `master`. Bug fixes → latest stable release branch (e.g., `release/2.5`). The \"Merge up\" GitHub Action propagates fixes to newer branches automatically.\n- Run `task` (default target) before every PR.\n- Changed public API (`mongo/`, `bson/`, `event/`, `tag/`)? Run `task api-report` and include the output in the PR description.\n- User-visible breaking change? Update `docs/migration-2.0.md`.\n- Spec compliance changes? Quote the relevant spec requirement in the PR description.\n","category":"root","tokens":1222}]}