DRIVERS-3667 Drivers specification standards by NoahStapp · Pull Request #1992 · mongodb/specifications

NoahStapp · 2026-10-02T14:35:48Z

Please complete the following before merging:

Is the relevant DRIVERS ticket in the PR title?

~~[ ] Update changelog.~~
~~[ ] Test changes in at least one language driver.~~
[ ] Test these changes against all server versions and topologies (including standalone, replica set, and sharded
clusters).

matthewdale · 2026-10-05T07:58:41Z

+
+## Document Structure
+
+- All specifications must be written exclusively using the following required sections in the order they appear in:


This seems overly prescriptive. We should suggest but not require all sections. We should require the order is the same, and require a subset of sections.

For example:

Specifications must use the following sections, in this order, when present. Abstract, META, Specification, and Changelog are required.

Fair enough, no use in having empty sections just to fit a structure.

matthewdale · 2026-10-05T08:05:56Z

+
+## Style and formatting
+
+- All prose must use proper English grammar: write in complete sentences, start with a capital letter, use correct


Do we intend to follow RFC 2119 in the contributing guidelines? If not, it's worth calling out that this document does not follow RFC 2119, since drivers devs are used to reading spec documents with "MUST".

You mean that we should explicitly call out that RFC 2119 keywords are exempt from this rule?

Re-reading I see what you mean. I would prefer to not use RFC 2119 here since all of these rules are effectively MUST.

I don't think that's true: re all rules being effectively "MUST" - there is a mix of requirements and "soft" recommendations, e.g. "consider", "prefer".

Moreover, the current list of bullet points mixes directives with statements. Using "MUST" in a lot of places might feel like too loud, but I think it would make this easier to read and follow (i.e., harder to misinterpret intent or argue down the line about whether something is a soft guideline vs a hard requirement). It would also make the standards page more cohesive with the specs themselves.

Fair enough. I read all of them as having an implicit "MUST" (e.x. "MUST consider..."), but that's less explicit than actually having the words there.

Co-authored-by: Matt Dale <9760375+matthewdale@users.noreply.github.com>

jyemin · 2026-10-02T18:15:30Z

+
+- 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.


Consider expanding this, something like:

Add tests to a tests directory
** Add prose tests to a README.md file in the tests directory
** Add unified tests to a unified directory in the tests directory

prestonvasquez · 2026-10-06T17:02:08Z

+- 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.
+- Authors MUST use Python syntax for algorithms and Typescript syntax for BSON and wire documents.


[question] What is the historical reasoning for Javascript / Typescript pseudocode? These seem to be the widely used language for algorithms in the specifications.

Do we anticipate that this rule is forward-only, or does it mean we plan to convert the existing algorithm blocks? If we plan to convert, we should create a ticket and link it here as a future effort.

Edit: python syntax is the most common for algorithms if you don't count BSON / mongosh.

I assume because they have minimal syntax overhead and are widely readable regardless of language knowledge, but @jyemin might have a more historical answer.

We do plan to convert the existing blocks. I'll create a ticket to track that work. I'm not sure we need to link it in this document since it doesn't relate for future specification work.

I assume because they have minimal syntax overhead and are widely readable regardless of language knowledge

What does python syntax improve on this?

I'm not sure we need to link it in this document since it doesn't relate for future specification work.

If we plan to convert the existing blocks, that conversion is a consequence of this rule so it does relate to this document. Unless we decided to make this forward-only. Either works for me, but I'd like the document to say which, since future PRs against existing non-python syntax will have to guess. e.g. "if the spec PR modifies a few lines of an existing JS algorithm, is the author expected to convert the entire block?"

There is precedent to linking driver tickets for future work in specifications, https://github.com/search?q=repo%3Amongodb%2Fspecifications+DRIVERS-&type=code

What does python syntax improve on this?

I don't understand the question. Python is as close as languages get to being English text with some syntax, making it very easy to read psuedocode.

If we plan to convert the existing blocks, that conversion is a consequence of this rule so it does relate to this document. Unless we decided to make this forward-only. Either works for me, but I'd like the document to say which, since future PRs against existing non-python syntax will have to guess. e.g. "if the spec PR modifiees a few lines of an existing JS algorithm, is the author expected to convert the entire block?"

There is precedence to linking driver tickets for future work in specifications, https://github.com/search?q=repo%3Amongodb%2Fspecifications+DRIVERS-&type=code

We'll have a single PR to update all of the existing psuedocode to these standards so authors won't have to determine that. I'd prefer to keep transient references like tickets out of a standards document.

Suggest deferring the pseudocode decision to the DRIVERS ticket so that the style guide and existing specs change together.

sanych-sun

Should we mention that each change MUST have related Drivers ticket?

sanych-sun · 2026-10-06T18:28:09Z

+
+## Style and formatting
+
+- All prose MUST use proper English grammar: write in complete sentences, start with a capital letter, use correct


Should we mention md format is required for all specs?

sanych-sun · 2026-10-06T18:31:40Z

@@ -0,0 +1,125 @@
+# Specification standards


Should we add link to the CONTRIBUTING.md from the README.md, and probably move some content from README into this document? For example: "Writing Documents", "Prose Test Numbering", "Automated Test Best Practices" sections sounds like they are belong to the CONTRIBUTING.md too.

jyemin

A few other things to consider before merging:

RFT 8174 clarifies usage of all-caps MUST, SHOULD etc. Consider referencing it
The AGENTS.md file has several recommendations that more properly belong here, e.g. 120-char GFM line width, never hand-edit generated JSON/YAML is source of truth, always use the lowest schema version that works, prose tests use relative 1. numbering and new tests append at the end (drivers reference by number), test isolation (omit irrelevant fields), don't modify existing tests unless they test wrong behavior, PR requirements (DRIVERS ticket, driver implementation PR links in description).
Mention the automated enforcement layer in .pre-commit-config.yaml and .github/workflows/lint.yml

NoahStapp · 2026-10-06T19:53:06Z

A few other things to consider before merging:

1. [RFT 8174](https://www.rfc-editor.org/info/rfc8174/) clarifies usage of all-caps MUST, SHOULD etc.  Consider referencing it

2. The AGENTS.md file has several recommendations that more properly belong here, e.g. 120-char GFM line width, never hand-edit generated JSON/YAML is source of truth, always use the lowest schema version that works, prose tests use relative 1. numbering and new tests append at the end (drivers reference by number), test isolation (omit irrelevant fields), don't modify existing tests unless they test wrong behavior, PR requirements (DRIVERS ticket, driver implementation PR links in description).

3. Mention the automated enforcement layer in `.pre-commit-config.yaml` and `.github/workflows/lint.yml`

I've moved all content that fits from README.md and AGENTS.md into CONTRIBUTING.md.

prestonvasquez · 2026-10-06T21:20:22Z

+    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.


[question] Is this intended for all tests or just unified tests? If prose tests are included, then we should define some mechanism to make it not conflict with L63. E.g. "Since drivers reference prose tests by number, once a prose test has been removed by all drivers then its contents MAY be replaced with a note such as Removed."

prestonvasquez · 2026-10-06T21:28:49Z

+    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.


[blocking] Not all files have a yaml source, e.g. bson-corpus/tests.

Suggested change

- 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.

prestonvasquez · 2026-10-06T21:30:15Z

+        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


Suggested change

- 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

prestonvasquez · 2026-10-06T21:30:24Z

+- 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


Suggested change

- 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

prestonvasquez · 2026-10-06T21:34:57Z

+- Pseudocode MUST be purely explanatory, not normative. It cannot substitute for a prose description of a required
+    behavior.
+
+## Tests


[question] What do you think about adding labels to the test standards to make them referenceable, similar to prose tests?

- **T1.** Tests MUST cover every behavior required in the specification.

prestonvasquez · 2026-10-06T21:41:28Z

@@ -0,0 +1,162 @@
+# Specification standards


Suggest we note somewhere that specifications are self-defining: "A specification is a document under source/ whose header block includes a Status line". That way we can still have markdown files (or whatever) in source without it falling under the requirements of this standard.

prestonvasquez · 2026-10-06T21:47:38Z

+- 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/…`).


[blocking] These requirements can't be satisfied by editorial PRs (such as this one). Suggest that we state that somewhere: e.g., "PRs that do not change driver behavior or tests, such as editorial changes, are exempt from the driver requirements above."

Or if this change is accepted: https://github.com/mongodb/specifications/pull/1992/changes#r4200664929, something like: "PRs that do not change driver behavior or tests, such as editorial changes, are exempt from the driver requirements PR2 and PR3."

DRIVERS-3667 Drivers specification standards

9f5e38d

NoahStapp requested a review from a team as a code owner October 2, 2026 14:35

NoahStapp requested review from dariakp, jyemin, matthewdale, prestonvasquez, sanych-sun and vbabanin October 2, 2026 14:36

matthewdale reviewed Oct 5, 2026

View reviewed changes

NoahStapp and others added 2 commits October 5, 2026 09:49

Update CONTRIBUTING.md

0411ae8

Co-authored-by: Matt Dale <9760375+matthewdale@users.noreply.github.com>

Update CONTRIBUTING.md

ec78c2e

Co-authored-by: Matt Dale <9760375+matthewdale@users.noreply.github.com>

jyemin requested changes Oct 5, 2026

View reviewed changes

MD + JY review

d84293c

NoahStapp requested review from jyemin and matthewdale October 5, 2026 14:40

NoahStapp added 2 commits October 5, 2026 15:30

DP review

fddafe4

Add RFC 2119 section

d067f74

prestonvasquez approved these changes Oct 6, 2026

View reviewed changes

sanych-sun reviewed Oct 6, 2026

View reviewed changes

jyemin requested changes Oct 6, 2026

View reviewed changes

OP + JY review

2a6792f

NoahStapp requested review from jyemin and sanych-sun October 6, 2026 19:53

prestonvasquez self-requested a review October 6, 2026 21:09

prestonvasquez requested changes Oct 6, 2026

View reviewed changes


		## Document Structure

		- All specifications must be written exclusively using the following required sections in the order they appear in:


		## Style and formatting

		- All prose must use proper English grammar: write in complete sentences, start with a capital letter, use correct

	- 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.

	- 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

	- 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

Conversation

NoahStapp commented Oct 2, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

prestonvasquez Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sanych-sun left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jyemin left a comment

Choose a reason for hiding this comment

Uh oh!

NoahStapp commented Oct 6, 2026

Uh oh!

prestonvasquez Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prestonvasquez Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

prestonvasquez Oct 6, 2026 •

edited

Loading

prestonvasquez Oct 6, 2026 •

edited

Loading

prestonvasquez Oct 6, 2026 •

edited

Loading

prestonvasquez Oct 6, 2026 •

edited

Loading

prestonvasquez Oct 6, 2026 •

edited

Loading

prestonvasquez Oct 6, 2026 •

edited

Loading