Contributing

Contributing

Setup

• CMake 3.16+, a C++20 compiler, and optionally Ninja
• clang-format 20: CI pins 20.1.8 (pip install clang-format==20.1.8), and Homebrew's llvm@20 works too
• scripts/setup-dev.sh: creates .venv-pre-commit and installs a commit-msg hook that checks commit messages

Conventions

• Commits follow Conventional Commits: type(scope): subject. Accepted types: feat, fix, chore, docs, refactor, perf, ci, build, style, revert, test. The subject is at most 84 characters. Merge commits are exempt.
• Formatting is LLVM style (.clang-format). scripts/format.sh formats the tree, and scripts/format-check.sh checks it. Both need clang-format 20 or newer, or set CLANG_FORMAT to point to it.
• License: MIT. Any SPDX-License-Identifier in the repository must say MIT (scripts/check-license-compliance.sh).
• Tests: every behavior change comes with a test. For a bug fix, commit the failing test first. See Testing.

Pull requests

• One issue per branch, named after it, for example fix/25-serialize-format-error or test/14-unit-tests.
• Describe the change under ## Summary and how it was checked under ## Verification, then end with Closes #N.
• After opening the pull request, check that the issue appears under Development in its sidebar. GitHub ignores Closes when the base branch is not main (stacked pull requests), and those links were also missing for some pull requests into main. If the link is missing, close the issue by hand once the pull request is merged.

CI workflows

Workflow	Trigger	What it checks
Build	push to main, pull request into main, manual	Build and CTest on Ubuntu, macOS and Windows
Sanitizers	push to main, any pull request, manual	CTest under ASan + UBSan and under TSan (Linux, GCC)
Package	push to main, any pull request, manual	tests/consumer/ through find_package() after cmake --install, and through add_subdirectory(), on Ubuntu and Windows
Coverage	push to main, any pull request, manual	gcovr line coverage, at least 88%
clang-format	push to main, any pull request	scripts/format-check.sh with clang-format 20.1.8
license-compliance	push to main, any pull request	scripts/check-license-compliance.sh
Commit conventions	any push	scripts/ci/commit_checker.py on the pushed commits

Build only runs on pull requests into main. For a pull request based on another branch, start it by hand: gh workflow run build.yml --ref <branch>.