From a30a65fc50e83dccc2908e270013f74896206ed9 Mon Sep 17 00:00:00 2001
From: HTHou <haonan@apache.org>
Date: Mon, 20 Apr 2026 12:18:44 +0800
Subject: [PATCH] Update README with clang-format install notes

---
 cpp/README-zh.md | 37 ++++++++++++++++++++++++++++++++++++-
 cpp/README.md    | 37 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 72 insertions(+), 2 deletions(-)

diff --git a/cpp/README-zh.md b/cpp/README-zh.md
index 1ff0372f3..bb20dcd92 100644
--- a/cpp/README-zh.md
+++ b/cpp/README-zh.md
@@ -43,6 +43,41 @@ TsFile_cpp 的性能基准测试位于 `./bench_mark` 目录。
 
 我们使用 `clang-format` 来确保 C++ 代码遵循 `./clang-format` 文件中定义的一致规范（类似于 Google 风格）。
 
+`mvn spotless` 会使用 `clang-format v17.0.6` 来格式化 C++ 代码。在提交代码前，请先确认你环境里的 `clang-format` 版本与其一致，并且已经加入 `PATH`。
+
+`clang-format v17.0.6` 安装方式如下：
+
+- macOS
+
+```bash
+brew install llvm@17
+ln -sf /opt/homebrew/opt/llvm@17/bin/clang-format /opt/homebrew/bin/clang-format
+```
+
+- Windows
+
+```bash
+choco install llvm --version 17.0.6 --force
+```
+
+安装完成后，可通过以下命令确认版本：
+
+```bash
+clang-format --version
+```
+
+如需格式化 C++ 代码，可执行：
+
+```bash
+mvn spotless:apply -P with-cpp
+```
+
+如果你需要临时跳过代码格式化检查，可以添加 `-Dspotless.skip=true`，例如：
+
+```bash
+mvn package -P with-cpp clean verify -Dspotless.skip=true
+```
+
 欢迎提交任何 Bug 报告。
 你可以创建一个以 `[CPP]` 开头的 Issue 来描述问题，例如：
 https://github.com/apache/tsfile/issues/94
@@ -146,4 +181,4 @@ storage::set_write_thread_count(4);
 bash build.sh
 ```
 
-即可在 `./examples/build` 目录下生成可执行文件。
\ No newline at end of file
+即可在 `./examples/build` 目录下生成可执行文件。
diff --git a/cpp/README.md b/cpp/README.md
index 9ee9d7c97..9f3ee7ac0 100644
--- a/cpp/README.md
+++ b/cpp/README.md
@@ -38,6 +38,41 @@ The source code can be found in the `./src` directory. C/C++ examples are locate
 
 We use `clang-format` to ensure that our C++ code adheres to a consistent set of rules defined in `./clang-format`. This is similar to the Google style.
 
+`mvn spotless` uses `clang-format v17.0.6` for C++ code formatting. Please make sure the `clang-format` in your `PATH` matches this version before submitting code.
+
+How to install `clang-format v17.0.6`:
+
+- macOS
+
+```bash
+brew install llvm@17
+ln -sf /opt/homebrew/opt/llvm@17/bin/clang-format /opt/homebrew/bin/clang-format
+```
+
+- Windows
+
+```bash
+choco install llvm --version 17.0.6 --force
+```
+
+You can verify the installed version with:
+
+```bash
+clang-format --version
+```
+
+To format the C++ code, run:
+
+```bash
+mvn spotless:apply -P with-cpp
+```
+
+If you need to skip code formatting temporarily, you can add `-Dspotless.skip=true`, for example:
+
+```bash
+mvn package -P with-cpp clean verify -Dspotless.skip=true
+```
+
 We welcome any bug reports. You can open an issue with a title starting with [CPP] to describe the bug, like: https://github.com/apache/tsfile/issues/94
 
 ## Build
@@ -104,4 +139,4 @@ By default, parallel write is enabled when the machine has more than one CPU cor
 
 ## Use TsFile
 
-You can find examples on how to read and write data in `demo_read.cpp` and `demo_write.cpp` located under `./examples/cpp_examples`. There are also examples under `./examples/c_examples`on how to use a C-style API to read and write data in a C environment. You can run `bash build.sh` under `./examples` to generate an executable output under `./examples/build`.
\ No newline at end of file
+You can find examples on how to read and write data in `demo_read.cpp` and `demo_write.cpp` located under `./examples/cpp_examples`. There are also examples under `./examples/c_examples`on how to use a C-style API to read and write data in a C environment. You can run `bash build.sh` under `./examples` to generate an executable output under `./examples/build`.