From 683dfa31d0621888cacb290a170bec1a99123275 Mon Sep 17 00:00:00 2001 From: Sophia Yang Date: Tue, 26 May 2026 17:04:37 -0400 Subject: [PATCH 1/5] agents.md --- .github/AGENTS.md | 54 +++++++++++++++++++++++++++++++++ .github/CLAUDE.md | 1 + .github/copilot-instructions.md | 44 --------------------------- 3 files changed, 55 insertions(+), 44 deletions(-) create mode 100644 .github/AGENTS.md create mode 100644 .github/CLAUDE.md delete mode 100644 .github/copilot-instructions.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 0000000000..2626e0cf76 --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,54 @@ +# AGENTS.md - PyMongo (mongo-python-driver) + +## Overview +Official Python driver for MongoDB. + +## Tech Stack +- **Build/env:** `hatch` — use `hatch run test:test` and `hatch run test:test-async`, not `pytest` directly +- **Task runner:** `just` (Justfile at repo root) +- **Linter/formatter:** `ruff` via pre-commit +- **Type checker:** `mypy` (strict) +- **Docs:** Sphinx / reStructuredText; use Sphinx docstring format for all docstrings + +> **Never** run `pip install bson`. PyMongo ships its own `bson`; the PyPI `bson` package silently breaks things. + +## Project Structure +- `pymongo/` — sync driver (MongoClient, Collection, Database, etc.) +- `pymongo/asynchronous/` — async API, mirrors `pymongo/` +- `bson/` — BSON implementation +- `gridfs/` — GridFS API +- `test/` — sync test suite +- `test/asynchronous/` — async test suite, mirrors `test/` +- `test/unified_format/` — cross-driver spec tests (Unified Test Format) +- `tools/convert_test_to_async.py` — generates async test stubs from sync tests + +## Commands +```bash +just install # set up venv + pre-commit hook +just typing-mypy # type check +just run lint-manual # ruff linter + +hatch run test:test # run sync tests +hatch run test:test-async # run async tests + +MONGODB_VERSION=8.0 just run-server # start a local MongoDB server +``` + +## Testing +Tests require a live MongoDB server (`just run-server` above). + +When modifying sync code, also update the async counterpart: +1. Make changes in `pymongo/` and `test/`. +2. Run `tools/convert_test_to_async.py` on the sync test file to generate a starting-point async version. +3. Manually complete the async version in `test/asynchronous/`. + +Do not edit files in `pymongo/synchronous/` or mirrored files in `test/` directly — they are auto-generated by `tools/synchro.py` from `pymongo/asynchronous/` and `test/asynchronous/`. Only edit them if the change includes a `_IS_SYNC` statement. + +Async functions must not call blocking I/O. + +New features need integration tests. Bug fixes need regression tests. + +## Commit and PR Conventions +- Prefix commits and PR titles with the JIRA ticket: `PYTHON-1234 Fix retryable write on mongos` +- Backport PRs: append the target branch in brackets — `PYTHON-1234 [v4.9] Fix retryable write` +- Merge via **Squash and Merge** only diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/.github/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index b67cb49aca..0000000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,44 +0,0 @@ -When reviewing code, focus on: - -## Security Critical Issues -- Check for hardcoded secrets, API keys, or credentials. -- Check for instances of potential method call injection, dynamic code execution, symbol injection or other code injection vulnerabilities. - -## Performance Red Flags -- Spot inefficient loops and algorithmic issues. -- Check for memory leaks and resource cleanup. - -## Code Quality Essentials -- Methods should be focused and appropriately sized. If a method is doing too much, suggest refactorings to split it up. -- Use clear, descriptive naming conventions. -- Avoid encapsulation violations and ensure proper separation of concerns. -- All public classes, modules, and methods should have clear documentation in Sphinx format. - -## PyMongo-specific Concerns -- Do not review files within `pymongo/synchronous` or files in `test/` that also have a file of the same name in `test/asynchronous` unless the reviewed changes include a `_IS_SYNC` statement. PyMongo generates these files from `pymongo/asynchronous` and `test/asynchronous` using `tools/synchro.py`. -- All asynchronous functions must not call any blocking I/O. - -## Review Style -- Be specific and actionable in feedback. -- Explain the "why" behind recommendations. -- Acknowledge good patterns when you see them. -- Ask clarifying questions when code intent is unclear. - -Always prioritize security vulnerabilities and performance issues that could impact users. - -Always suggest changes to improve readability and testability. For example, this suggestion seeks to make the code more readable, reusable, and testable: - -```python -# Instead of: -if user.email and "@" in user.email and len(user.email) > 5: - submit_button.enabled = True -else: - submit_button.enabled = False - -# Consider: -def valid_email(email): - return email and "@" in email and len(email) > 5 - - -submit_button.enabled = valid_email(user.email) -``` From 7fabff9dcb74281b7d8e45daef0cddb9ca5a6313 Mon Sep 17 00:00:00 2001 From: Sophia Yang Date: Wed, 27 May 2026 11:14:01 -0400 Subject: [PATCH 2/5] jib suggestions --- .github/AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/AGENTS.md b/.github/AGENTS.md index 2626e0cf76..1f27a80f71 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -13,8 +13,8 @@ Official Python driver for MongoDB. > **Never** run `pip install bson`. PyMongo ships its own `bson`; the PyPI `bson` package silently breaks things. ## Project Structure -- `pymongo/` — sync driver (MongoClient, Collection, Database, etc.) -- `pymongo/asynchronous/` — async API, mirrors `pymongo/` +- `pymongo/synchronous/` — sync driver (MongoClient, Collection, Database, etc.) generated from `pymongo/asynchronous/` using unasync +- `pymongo/asynchronous/` — async API, mirrors `pymongo/synchronous/` - `bson/` — BSON implementation - `gridfs/` — GridFS API - `test/` — sync test suite @@ -37,8 +37,8 @@ MONGODB_VERSION=8.0 just run-server # start a local MongoDB server ## Testing Tests require a live MongoDB server (`just run-server` above). -When modifying sync code, also update the async counterpart: -1. Make changes in `pymongo/` and `test/`. +Never modify pymongo/synchronous code first; update the async counterpart and run our `tools/synchro.py` script: +1. Make changes in `pymongo/asynchronous` or top-level `pymongo/` files and `test/`. 2. Run `tools/convert_test_to_async.py` on the sync test file to generate a starting-point async version. 3. Manually complete the async version in `test/asynchronous/`. From 3bb5f55aa6dfc13f4345d14e04dd715477e010ee Mon Sep 17 00:00:00 2001 From: Sophia Yang Date: Wed, 27 May 2026 14:55:36 -0400 Subject: [PATCH 3/5] add back copilot instructions --- .github/copilot-instructions.md | 44 +++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..b67cb49aca --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,44 @@ +When reviewing code, focus on: + +## Security Critical Issues +- Check for hardcoded secrets, API keys, or credentials. +- Check for instances of potential method call injection, dynamic code execution, symbol injection or other code injection vulnerabilities. + +## Performance Red Flags +- Spot inefficient loops and algorithmic issues. +- Check for memory leaks and resource cleanup. + +## Code Quality Essentials +- Methods should be focused and appropriately sized. If a method is doing too much, suggest refactorings to split it up. +- Use clear, descriptive naming conventions. +- Avoid encapsulation violations and ensure proper separation of concerns. +- All public classes, modules, and methods should have clear documentation in Sphinx format. + +## PyMongo-specific Concerns +- Do not review files within `pymongo/synchronous` or files in `test/` that also have a file of the same name in `test/asynchronous` unless the reviewed changes include a `_IS_SYNC` statement. PyMongo generates these files from `pymongo/asynchronous` and `test/asynchronous` using `tools/synchro.py`. +- All asynchronous functions must not call any blocking I/O. + +## Review Style +- Be specific and actionable in feedback. +- Explain the "why" behind recommendations. +- Acknowledge good patterns when you see them. +- Ask clarifying questions when code intent is unclear. + +Always prioritize security vulnerabilities and performance issues that could impact users. + +Always suggest changes to improve readability and testability. For example, this suggestion seeks to make the code more readable, reusable, and testable: + +```python +# Instead of: +if user.email and "@" in user.email and len(user.email) > 5: + submit_button.enabled = True +else: + submit_button.enabled = False + +# Consider: +def valid_email(email): + return email and "@" in email and len(email) > 5 + + +submit_button.enabled = valid_email(user.email) +``` From 5f62bfcaf2d0a136d35fe2981957b221c1d831bc Mon Sep 17 00:00:00 2001 From: Sophia Yang Date: Fri, 29 May 2026 10:35:37 -0400 Subject: [PATCH 4/5] place md at root --- .github/AGENTS.md => AGENTS.md | 2 ++ .github/CLAUDE.md => CLAUDE.md | 0 2 files changed, 2 insertions(+) rename .github/AGENTS.md => AGENTS.md (98%) rename .github/CLAUDE.md => CLAUDE.md (100%) diff --git a/.github/AGENTS.md b/AGENTS.md similarity index 98% rename from .github/AGENTS.md rename to AGENTS.md index 1f27a80f71..4837f645ac 100644 --- a/.github/AGENTS.md +++ b/AGENTS.md @@ -52,3 +52,5 @@ New features need integration tests. Bug fixes need regression tests. - Prefix commits and PR titles with the JIRA ticket: `PYTHON-1234 Fix retryable write on mongos` - Backport PRs: append the target branch in brackets — `PYTHON-1234 [v4.9] Fix retryable write` - Merge via **Squash and Merge** only + +See copilot-instructions.md for more details. diff --git a/.github/CLAUDE.md b/CLAUDE.md similarity index 100% rename from .github/CLAUDE.md rename to CLAUDE.md From 8ec60044737f609e5c013df1686e20f3fec78e09 Mon Sep 17 00:00:00 2001 From: Sophia Yang Date: Fri, 29 May 2026 11:49:13 -0400 Subject: [PATCH 5/5] Update AGENTS.md Co-authored-by: Jib --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4837f645ac..8417c2cd3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,4 +53,4 @@ New features need integration tests. Bug fixes need regression tests. - Backport PRs: append the target branch in brackets — `PYTHON-1234 [v4.9] Fix retryable write` - Merge via **Squash and Merge** only -See copilot-instructions.md for more details. +See .github/copilot-instructions.md for more details.