Context
The codebase currently has no enforced formatting standard. This leads to inconsistent style, noisy diffs, and harder code reviews.
Goals
• Add a versioned clang-format configuration to the repository.
• Provide simple developer commands to format locally.
• Add a CI check that fails when code is not formatted (CI should not auto-reformat).
Scope
1) Configuration
• Add a .clang-format file at the repository root (or tools/format/ if that matches the repo conventions).
• Pick a baseline style (e.g., LLVM / Google) and lock it in the config.
2) Developer commands
Add commands via Makefile / CMake targets / scripts:
• format: formats the whole C/C++ codebase in-place
• format-check: verifies formatting without modifying files
Expected behavior:
• format runs clang-format -i on all relevant sources
• format-check produces a non-zero exit code if any file differs from clang-format -style=file
3) CI
Add a CI job (e.g., GitHub Actions) named clang-format that:
• Installs clang-format
• Runs format-check
• Fails if formatting differences are detected
Proposed Implementation
Files to add
• .clang-format
• scripts/format.sh
• scripts/format-check.sh
• (Optional) update .gitignore if needed
File selection / exclusions
Target only:
• *.c, *.cc, *.cpp, *.cxx, *.h, *.hh, *.hpp, *.hxx
Exclude common generated / external directories:
• build/, external/, third_party/, vendor/, submodules/ (adapt to repo layout)
Acceptance Criteria
• clang-format -style=file works from any subdirectory (config is discovered correctly)
• ./scripts/format.sh formats repository sources and does not touch external dependencies
• ./scripts/format-check.sh returns a non-zero exit code when at least one file is not formatted
• CI fails when formatting is not respected
• README or CONTRIBUTING documents how to install and use clang-format
Notes / Decisions
• Standardize the clang-format version (e.g., 16 or 17) to avoid cross-version diffs between local and CI.
• Suggested baseline style: BasedOnStyle: LLVM (adjustable).
Follow-ups (optional)
• Add a pre-commit hook to run format-check before commits
• Add a CMake target (cmake --build . --target format) if the project uses CMake
Context
The codebase currently has no enforced formatting standard. This leads to inconsistent style, noisy diffs, and harder code reviews.
Goals
Scope
1) Configuration
2) Developer commands
Add commands via Makefile / CMake targets / scripts:
• format: formats the whole C/C++ codebase in-place
• format-check: verifies formatting without modifying files
Expected behavior:
• format runs clang-format -i on all relevant sources
• format-check produces a non-zero exit code if any file differs from clang-format -style=file
3) CI
Add a CI job (e.g., GitHub Actions) named clang-format that:
• Installs clang-format
• Runs format-check
• Fails if formatting differences are detected
Proposed Implementation
Files to add
File selection / exclusions
Target only:
Exclude common generated / external directories:
Acceptance Criteria
Notes / Decisions
Follow-ups (optional)