From 9f5e38d9eb72600f9d4bcd7dca1c782737144833 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Fri, 2 Oct 2026 10:35:11 -0400 Subject: [PATCH 01/12] DRIVERS-3667 Drivers specification standards --- CONTRIBUTING.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..72976f8393 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,105 @@ +# Specification standards + +This document describes the shared standards for all specifications contained within this repository. These standards +apply to all specification prose, pseudocode, tests, and comments, both human and machine-authored. Use these guidelines +both when writing and reviewing specification changes. + +This is a living document: when an issue or difference of opinion occurs several times across reviews, the final +resolution should be added as a new guideline here. + +## Style and formatting + +- All prose must use proper English grammar: write in complete sentences, start with a capital letter, use correct + punctuation, and end with a period. +- Avoid metaphors, similes, analogies, and other figurative language. +- Use numbered lists for enumerating steps in a process. +- Use bulleted lists for enumerating related but unordered lists of items. + +## Pseudocode + +- Consider adding pseudocode following a numbered list of MUST steps that defines an algorithm or system. +- Comments must follow the standards above for prose style. +- Use Python syntax for algorithms, Typescript syntax for BSON and wire documents, and plain text for systems. + +## Tests + +- Prefer unified tests over prose tests whenever possible. +- Specify all environmental and topological requirements for each test. +- Tests belong in a separate `tests/README.md` file within the specification directory, not in the specification itself. + +## Changelog + +- All changes require a changelog entry in the modified specification. +- Changelog entries are concise summaries of their described changes. +- Changelog entries are in reverse chronological order, with the latest change at the top. +- Each entry follows a standard format: `YYYY-MM-DD: Description.`, and is separated from its neighbors by a blank line. + +## Links + +- Cross-spec links use relative paths instead of absolute ones. +- Link to terms defined in another specification instead of re-defining. + +## Deprecation + +- Mark deprecated features as deprecated and remove them entirely from the specification once no driver + server pair + supports them. + +## Document Structure + +- All specifications must be written exclusively using the following required sections in the order they appear in: + +``` +## Abstract + +A brief description of the specification's intent and why it requires its own specification. + +## META + +The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +## Terms + +Definitions of all technical terms used in the specification. + +## Specification + +The bulk of the document. Contains all actual requirements and the use of keywords defined in the META section. + +## Implementation Notes + +Guidance for driver authors specific to actual implementation. This can include allowances for language differences, examples of non-obvious complexity in code, and the like. + +## Rationale + +Motivations for the design choices made in the specification. Answer the "why" of choices, not the "how". +If there are notable rejected designs, include brief explanations for their rejection in a "Rejected Alternatives" subsection. + +## Backwards Compatibility + +Implications of the specification for older driver and server versions that do not support its changes. + +## Reference Implementation + +The drivers responsible for producing the initial reference implementation of the specification. + +## Future Work + +Future additions to the specification that did not qualify for the initial version. + +## Questions and Answers + +Answers to questions that have or will frequently come up for driver authors working to implement or understand the specification. + +## Test Plan + +A link to the separate test document associated with the specification. + +## CHANGELOG + +A dated, bulleted list of changes made to the specification. +``` + +## LLM usage + +- All changes are owned by and are the responsibility of the author, regardless of how they were created. From 0411ae858b9ab8f93f4ac6aec4b1cc2a49b5d902 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 5 Oct 2026 09:49:52 -0400 Subject: [PATCH 02/12] Update CONTRIBUTING.md Co-authored-by: Matt Dale <9760375+matthewdale@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 72976f8393..54dc3db8e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,7 +95,7 @@ Answers to questions that have or will frequently come up for driver authors wor A link to the separate test document associated with the specification. -## CHANGELOG +## Changelog A dated, bulleted list of changes made to the specification. ``` From ec78c2e88c7904701b690d32d224821979f43754 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 5 Oct 2026 09:49:59 -0400 Subject: [PATCH 03/12] Update CONTRIBUTING.md Co-authored-by: Matt Dale <9760375+matthewdale@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54dc3db8e7..a400b5beb0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,7 +70,7 @@ The bulk of the document. Contains all actual requirements and the use of keywor Guidance for driver authors specific to actual implementation. This can include allowances for language differences, examples of non-obvious complexity in code, and the like. -## Rationale +## Design Rationale Motivations for the design choices made in the specification. Answer the "why" of choices, not the "how". If there are notable rejected designs, include brief explanations for their rejection in a "Rejected Alternatives" subsection. From d84293ce59f218d99003dc443835034ce8f57fab Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 5 Oct 2026 10:39:46 -0400 Subject: [PATCH 04/12] MD + JY review --- CONTRIBUTING.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a400b5beb0..324749ead7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,22 +10,31 @@ resolution should be added as a new guideline here. ## Style and formatting - All prose must use proper English grammar: write in complete sentences, start with a capital letter, use correct - punctuation, and end with a period. + punctuation, and end with a period. [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) terms defined in a + specification's `META` section are exempt. - Avoid metaphors, similes, analogies, and other figurative language. - Use numbered lists for enumerating steps in a process. - Use bulleted lists for enumerating related but unordered lists of items. ## Pseudocode -- Consider adding pseudocode following a numbered list of MUST steps that defines an algorithm or system. +- Consider adding pseudocode following a numbered list of MUST steps that defines an algorithm or a description of a + schema. - Comments must follow the standards above for prose style. -- Use Python syntax for algorithms, Typescript syntax for BSON and wire documents, and plain text for systems. +- Use Python syntax for algorithms and Typescript syntax for BSON and wire documents. +- Pseudocode is purely explanatory, not normative. It cannot substitute for a prose description of a required behavior. ## Tests -- Prefer unified tests over prose tests whenever possible. +- Tests are required for every behavior required in the specification. +- Prefer unified tests over prose tests whenever possible, and prefer unified tests over new test formats. Prefer + expanding unified test capabilities over prose tests where expansion would permit the testing of new behaviors. - Specify all environmental and topological requirements for each test. -- Tests belong in a separate `tests/README.md` file within the specification directory, not in the specification itself. +- Do not assume a specific driver architecture when creating tests unless that architecture is explicitly required by + the specification. +- Tests belong in a separate `tests/` directory within specification directory, not in the specification itself. + - Prose tests belong in a `tests/README.md` file. + - Unified tests belong in a `tests/unified` subdirectory. ## Changelog @@ -46,7 +55,8 @@ resolution should be added as a new guideline here. ## Document Structure -- All specifications must be written exclusively using the following required sections in the order they appear in: +- Specifications must use the following sections, in this order, when present. Abstract, META, Specification, and + Changelog are required. ``` ## Abstract From fddafe4dc89195d9be4ba99d0c5b0f13d6166448 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 5 Oct 2026 15:30:46 -0400 Subject: [PATCH 05/12] DP review --- CONTRIBUTING.md | 60 ++++++++++++++++++++++++++----------------------- 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 324749ead7..642b546064 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,57 +5,61 @@ apply to all specification prose, pseudocode, tests, and comments, both human an both when writing and reviewing specification changes. This is a living document: when an issue or difference of opinion occurs several times across reviews, the final -resolution should be added as a new guideline here. +resolution SHOULD be added as a new guideline here. ## Style and formatting -- All prose must use proper English grammar: write in complete sentences, start with a capital letter, use correct +- All prose MUST use proper English grammar: write in complete sentences, start with a capital letter, use correct punctuation, and end with a period. [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) terms defined in a specification's `META` section are exempt. -- Avoid metaphors, similes, analogies, and other figurative language. -- Use numbered lists for enumerating steps in a process. -- Use bulleted lists for enumerating related but unordered lists of items. +- Authors MUST avoid metaphors, similes, analogies, and other figurative language. +- Authors MUST use numbered lists for enumerating steps in a process. +- Authors MUST use bulleted lists for enumerating related but unordered lists of items. ## Pseudocode -- Consider adding pseudocode following a numbered list of MUST steps that defines an algorithm or a description of a +- Authors SHOULD add pseudocode following a numbered list of MUST steps that defines an algorithm or a description of a schema. -- Comments must follow the standards above for prose style. -- Use Python syntax for algorithms and Typescript syntax for BSON and wire documents. -- Pseudocode is purely explanatory, not normative. It cannot substitute for a prose description of a required behavior. +- Comments MUST follow the standards above for prose style. +- Authors MUST use Python syntax for algorithms and Typescript syntax for BSON and wire documents. +- Pseudocode MUST be purely explanatory, not normative. It cannot substitute for a prose description of a required + behavior. ## Tests -- Tests are required for every behavior required in the specification. -- Prefer unified tests over prose tests whenever possible, and prefer unified tests over new test formats. Prefer - expanding unified test capabilities over prose tests where expansion would permit the testing of new behaviors. -- Specify all environmental and topological requirements for each test. -- Do not assume a specific driver architecture when creating tests unless that architecture is explicitly required by - the specification. -- Tests belong in a separate `tests/` directory within specification directory, not in the specification itself. - - Prose tests belong in a `tests/README.md` file. - - Unified tests belong in a `tests/unified` subdirectory. +- Tests MUST cover every behavior required in the specification. +- Authors SHOULD use unified tests over prose tests whenever possible. + - Authors SHOULD prefer unified tests over new test formats. + - Authors SHOULD expand unified test capabilities over prose tests where expansion would permit the testing of new + behaviors. +- Authors MUST specify all environmental and topological requirements for each test. +- Authors MUST NOT assume a specific driver architecture when creating tests unless that architecture is explicitly + required by the specification. +- Tests MUST be in a separate `tests/` directory within specification directory, not in the specification itself. + - Prose tests MUST be in a `tests/README.md` file. + - Unified tests MUST be in a `tests/unified` subdirectory. ## Changelog -- All changes require a changelog entry in the modified specification. -- Changelog entries are concise summaries of their described changes. -- Changelog entries are in reverse chronological order, with the latest change at the top. -- Each entry follows a standard format: `YYYY-MM-DD: Description.`, and is separated from its neighbors by a blank line. +- All changes MUST have a changelog entry in the modified specification. +- Changelog entries MUST be concise summaries of their described changes. +- Changelog entries MUST be in reverse chronological order, with the latest change at the top. +- Each entry MUST follow a standard format: `YYYY-MM-DD: Description.`, and MUST be separated from its neighbors by a + blank line. ## Links -- Cross-spec links use relative paths instead of absolute ones. -- Link to terms defined in another specification instead of re-defining. +- Cross-spec links MUST use relative paths instead of absolute ones. +- Terms defined in another specification MUST be linked instead of re-defining. ## Deprecation -- Mark deprecated features as deprecated and remove them entirely from the specification once no driver + server pair - supports them. +- Deprecated features MUST be marked as deprecated and removed entirely from the specification once no driver + server + pair supports them. ## Document Structure -- Specifications must use the following sections, in this order, when present. Abstract, META, Specification, and +- Specifications MUST use the following sections, in this order, when present. Abstract, META, Specification, and Changelog are required. ``` @@ -112,4 +116,4 @@ A dated, bulleted list of changes made to the specification. ## LLM usage -- All changes are owned by and are the responsibility of the author, regardless of how they were created. +- Authors MUST be responsible for and own all changes made under their name, regardless of how they were created. From d067f742a7aa30bb70ed3509e11f5b59a066b7d8 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Tue, 6 Oct 2026 11:44:08 -0400 Subject: [PATCH 06/12] Add RFC 2119 section --- CONTRIBUTING.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 642b546064..dba5e8d0ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,12 @@ resolution SHOULD be added as a new guideline here. - Authors MUST use numbered lists for enumerating steps in a process. - Authors MUST use bulleted lists for enumerating related but unordered lists of items. +## RFC 2119 keywords + +- Authors MUST use "MUST" wherever alignment of drivers across languages is required. +- Authors MUST use "SHOULD" only when valid exceptions to a requirement exist and can be documented. +- When in doubt, authors MUST use "MUST" instead of "SHOULD". + ## Pseudocode - Authors SHOULD add pseudocode following a numbered list of MUST steps that defines an algorithm or a description of a From 2a6792fc25903028bf0889ae6f7476be7d1ac8b8 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Tue, 6 Oct 2026 15:52:28 -0400 Subject: [PATCH 07/12] OP + JY review --- AGENTS.md | 93 +------------------------------------------------ CONTRIBUTING.md | 41 ++++++++++++++++++++-- README.md | 60 ++++++++----------------------- 3 files changed, 55 insertions(+), 139 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f9d9e944e6..9a73ce7d1a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,7 +34,7 @@ files. ```bash npm install -g js-yaml # Required once -make -C source # Convert all YAML test files to JSON +make -C source # Convert most YAML test files to JSON ``` ### Schema Latest Update (after adding a new unified test format schema version) @@ -43,91 +43,22 @@ make -C source # Convert all YAML test files to JSON make update-schema-latest -C source ``` -### Test Generation Scripts - -Some specs include Python scripts that generate test files. These often live alongside their respective specs rather -than in a single directory. Examples: - -```bash -python source/server-discovery-and-monitoring/tests/errors/generate-error-tests.py # SDAM error tests -python source/client-side-encryption/etc/generate-corpus.py # Client-side encryption corpus tests -python source/etc/generate-handshakeError-tests.py # Handshake error tests -``` - -A general pattern: look for `generate-*.py` scripts in a spec's `etc/` or `tests/` subdirectory. - ## Architecture -### Specification Documents (`source/`) - -Each subdirectory under `source/` is a specification area (e.g., `crud/`, `transactions/`, `auth/`). Specs are written -in GitHub Flavored Markdown at 120-character line width, following the -[MongoDB Documentation Style Guidelines](https://www.mongodb.com/docs/meta/style-guide/). Each spec typically contains: - -- `*.md` — the specification itself, with a `## Changelog` section at the bottom -- `tests/` — YAML test files (human-editable) and auto-generated JSON (never edit manually) - -### Changelog Format - -Each spec file contains its own `## Changelog` section (not a separate file). Entries are dated and prepended at the -top: - -```markdown -## Changelog - -- 2026-05-13: Describe the change made. - -- 2024-03-01: Previous change. -``` - ### Unified Test Format The unified test format (`source/unified-test-format/`) defines a YAML/JSON schema for cross-driver tests. Key rules: -- **Always use the lowest possible schema version** that satisfies a test's requirements — do not default to the latest -- YAML files are the source of truth; JSON files are auto-generated and committed - Schema versions live in `source/unified-test-format/schema-*.json`; `schema-latest.json` must match the highest version (run `make update-schema-latest -C source` to update it) - CI validates test files against the declared schema version using `ajv-cli`. Using any fields from a newer schema version than declared will fail validation. -### Test File Conventions - -- YAML test files are human-editable and located in `tests/` subdirectories -- JSON files are generated automatically by CI from YAML — never edit `.json` test files manually -- Use `runOnRequirements` to restrict tests to specific server versions/topologies -- Topologies to consider: standalone, replica set, sharded cluster, load balanced - ### Documentation Build (`mkdocs.yml`) MkDocs with `pymdown-extensions` and `mkdocs-github-admonitions-plugin`. The navigation is largely auto-generated via `scripts/generate_index.py`. The build must pass in `--strict` mode (no warnings). -## Test Authoring Rules - -### Immutability of Existing Tests - -**Do not modify existing tests** unless they are testing incorrect behavior. Default to creating new tests or new test -files instead of altering existing ones. - -- Test files can only be deleted once **no driver runs them anymore**. -- For spec changes that remove functionality: use `runOnRequirements` (unified tests) or have drivers skip the test - (non-unified tests like SDAM). -- Outdated prose tests must not be removed — mark them as such (e.g., strikethrough or *Removed*). -- Retiring an EOL server version (removing now-dead version-gated tests, prose, and pseudocode after the minimum - supported server version is raised) is a repo-wide sweep with many non-obvious traps. Use the - `retiring-server-versions` skill for the full checklist before starting one. - -### Prose Test Numbering - -Always use relative numbered bullets (`1.`) for prose tests. **New tests must be appended at the end** of the list, -since drivers may reference existing tests by number. - -### Test Isolation - -Only test functionality directly related to the new spec requirements. Omit irrelevant fields in command expectations. -This makes tests more resilient against future spec updates. - ## Linting & Formatting | Tool | Purpose | @@ -138,25 +69,3 @@ This makes tests more resilient against future spec updates. | `shellcheck` | Shell script linting | All checks run via `pre-commit`. CI enforces them in `.github/workflows/lint.yml`. - -## PR Requirements - -Per the PR template and project workflow: - -- Title must include a DRIVERS ticket (e.g., `DRIVERS-1234`) -- Update the `## Changelog` section in each modified spec file -- Test changes in at least one language driver -- Include links to the driver implementation PRs in the PR description (e.g., - `Python implementation: https://github.com/mongodb/mongo-python-driver/pull/…`) -- Tests must pass against all supported server versions and topologies - -## Specification Writing Guidelines - -From `source/driver-mantras.md`: - -- Prefer **MUST** over **SHOULD** — wishy-washy specs produce incompatible drivers -- Be topology-agnostic wherever possible -- Minimize configuration options ("No Knobs" principle) -- Check wire protocol version, not server version -- Follow semantic versioning for behavior changes -- Design for the next release, not hypothetical future ones ("Defy augury") diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dba5e8d0ad..b4db871b31 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,10 @@ both when writing and reviewing specification changes. This is a living document: when an issue or difference of opinion occurs several times across reviews, the final resolution SHOULD be added as a new guideline here. +## Repository structure + +- All specifications MUST go in the `source/` directory under their own subdirectory (e.g `source/auth/`). + ## Style and formatting - All prose MUST use proper English grammar: write in complete sentences, start with a capital letter, use correct @@ -15,12 +19,18 @@ resolution SHOULD be added as a new guideline here. - Authors MUST avoid metaphors, similes, analogies, and other figurative language. - Authors MUST use numbered lists for enumerating steps in a process. - Authors MUST use bulleted lists for enumerating related but unordered lists of items. +- All specifications MUST use [GitHub Flavored Markdown](https://github.github.com/gfm/) and follow the + [MongoDB Documentation Style Guidelines](https://www.mongodb.com/docs/meta/style-guide/) with a 120-line character + limit. +- Authors MUST abide by the automated linters described in [README.md](./README.md). ## RFC 2119 keywords - Authors MUST use "MUST" wherever alignment of drivers across languages is required. - Authors MUST use "SHOULD" only when valid exceptions to a requirement exist and can be documented. - When in doubt, authors MUST use "MUST" instead of "SHOULD". +- Authors MUST follow [RFC 8174](https://www.rfc-editor.org/info/rfc8174/) and use all-caps when invoking RFC 2119 + keywords. ## Pseudocode @@ -34,16 +44,33 @@ resolution SHOULD be added as a new guideline here. ## Tests - Tests MUST cover every behavior required in the specification. +- Tests MUST only verify functionality directly related to their specification. Omit irrelevant fields in expected + output. - Authors SHOULD use unified tests over prose tests whenever possible. - Authors SHOULD prefer unified tests over new test formats. - Authors SHOULD expand unified test capabilities over prose tests where expansion would permit the testing of new behaviors. +- Authors MUST number prose tests starting with `1.`. +- Authors MUST add new tests to the end of list of prose tests. +- Authors MUST not modify existing tests unless to fix correctness issues. Create new tests instead of modifying + existing ones. - Authors MUST specify all environmental and topological requirements for each test. - Authors MUST NOT assume a specific driver architecture when creating tests unless that architecture is explicitly required by the specification. - Tests MUST be in a separate `tests/` directory within specification directory, not in the specification itself. - Prose tests MUST be in a `tests/README.md` file. - Unified tests MUST be in a `tests/unified` subdirectory. +- Authors MUST not remove deprecated prose tests, but instead strike through their content or otherwise explicitly mark + them as such. +- Authors MUST use `runOnRequirements` (for unified tests) or instructions on skipping (for other tests) to ensure tests + are only executed when supported. +- Tests not run by any driver MUST be deleted. +- Unified tests MUST use the lowest possible schema version that satisfies their requirements. +- Tests MUST verify or explicitly exclude behavior for all four supported topologies: standalone, replica set, sharded + cluster, and load balanced. +- Authors MUST make manual changes to `.yml` test files and then generate the `.json` versions using + [these instructions](./README.md#converting-to-json). +- Authors MUST NOT make manual changes to `.json` test files. ## Changelog @@ -60,8 +87,10 @@ resolution SHOULD be added as a new guideline here. ## Deprecation -- Deprecated features MUST be marked as deprecated and removed entirely from the specification once no driver + server +- Deprecated features MUST be marked as deprecated and removed entirely from the specification once no driver and server pair supports them. +- When retiring an EOL server version, authors MUST remove all version-gated tests, prose, and pseudocode specific to + the EOL version. Use the `retiring-server-versions` skill as a starting point. ## Document Structure @@ -122,4 +151,12 @@ A dated, bulleted list of changes made to the specification. ## LLM usage -- Authors MUST be responsible for and own all changes made under their name, regardless of how they were created. +- Authors MUST take responsibility for and own all changes made under their name, regardless of how they were created. + +## PR Requirements + +- PR titles MUST include a DRIVERS ticket (e.g., `DRIVERS-1234`). +- Authors MUST test changes in at least one language driver. +- Authors MUST include links to the driver implementation PRs in the PR description (e.g., + `Python implementation: https://github.com/mongodb/mongo-python-driver/pull/…`). +- Tests MUST pass against all supported server versions and topologies. diff --git a/README.md b/README.md index a355b3ce52..1418571b2d 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,13 @@ This repository holds in progress and completed specification for features of MongoDB, Drivers, and associated products. Also contained is a rudimentary system for producing these documents. -## Driver Mantras - -See [Documentation](./source/driver-mantras.md). +## Contributing -## Writing Documents +See [CONTRIBUTING.md](./CONTRIBUTING.md). -Write documents using [GitHub Flavored Markdown](https://github.github.com/gfm/), following the -[MongoDB Documentation Style Guidelines](https://www.mongodb.com/docs/meta/style-guide/). +## Driver Mantras -Store all source documents in the `source/` directory. +See [Documentation](./source/driver-mantras.md). ## Linting @@ -36,43 +33,6 @@ To run a manual hook like `shellcheck` manually, run: pre-commit run --all-files --hook-stage manual shellcheck ``` -## Prose Test Numbering - -When numbering prose tests, always use relative numbered bullets (`1.`). New tests must be appended at the end of the -test list, since drivers may refer to existing tests by number. - -Outdated tests must not be removed completely, but may be marked as such (e.g. by striking through or replacing the -entire test with a note (e.g. *Removed*). - -## Automated Test Best Practices - -### Immutability of Existing Tests - -**Do not modify existing tests**, unless they are testing incorrect behavior. Default to creating new tests or test -files instead of altering existing ones. - -Test files can only be deleted once no driver runs them anymore. In the meantime, for cases where a spec change removes -functionality: - -- **Unified Tests:** Use `runOnRequirements` to ensure tests are only executed by drivers supporting the required - functionality. -- **Non-Unified Tests (e.g., SDAM):** Drivers should skip tests that no longer apply to them. - -### Test Isolation - -When creating a new test, only test functionality directly related to the new spec requirements. Omit irrelevant fields -in command expectations. - -This makes tests more resilient against spec updates and avoids needing to change tests down the line. - -### Schema Version Usage - -Use the **lowest possible schema version** for each test. - -Do NOT default to using the latest unified test format schema version, as the drivers may not all implement it. Use the -oldest schema version that supports all functionality used in the test, even if it requires creating a new test file -with a lower schema version. - ## Building Documents We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, in a @@ -94,7 +54,17 @@ using `yaml2json` anymore, but instead the [js-yaml](https://www.npmjs.com/packa converter, so that JSON is formatted consistently. Run `npm install -g js-yaml`, then run `make` in the `source` directory at the top level of this repository to convert -all YAML test files to JSON. +most YAML test files to JSON. + +Some specs include Python scripts that generate test files. These often live alongside their respective specs: + +```bash +python source/server-discovery-and-monitoring/tests/errors/generate-error-tests.py # SDAM error tests +python source/client-side-encryption/etc/generate-corpus.py # Client-side encryption corpus tests +python source/etc/generate-handshakeError-tests.py # Handshake error tests +``` + +In general, these follow the `generate-*.py` naming convention in a spec's `etc/` or `tests/` subdirectory. ## Licensing From b0d796f6136f08f43477c6798250a011ff324c27 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 7 Oct 2026 09:57:15 -0400 Subject: [PATCH 08/12] Update CONTRIBUTING.md Co-authored-by: Preston Vasquez --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4db871b31..4d3ab8d943 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,7 +70,7 @@ resolution SHOULD be added as a new guideline here. cluster, and load balanced. - Authors MUST make manual changes to `.yml` test files and then generate the `.json` versions using [these instructions](./README.md#converting-to-json). -- Authors MUST NOT make manual changes to `.json` test files. +- Authors MUST NOT make manual changes to `.json` test files generated from a `.yml` source. ## Changelog From 309e1f6167cd71778fe75bf874d52d7d301d5ab6 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 7 Oct 2026 09:57:25 -0400 Subject: [PATCH 09/12] Update CONTRIBUTING.md Co-authored-by: Preston Vasquez --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d3ab8d943..6edf183746 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,7 @@ resolution SHOULD be added as a new guideline here. behaviors. - Authors MUST number prose tests starting with `1.`. - Authors MUST add new tests to the end of list of prose tests. -- Authors MUST not modify existing tests unless to fix correctness issues. Create new tests instead of modifying +- Authors MUST NOT modify existing tests unless to fix correctness issues. Create new tests instead of modifying existing ones. - Authors MUST specify all environmental and topological requirements for each test. - Authors MUST NOT assume a specific driver architecture when creating tests unless that architecture is explicitly From 56d91d0ef62f756eed194db6de22ab8b6e2aae5f Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 7 Oct 2026 09:57:34 -0400 Subject: [PATCH 10/12] Update CONTRIBUTING.md Co-authored-by: Preston Vasquez --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6edf183746..32254fefb6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,7 +60,7 @@ resolution SHOULD be added as a new guideline here. - Tests MUST be in a separate `tests/` directory within specification directory, not in the specification itself. - Prose tests MUST be in a `tests/README.md` file. - Unified tests MUST be in a `tests/unified` subdirectory. -- Authors MUST not remove deprecated prose tests, but instead strike through their content or otherwise explicitly mark +- Authors MUST NOT remove deprecated prose tests, but instead strike through their content or otherwise explicitly mark them as such. - Authors MUST use `runOnRequirements` (for unified tests) or instructions on skipping (for other tests) to ensure tests are only executed when supported. From 0d7d1c8024f6b8d2359854d690a385da02fdc38d Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 7 Oct 2026 10:14:17 -0400 Subject: [PATCH 11/12] PV review --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32254fefb6..cccf9b2d1c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,11 +60,10 @@ resolution SHOULD be added as a new guideline here. - Tests MUST be in a separate `tests/` directory within specification directory, not in the specification itself. - Prose tests MUST be in a `tests/README.md` file. - Unified tests MUST be in a `tests/unified` subdirectory. -- Authors MUST NOT remove deprecated prose tests, but instead strike through their content or otherwise explicitly mark - them as such. - Authors MUST use `runOnRequirements` (for unified tests) or instructions on skipping (for other tests) to ensure tests are only executed when supported. - Tests not run by any driver MUST be deleted. +- Authors MUST re-number existing prose tests to prevent numbering gaps when deleting unused prose tests. - Unified tests MUST use the lowest possible schema version that satisfies their requirements. - Tests MUST verify or explicitly exclude behavior for all four supported topologies: standalone, replica set, sharded cluster, and load balanced. @@ -156,7 +155,8 @@ A dated, bulleted list of changes made to the specification. ## PR Requirements - PR titles MUST include a DRIVERS ticket (e.g., `DRIVERS-1234`). -- Authors MUST test changes in at least one language driver. -- Authors MUST include links to the driver implementation PRs in the PR description (e.g., - `Python implementation: https://github.com/mongodb/mongo-python-driver/pull/…`). -- Tests MUST pass against all supported server versions and topologies. +- PRs that modify driver or test behavior MUST also fulfill these requirements: + - Authors MUST test changes in at least one language driver. + - Authors MUST include links to the driver implementation PRs in the PR description (e.g., + `Python implementation: https://github.com/mongodb/mongo-python-driver/pull/…`). + - Tests MUST pass against all supported server versions and topologies. From 0942176c5183becef334224c8b3099b71574ad13 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 7 Oct 2026 11:52:30 -0400 Subject: [PATCH 12/12] Update CONTRIBUTING.md Co-authored-by: Jeff Yemin --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cccf9b2d1c..2de886778a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,7 +150,7 @@ A dated, bulleted list of changes made to the specification. ## LLM usage -- Authors MUST take responsibility for and own all changes made under their name, regardless of how they were created. +- Authors MUST take responsibility for all changes made under their name, regardless of how they were created. ## PR Requirements