Skip to content

chore(format-core): add clang-format configuration + format check #14

@SizzleUnrlsd

Description

@SizzleUnrlsd

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

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions