apache · hongzhi-gao · Apr 21, 2026 · Apr 21, 2026 · Apr 22, 2026 · Apr 22, 2026
diff --git a/.clang-format b/.clang-format
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+---
+BasedOnStyle: LLVM
+IndentWidth: 2
+TabWidth: 2
+UseTab: Never
+ColumnLimit: 100
+BreakBeforeBraces: Attach
+AllowShortIfStatementsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Empty
+PointerAlignment: Left
+DerivePointerAlignment: false
+SortIncludes: false
+ReflowComments: false
+Standard: c++11
+...
diff --git a/.github/workflows/client-cpp-package.yml b/.github/workflows/client-cpp-package.yml
@@ -87,7 +87,20 @@ jobs:
         run: |
           set -euxo pipefail
           sudo apt-get update
-          sudo apt-get install -y libboost-all-dev openssl libssl-dev
+          sudo apt-get install -y libboost-all-dev openssl libssl-dev wget
+          . /etc/os-release
+          if [[ "${VERSION_CODENAME}" == "jammy" ]]; then
+            wget -qO /tmp/llvm.sh https://apt.llvm.org/llvm.sh
+            chmod +x /tmp/llvm.sh
+            sudo DEBIAN_FRONTEND=noninteractive /tmp/llvm.sh 17
+            # llvm.sh installs clang-17/lldb/lld/clangd but not the clang-format-17 package
+            sudo apt-get install -y clang-format-17
+          else
+            sudo apt-get install -y clang-format-17
+          fi
+          sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-17 100
+          sudo update-alternatives --set clang-format /usr/bin/clang-format-17
+          clang-format --version
       - name: Cache Maven packages
         uses: actions/cache@v5
         with:
@@ -99,9 +112,7 @@ jobs:
         shell: bash
         run: |
           set -euxo pipefail
-          ./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am \
-            -DskipTests \
-            -Dspotless.check.skip=true -Dspotless.apply.skip=true
+          ./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests
       - name: Upload zip artifact
         uses: actions/upload-artifact@v6
         with:
@@ -133,7 +144,10 @@ jobs:
         shell: bash
         run: |
           set -euxo pipefail
-          brew install boost openssl
+          brew install boost openssl llvm@17
+          ln -sf "$(brew --prefix llvm@17)/bin/clang-format" "$(brew --prefix)/bin/clang-format"
+          echo "$(brew --prefix llvm@17)/bin" >> "$GITHUB_PATH"
+          clang-format --version
       - name: Cache Maven packages
         uses: actions/cache@v5
         with:
@@ -147,9 +161,7 @@ jobs:
           MACOSX_DEPLOYMENT_TARGET: "12.0"
         run: |
           set -euxo pipefail
-          ./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am \
-            -DskipTests \
-            -Dspotless.check.skip=true -Dspotless.apply.skip=true
+          ./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests
       - name: Upload zip artifact
         uses: actions/upload-artifact@v6
         with:
@@ -194,6 +206,8 @@ jobs:
           $sslPath = (Get-ChildItem 'C:\Program Files\OpenSSL*' -Directory | Select-Object -First 1).FullName
           echo "$sslPath\bin" >> $env:GITHUB_PATH
           echo "OPENSSL_ROOT_DIR=$sslPath" >> $env:GITHUB_ENV
+          choco install llvm --version=17.0.6 --force -y
+          clang-format --version
       - name: Cache Maven packages
         uses: actions/cache@v5
         with:
@@ -208,9 +222,7 @@ jobs:
           IOTDB_TOOLS_THRIFT_VERSION: ${{ matrix.iotdb_tools_thrift_version }}
         run: |
           set -euxo pipefail
-          MVN_ARGS=(./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am \
-            -DskipTests \
-            -Dspotless.check.skip=true -Dspotless.apply.skip=true)
+          MVN_ARGS=(./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests)
           if [ -n "${CMAKE_GENERATOR:-}" ]; then
             MVN_ARGS+=("-Dcmake.generator=${CMAKE_GENERATOR}")
           fi

diff --git a/.github/workflows/multi-language-client.yml b/.github/workflows/multi-language-client.yml
@@ -54,16 +54,33 @@ jobs:
         if: runner.os == 'Linux'
         shell: bash
         run: |
+          set -euxo pipefail
           sudo apt-get update
-          sudo apt-get install libboost-all-dev
-          sudo apt-get install openssl libssl-dev
+          sudo apt-get install -y libboost-all-dev openssl libssl-dev wget
+          # jammy (22.04): no clang-format-17 in default repos — use apt.llvm.org (same LLVM 17 as noble/choco/brew)
+          . /etc/os-release
+          if [[ "${VERSION_CODENAME}" == "jammy" ]]; then
+            wget -qO /tmp/llvm.sh https://apt.llvm.org/llvm.sh
+            chmod +x /tmp/llvm.sh
+            sudo DEBIAN_FRONTEND=noninteractive /tmp/llvm.sh 17
+            # llvm.sh installs clang-17/lldb/lld/clangd but not the clang-format-17 package
+            sudo apt-get install -y clang-format-17
+          else
+            sudo apt-get install -y clang-format-17
+          fi
+          sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-17 100
+          sudo update-alternatives --set clang-format /usr/bin/clang-format-17
+          clang-format --version
       - name: Install CPP Dependencies (Mac)
         # remove some xcode to release disk space
         if: runner.os == 'macOS'
         shell: bash
         run: |
           brew install boost
-          brew install openssl
+          brew install openssl llvm@17
+          ln -sf "$(brew --prefix llvm@17)/bin/clang-format" "$(brew --prefix)/bin/clang-format"
+          echo "$(brew --prefix llvm@17)/bin" >> "$GITHUB_PATH"
+          clang-format --version
           sudo rm -rf /Applications/Xcode_14.3.1.app
           sudo rm -rf /Applications/Xcode_15.0.1.app
           sudo rm -rf /Applications/Xcode_15.1.app
@@ -72,21 +89,28 @@ jobs:
       - name: Install CPP Dependencies (Windows)
         if: runner.os == 'Windows'
         run: |
-          choco install winflexbison3
-          choco install boost-msvc-14.3
+          choco install winflexbison3 -y
+          choco install boost-msvc-14.3 -y
           $boost_path = (Get-ChildItem -Path 'C:\local\' -Filter 'boost_*').FullName
           echo $boost_path >> $env:GITHUB_PATH
 
-          choco install openssl
+          choco install openssl -y
           $sslPath = (Get-ChildItem 'C:\Program Files\OpenSSL*' -Directory | Select-Object -First 1).FullName
           echo "$sslPath\bin" >> $env:GITHUB_PATH
           echo "OPENSSL_ROOT_DIR=$sslPath" >> $env:GITHUB_ENV
+          choco install llvm --version=17.0.6 --force -y
+          clang-format --version
       - name: Cache Maven packages
         uses: actions/cache@v5
         with:
           path: ~/.m2
           key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
           restore-keys: ${{ runner.os }}-m2-
+      - name: Check C++ format (Spotless)
+        shell: bash
+        run: |
+          ./mvnw -P with-cpp -pl iotdb-client/client-cpp spotless:check
+          ./mvnw -P with-cpp -pl example/client-cpp-example spotless:check
       - name: Build IoTDB server
         shell: bash
         run: ./mvnw clean install -pl distribution -am -DskipTests

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -107,6 +107,31 @@ plugin](https://github.com/diffplug/spotless/tree/main/plugin-maven) together wi
    import static all other imports
 ```
 
+### C++ formatting
+
+- Formatter: `clang-format` only
+- Version: pinned as `clang.format.version` in the root `pom.xml` (currently `17.0.6`, aligned with Apache TsFile); CI installs LLVM/clang-format so the default `clang-format` on the runner matches that version
+- Entrypoint: Maven Spotless; the `clangFormat` configuration is attached under the `spotless-cpp` profile in the C++ modules and activates only on **JDK 11+**, so run `spotless:check` / `spotless:apply` for C++ with JDK 11 or newer (CI does). JDK 8 builds elsewhere in the reactor do not load that Spotless fragment.
+
+Check only:
+
+`./mvnw -P with-cpp -pl iotdb-client/client-cpp spotless:check`
+
+`./mvnw -P with-cpp -pl example/client-cpp-example spotless:check`
+
+Auto-fix:
+
+`./mvnw -P with-cpp -pl iotdb-client/client-cpp spotless:apply`
+
+`./mvnw -P with-cpp -pl example/client-cpp-example spotless:apply`
+
+On Windows PowerShell, a comma inside `-pl` can be parsed incorrectly; use the two commands above, or quote the full `-pl` value, for example `./mvnw -P with-cpp "-pl=iotdb-client/client-cpp,example/client-cpp-example" spotless:check`.
+
+Temporarily skip Spotless (not recommended except emergency CI triage):
+
+`-Dspotless.skip=true`
+
+Risk: skipping formatting checks can introduce style drift between contributors and CI, and often causes follow-up format-only commits.
 
 ## Contributing code
 

diff --git a/example/client-cpp-example/pom.xml b/example/client-cpp-example/pom.xml
@@ -162,4 +162,39 @@
             </plugin>
         </plugins>
     </build>
+    <profiles>
+        <profile>
+            <id>spotless-cpp</id>
+            <activation>
+                <jdk>[11,)</jdk>
+            </activation>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>com.diffplug.spotless</groupId>
+                        <artifactId>spotless-maven-plugin</artifactId>
+                        <version>2.44.5</version>
+                        <configuration>
+                            <cpp>
+                                <includes>
+                                    <include>src/**/*.h</include>
+                                    <include>src/**/*.hpp</include>
+                                    <include>src/**/*.c</include>
+                                    <include>src/**/*.cc</include>
+                                    <include>src/**/*.cpp</include>
+                                </includes>
+                                <excludes>
+                                    <exclude>src/test/catch2/**</exclude>
+                                </excludes>
+                                <clangFormat>
+                                    <version>${clang.format.version}</version>
+                                    <style>file</style>
+                                </clangFormat>
+                            </cpp>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
 </project>