From b37e4634def46359f1ebbb6c3e8a4e66328cc860 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Tue, 14 May 2024 06:48:46 -0500 Subject: [PATCH 1/3] DRIVERS-2881 Render documentation on ReadTheDocs --- .readthedocs.yaml | 19 +++++ README.md | 78 ++----------------- mkdocs.yml | 4 + .../connection-monitoring-and-pooling.md | 2 +- source/driver-mantras.md | 69 ++++++++++++++++ source/index.md | 1 + source/requirements.txt | 1 + 7 files changed, 101 insertions(+), 73 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 mkdocs.yml create mode 100644 source/driver-mantras.md create mode 100644 source/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..ddd534c41f --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,19 @@ +# Read the Docs configuration file for MkDocs projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +mkdocs: + configuration: mkdocs.yml + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: source/requirements.txt \ No newline at end of file diff --git a/README.md b/README.md index 92b8d07895..5252f93370 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,13 @@ # MongoDB Specifications +[![Documentation Status](https://readthedocs.org/projects/specifications/badge/?version=latest)](http://specifications.readthedocs.io/en/latest/?badge=latest) + 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 -When developing specifications -- and the drivers themselves -- we follow the following principles: - -### Strive to be idiomatic, but favor consistency - -Drivers attempt to provide the easiest way to work with MongoDB in a given language ecosystem, while specifications -attempt to provide a consistent behavior and experience across all languages. Drivers should strive to be as idiomatic -as possible while meeting the specification and staying true to the original intent. - -### No Knobs - -Too many choices stress out users. Whenever possible, we aim to minimize the number of configuration options exposed to -users. In particular, if a typical user would have no idea how to choose a correct value, we pick a good default instead -of adding a knob. - -### Topology agnostic - -Users test and deploy against different topologies or might scale up from replica sets to sharded clusters. Applications -should never need to use the driver differently based on topology type. - -### Where possible, depend on server to return errors - -The features available to users depend on a server's version, topology, storage engine and configuration. So that -drivers don't need to code and test all possible variations, and to maximize forward compatibility, always let users -attempt operations and let the server error when it can't comply. Exceptions should be rare: for cases where the server -might not error and correctness is at stake. - -### Minimize administrative helpers - -Administrative helpers are methods for admin tasks, like user creation. These are rarely used and have maintenance costs -as the server changes the administrative API. Don't create administrative helpers; let users rely on "RunCommand" for -administrative commands. - -### Check wire version, not server version - -When determining server capabilities within the driver, rely only on the maxWireVersion in the hello response, not on -the X.Y.Z server version. An exception is testing server development releases, as the server bumps wire version early -and then continues to add features until the GA. - -### When in doubt, use "MUST" not "SHOULD" in specs - -Specs guide our work. While there are occasionally valid technical reasons for drivers to differ in their behavior, -avoid encouraging it with a wishy-washy "SHOULD" instead of a more assertive "MUST". - -### Defy augury - -While we have some idea of what the server will do in the future, don't design features with those expectations in mind. -Design and implement based on what is expected in the next release. - -Case Study: In designing OP_MSG, we held off on designing support for Document Sequences in Replies in drivers until the -server would support it. We subsequently decided not to implement that feature in the server. - -### The best way to see what the server does is to test it - -For any unusual case, relying on documentation or anecdote to anticipate the server's behavior in different -versions/topologies/etc. is error-prone. The best way to check the server's behavior is to use a driver or the shell and -test it directly. - -### Drivers follow semantic versioning - -Drivers should follow X.Y.Z versioning, where breaking API changes require a bump to X. See -[semver.org](https://semver.org/) for more. - -### Backward breaking behavior changes and semver - -Backward breaking behavior changes can be more dangerous and disruptive than backward breaking API changes. When -thinking about the implications of a behavior change, ask yourself what could happen if a user upgraded your library -without carefully reading the changelog and/or adequately testing the change. +See [Documentation](./source/driver-mantras.md). ## Writing Documents @@ -110,13 +46,11 @@ entire test with a note (e.g. *Removed*). ## Building Documents -We build the docs in `text` mode in CI to make sure they build without errors. We don't actually support building html, -since we rely on GitHub to render the documents. To build locally, run: +We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, run: ```bash -pip install sphinx -cd source -sphinx-build -W -b text . docs_build index.rst +pip install mkdocs +mkdocs serve ``` ## Converting to JSON diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..1f8af2db19 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,4 @@ +site_name: MongoDB Specifications +docs_dir: source +nav: + - 'index.md' \ No newline at end of file diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md index 00ca2899ff..b1179698c5 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md @@ -1265,7 +1265,7 @@ longer full, it is immediately filled. It is not a favorable situation to be in, guarantee that the waitQueue normally provides. Because of these issues, it does not make sense to -[go against driver mantras and provide an additional knob](../../README.md#). We may eventually pursue an alternative +[go against driver mantras and provide an additional knob](../driver-mantras.md#). We may eventually pursue an alternative configurations to address wait queue size in [Advanced Pooling Behaviors](#advanced-pooling-behaviors). Users that wish to have this functionality can achieve similar results by utilizing other methods to limit concurrency. diff --git a/source/driver-mantras.md b/source/driver-mantras.md new file mode 100644 index 0000000000..467f741dd2 --- /dev/null +++ b/source/driver-mantras.md @@ -0,0 +1,69 @@ +# Driver Mantras + +When developing specifications -- and the drivers themselves -- we follow the following principles: + +### Strive to be idiomatic, but favor consistency + +Drivers attempt to provide the easiest way to work with MongoDB in a given language ecosystem, while specifications +attempt to provide a consistent behavior and experience across all languages. Drivers should strive to be as idiomatic +as possible while meeting the specification and staying true to the original intent. + +### No Knobs + +Too many choices stress out users. Whenever possible, we aim to minimize the number of configuration options exposed to +users. In particular, if a typical user would have no idea how to choose a correct value, we pick a good default instead +of adding a knob. + +### Topology agnostic + +Users test and deploy against different topologies or might scale up from replica sets to sharded clusters. Applications +should never need to use the driver differently based on topology type. + +### Where possible, depend on server to return errors + +The features available to users depend on a server's version, topology, storage engine and configuration. So that +drivers don't need to code and test all possible variations, and to maximize forward compatibility, always let users +attempt operations and let the server error when it can't comply. Exceptions should be rare: for cases where the server +might not error and correctness is at stake. + +### Minimize administrative helpers + +Administrative helpers are methods for admin tasks, like user creation. These are rarely used and have maintenance costs +as the server changes the administrative API. Don't create administrative helpers; let users rely on "RunCommand" for +administrative commands. + +### Check wire version, not server version + +When determining server capabilities within the driver, rely only on the maxWireVersion in the hello response, not on +the X.Y.Z server version. An exception is testing server development releases, as the server bumps wire version early +and then continues to add features until the GA. + +### When in doubt, use "MUST" not "SHOULD" in specs + +Specs guide our work. While there are occasionally valid technical reasons for drivers to differ in their behavior, +avoid encouraging it with a wishy-washy "SHOULD" instead of a more assertive "MUST". + +### Defy augury + +While we have some idea of what the server will do in the future, don't design features with those expectations in mind. +Design and implement based on what is expected in the next release. + +Case Study: In designing OP_MSG, we held off on designing support for Document Sequences in Replies in drivers until the +server would support it. We subsequently decided not to implement that feature in the server. + +### The best way to see what the server does is to test it + +For any unusual case, relying on documentation or anecdote to anticipate the server's behavior in different +versions/topologies/etc. is error-prone. The best way to check the server's behavior is to use a driver or the shell and +test it directly. + +### Drivers follow semantic versioning + +Drivers should follow X.Y.Z versioning, where breaking API changes require a bump to X. See +[semver.org](https://semver.org/) for more. + +### Backward breaking behavior changes and semver + +Backward breaking behavior changes can be more dangerous and disruptive than backward breaking API changes. When +thinking about the implications of a behavior change, ask yourself what could happen if a user upgraded your library +without carefully reading the changelog and/or adequately testing the change. \ No newline at end of file diff --git a/source/index.md b/source/index.md index cc0f28dbe7..b27666f0b9 100644 --- a/source/index.md +++ b/source/index.md @@ -13,6 +13,7 @@ - [Connection String Spec](connection-string/connection-string-spec.md) - [Driver Authentication](auth/auth.md) - [Driver CRUD API](crud/crud.md) +- [Driver Mantras](./driver-mantras.md) - [Driver Sessions Specification](sessions/driver-sessions.md) - [Driver Transactions Specification](transactions/transactions.md) - [FaaS Automated Testing](faas-automated-testing/faas-automated-testing.md) diff --git a/source/requirements.txt b/source/requirements.txt new file mode 100644 index 0000000000..b854bca214 --- /dev/null +++ b/source/requirements.txt @@ -0,0 +1 @@ +mkdocs \ No newline at end of file From 06908d46393bd729fb6ccb2b7481b78927aa7566 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Tue, 14 May 2024 06:48:57 -0500 Subject: [PATCH 2/3] DRIVERS-2881 Render documentation on ReadTheDocs --- README.md | 2 +- .../connection-monitoring-and-pooling.md | 4 ++-- source/driver-mantras.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5252f93370..3f88b2fa57 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ entire test with a note (e.g. *Removed*). ## Building Documents -We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, run: +We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, run: ```bash pip install mkdocs diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md index b1179698c5..9107efb251 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md @@ -1265,8 +1265,8 @@ longer full, it is immediately filled. It is not a favorable situation to be in, guarantee that the waitQueue normally provides. Because of these issues, it does not make sense to -[go against driver mantras and provide an additional knob](../driver-mantras.md#). We may eventually pursue an alternative -configurations to address wait queue size in [Advanced Pooling Behaviors](#advanced-pooling-behaviors). +[go against driver mantras and provide an additional knob](../driver-mantras.md#). We may eventually pursue an +alternative configurations to address wait queue size in [Advanced Pooling Behaviors](#advanced-pooling-behaviors). Users that wish to have this functionality can achieve similar results by utilizing other methods to limit concurrency. Examples include implementing either a thread pool or an operation queue with a capped size in the user application. diff --git a/source/driver-mantras.md b/source/driver-mantras.md index 467f741dd2..bf52c62f0a 100644 --- a/source/driver-mantras.md +++ b/source/driver-mantras.md @@ -66,4 +66,4 @@ Drivers should follow X.Y.Z versioning, where breaking API changes require a bum Backward breaking behavior changes can be more dangerous and disruptive than backward breaking API changes. When thinking about the implications of a behavior change, ask yourself what could happen if a user upgraded your library -without carefully reading the changelog and/or adequately testing the change. \ No newline at end of file +without carefully reading the changelog and/or adequately testing the change. From 434c713bd4ea794143ff3941c757af8362e62326 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Tue, 28 May 2024 09:58:36 -0500 Subject: [PATCH 3/3] Update source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md Co-authored-by: Jib --- .../connection-monitoring-and-pooling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md index 9107efb251..4864d40ce8 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md @@ -1266,7 +1266,7 @@ guarantee that the waitQueue normally provides. Because of these issues, it does not make sense to [go against driver mantras and provide an additional knob](../driver-mantras.md#). We may eventually pursue an -alternative configurations to address wait queue size in [Advanced Pooling Behaviors](#advanced-pooling-behaviors). +alternative configuration to address wait queue size in [Advanced Pooling Behaviors](#advanced-pooling-behaviors). Users that wish to have this functionality can achieve similar results by utilizing other methods to limit concurrency. Examples include implementing either a thread pool or an operation queue with a capped size in the user application.