Contributor Quickstart

Pick an issue, branch off upstream/develop, and ask for review once the full check passes.

Contribution steps

  1. Open an issue for a bug or feature request, or pick an open one, on the issue tracker.

  2. To talk a change over first, use the #mrdocs channel on the Cpplang Slack.

  3. Fork and clone the repository, then add the main repository as upstream with git remote add upstream https://github.com/cppalliance/mrdocs.git and git fetch upstream.

  4. Install the prerequisites and run the bootstrap script, as Build from Source describes. Development Setup covers what to do after bootstrap.

  5. Create a branch off upstream/develop, not off your fork’s develop, which may be behind.

  6. Keep one purpose per pull request. Send a bug fix and an unrelated cleanup separately.

  7. Add tests for the change, as Testing & fixtures describes.

  8. Follow C++ Conventions. Name commits as Git Repository says, and add fix #<n> to the body when the change closes issue <n>.

  9. Open a pull request and describe the change and its tests.

  10. Run python3 utils/testing/run_all_tests.py, fix what it reports, and request review once it passes.

Run the full check

The full check is the source of truth before you send changes. Run it with:

python3 utils/testing/run_all_tests.py

It does these things in order:

  1. Lints the files changed since the upstream base.

  2. Configures the preferred preset and builds.

  3. Runs the golden, unit, lint, schema and self-documentation checks.

  4. Installs into a local install/<preset> prefix.

  5. Builds the docs from that install, unless you skip it.

No program can enforce every policy, but this script runs every check a program can. Use it instead of a hand-written sequence of commands.

Bootstrap has to have run first: without its CMakeUserPresets.json the script stops with "CMake user presets are missing". The docs step needs Node, so pass --skip-docs on a machine without it.

Two flags drop part of the check:

  • --skip-docs drops the docs build.

  • --no-strict drops the strict tests: the xml-lint test and the self-documentation check that treats warnings as errors (MRDOCS_BUILD_STRICT_TESTS=OFF).

Use --no-strict on a machine without LibXml2 or Java. CI runs those tests, so a change can pass with the flag and still fail there.

--update-golden refreshes the golden fixtures first. Use it only for an intended output change.