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.
See Documentation.
Write documents using GitHub Flavored Markdown, following the MongoDB Documentation Style Guidelines.
Store all source documents in the source/ directory.
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 installTo 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 shellcheckWhen 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).
We use mkdocs to render the documentation. To see a live view of the documentation, run:
pip install mkdocs
mkdocs serveTo build the docs, use mkdocs build.
In CI we verify that there are no warnings. To replicate locally, run mkdocs build --strict.
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.
All the specs in this repository are available under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License.