MongoDB Specifications

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.

Writing Documents

Write documents using GitHub Flavored Markdown, following the MongoDB Documentation Style Guidelines.

Store all source documents in the source/ directory.

Linting

This repo uses pre-commit for managing linting. pre-commit performs various checks on the files and uses tools that help follow a consistent style within the repo.

To set up pre-commit locally, run:

brew install pre-commit
pre-commit install

To run pre-commit manually, run pre-commit run --all-files.

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

Building Documents

We use mkdocs to render the documentation. To see a live view of the documentation, run:

pip install mkdocs
mkdocs serve

To build the docs, use mkdocs build.

In CI we verify that there are no warnings. To replicate locally, run mkdocs build --strict.

Converting to JSON

There are many YAML to JSON converters. There are even several converters called yaml2json in NPM. Alas, we are not using yaml2json anymore, but instead the js-yaml package. Use only that 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.

Licensing

All the specs in this repository are available under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License.