docs: rework the README to the org layout and fix outdated facts

[shenxianpeng]

Part of aligning the READMEs across the org. Every README gets the same opening (name, badges, one sentence, a link line) and the same section order: Quick start, Usage, topic sections, Used by, Contributing, License.

What changed

Header

• 6 badges become 4 in one style: PyPI, ci, coverage, part of cpp-linter. Python versions and CodeQL are gone.
• The sentence and the Quick start are the same as on https://cpp-linter.github.io/getting-started/#before-every-commit.

Wrong or outdated, now fixed

• "Each release bundles a default version" is no longer true. Since v1.6.0 a hook without --version installs the newest wheel on PyPI at every run.
• The mirrors-clang-format table said it has no --style, --verbose or dry-run. It has all three (tested), so the ✅/❌ table becomes plain text.
• The --export-fixes warning blamed --jobs, but the hook already turns --jobs off for that flag. The real collision is pre-commit running groups of files in parallel: with 12 files, fixes.yaml kept 4 entries, and 12 with require_serial: true.
• Relative links become full URLs, so they work on PyPI.

Removed

• The "Why" section and the "Custom configuration files" block, which repeated other sections.
• The <p align> HTML in Used by. Each org is now its avatar and name in one link.
• Emoji, the "~80%" claim and the exclamation mark.

examples/

• --checks=.clang-tidy removed: it is a check glob, not a file, and clang-tidy finds .clang-tidy by itself.
• rev: v1.5.0 becomes v1.6.0, checkout@v4/setup-python@v5 become v7, and the "~80%" claim is gone.

Checked

• Every example ran with pre-commit 4.6.2 and rev: v1.6.0 in scratch repos.
  • clang-format fixed a badly formatted file.
  • clang-tidy passed once CMake wrote compile_commands.json.
• Every Used by org still runs the hook on its default branch.
• readme_renderer renders the README without warnings, so the PyPI page will render.

Note

--dry-run keeps a v1.6.0 caveat, because in v1.6.0 it always passes. Releasing v1.6.1 (draft) removes the need for it. rev would then move to v1.6.1 here and on the website.

Summary by CodeRabbit

• Documentation
  • Reorganized the main guide with clearer setup and usage instructions, including tool-version selection, supported wheel versions, and troubleshooting.
  • Added guidance on clang-format dry runs, clang-tidy checks and fixes, compilation database discovery, examples, and verbose output.
  • Updated example configurations and CI action versions, and clarified that formatting dry runs report lines needing changes without modifying files.
  • Removed the FAQ and some earlier explanatory material.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.53%. Comparing base (5de731b) to head (dd49517).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #289   +/-   ##
=======================================
  Coverage   97.53%   97.53%           
=======================================
  Files           3        3           
  Lines         243      243           
=======================================
  Hits          237      237           
  Misses          6        6           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Caution

Review failed

Failed to post review comments.

GitHub was unavailable or timed out while CodeRabbit was posting the review. Please request a new review later if the pull request still needs one. This happened while posting 2 inline comments. Use @coderabbitai full review to retry the review.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 9ca947d0-7b6e-4f27-a4b3-3c02e40fb95c

📥 Commits

Reviewing files that changed from the base of the PR and between 5de731b and dd49517.

📒 Files selected for processing (4)

• README.md
• examples/README.md
• examples/cmake/README.md
• examples/large-project/README.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

⏰ Context from checks skipped due to timeout. (20)

• GitHub Check: pre-commit / run-pre-commit
• GitHub Check: pre-commit / Check PR title
• GitHub Check: codeql / Analyze
• GitHub Check: draft-release / label_pr
• GitHub Check: test (windows-latest, 3.12)
• GitHub Check: test (ubuntu-latest, 3.14)
• GitHub Check: test (macos-latest, 3.11)
• GitHub Check: test (windows-latest, 3.14)
• GitHub Check: test (windows-latest, 3.11)
• GitHub Check: test (macos-latest, 3.10)
• GitHub Check: test (ubuntu-latest, 3.12)
• GitHub Check: test (macos-latest, 3.12)
• GitHub Check: test (macos-latest, 3.13)
• GitHub Check: test (windows-latest, 3.10)
• GitHub Check: test (ubuntu-latest, 3.13)
• GitHub Check: test (ubuntu-latest, 3.11)
• GitHub Check: test (macos-latest, 3.14)
• GitHub Check: test (ubuntu-latest, 3.10)
• GitHub Check: test (windows-latest, 3.13)
• GitHub Check: Analyze (python)

Walkthrough

The README was reorganized to cover setup, clang tool usage, compilation databases, pre-commit behavior, and feature comparisons. The example guides update hook settings, CI action versions, and clang-format dry-run descriptions.

Changes

Documentation and examples

Layer / File(s)	Summary
Setup and tool usage README.md	The README updates the quick start and documents clang-format output and clang-tidy check configuration.
Compilation databases and execution README.md	The README documents compilation-database discovery and selection, clang-tidy parallel execution behavior, and verbose output settings.
Comparison and example updates README.md, examples/README.md, examples/cmake/README.md, examples/large-project/README.md	The README adds a feature comparison and updates contribution, license, and showcase links. The example guides update hook settings, CI action versions, and dry-run wording.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Architecture Summary

Architecture risk: 🔵 Low · up to dd495

The change affects 2 systems.

Changed systems: examples, README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — examples (service) was modified; 3 changed files map to changed impact.
• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: Replaces the project overview and broad quick-start examples with badges, links, and a compact setup guide. The example pins clang-format and clang-tidy to major version 21, explains that rev identifies the project release, and documents version lookup, wheel availability, and network-failure behavior. Adds clang-format style selection and describes its modifying and dry-run output.
• observed — Modified behavior in README.md: Updates the clang-format dry-run example to show exit code 1 and formatting-violation diagnostics, replacing the previous exit code 255 and warning output. Adds guidance for quoting comma-separated clang-tidy checks in YAML and states that warnings or errors fail the hook.
• observed — Modified behavior in README.md: Adds compilation-database guidance covering automatic discovery in common build directories, explicit directory selection, disabling discovery, and CMake generation. Adds links to project examples. Removes the prior warning that --fix or -fix-errors automatically disables parallel execution.
• observed — Modified behavior in README.md: Replaces guidance about unique output paths for parallel clang-tidy invocations with a warning that --fix, -fix, -fix-errors, or --export-fixes causes the hook to ignore --jobs; pre-commit may still parallelize file groups, so require_serial: true is documented to run the hook once for all files.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary changes: README reorganization and correction of outdated documentation facts.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}