Require Clang Formatting

[mfisher31]

Info

Unfortunately, you cannot specify the clang-format version directly in the .clang-format file itself. The configuration file has no field for version pinning.

Best practices to ensure consistency:

1. Document the version in a comment:

# This file is formatted with clang-format version 18.0.0
# Please use the same version for consistency
---
AccessModifierOffset: -4
...

2. Use .clang-format-version file (not standard, but you can reference it in docs):

18.0.0

3. Enforce in CI/CD - In your GitHub Actions workflow:

- name: Check formatting
  run: |
    clang-format-18 --version
    clang-format-18 --dry-run --Werror src/*.cpp

4. Use pre-commit framework with pinned version in .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v18.1.8
    hooks:
      - id: clang-format

The most practical approach is #1 (comment) + #3 (CI enforcement). This way the version is visible in the config file and automated checks ensure compliance.

Let CI Handle It

Best Practice: CI handles formatting, devs write code

1. Add a GitHub Action that auto-formats (or just checks):

# .github/workflows/format.yml
name: Format Check
on: [pull_request]
jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DoozyX/clang-format-lint-action@v0.17
        with:
          source: 'src include'
          clangFormatVersion: 18
          style: file

2. Optional: Provide a formatting script using Docker (for those who want it):

#!/bin/bash
# scripts/format.sh
docker run --rm -v "$PWD:/src" xianpengshen/clang-format:18 \
  find /src/src /src/include -name '*.cpp' -o -name '*.hpp' | xargs clang-format-18 -i

3. Document in CONTRIBUTING.md:

## Code Formatting

CI will check formatting. If your PR fails formatting checks:
- Let CI auto-fix it (if enabled), or
- Run `./scripts/format.sh` (requires Docker), or  
- Don't worry about it - maintainers can format before merge

The key insight: Don't block contributions over formatting. Let CI be the source of truth, and either:

• Auto-format on merge
• Have maintainers format before merging
• Use a bot to push formatting fixes

This keeps the barrier to contribution low while maintaining consistency in the main branch.