You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by ja...@apache.org on 2026/02/28 03:56:24 UTC
(iotdb) 01/01: Add project helpful info readme for AI Coding model
This is an automated email from the ASF dual-hosted git repository.
jackietien pushed a commit to branch AGENTMD
in repository https://gitbox.apache.org/repos/asf/iotdb.git
commit 5356cd75a519d7ae90ae8dadd399c7704fb774d2
Author: JackieTien97 <ja...@gmail.com>
AuthorDate: Sat Feb 28 11:40:18 2026 +0800
Add project helpful info readme for AI Coding model
---
AGENTS.md | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 22 +++++++
2 files changed, 218 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..0cb9fde79b0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,196 @@
+<!--
+
+ 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.
+
+-->
+
+# Project Overview
+
+Apache IoTDB is a distributed time-series database written in Java. Version 2.0.x supports both tree-model (time-series paths) and table-model (relational) data access. It uses a ConfigNode/DataNode architecture with pluggable consensus protocols.
+
+
+# IoTDB Java Code Style Guide
+
+This document defines the coding rules that **must** be followed when generating or modifying Java code in this project. These rules are enforced by CheckStyle (`checkstyle.xml`) and Spotless (`pom.xml`).
+
+## Imports
+
+1. **Star imports are forbidden**: Never use `import xxx.*` or `import static xxx.*`. Always list each required class or static member explicitly.
+2. **Import ordering** (enforced by Spotless):
+ ```
+ org.apache.iotdb.*
+ ← blank line
+ Other third-party packages (e.g. org.apache.arrow, com.google, etc.)
+ ← blank line
+ javax.*
+ java.*
+ ← blank line
+ static imports
+ ```
+3. **Remove unused imports**.
+
+## Formatting
+
+- Use **Google Java Format** (GOOGLE style).
+- Indent with **2 spaces**, no tabs.
+- Line width limit is **100 characters** (except `package`, `import`, and URL lines).
+- Use **UNIX (LF)** line endings.
+
+## Naming Conventions
+
+| Type | Rule | Example |
+|------|------|---------|
+| Package | All lowercase, dot-separated | `org.apache.iotdb.flight` |
+| Class | UpperCamelCase | `TsBlockToArrowConverter` |
+| Method | lowerCamelCase (`^[a-z][a-z0-9][a-zA-Z0-9_]*$`) | `fillVectorSchemaRoot` |
+| Member variable | lowerCamelCase (`^[a-z][a-z0-9][a-zA-Z0-9]*$`) | `allocator` |
+| Parameter | lowerCamelCase | `tsBlock` |
+| Constant | UPPER_SNAKE_CASE, at most 1 consecutive uppercase letter in abbreviations | `MAX_RETRY_COUNT` |
+
+## Code Structure
+
+- Only one top-level class per `.java` file.
+- `switch` statements must have a `default` branch.
+- Empty `try`/`catch`/`if`/`else`/`switch` blocks are not allowed (unless they contain a comment).
+- Exception variables in empty `catch` blocks must be named `expected`.
+- `if`/`else`/`for`/`while`/`do` must use braces `{}`.
+
+## License Header
+
+Every file must start with the Apache License 2.0 header, java file:
+
+```java
+/*
+ * 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.
+ */
+```
+
+md or xml file:
+
+```xml
+<!--
+
+ 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.
+
+-->
+```
+
+## Verification Commands
+
+```bash
+# Format code
+mvn spotless:apply -P with-integration-tests
+
+# Check style
+mvn checkstyle:check -P with-integration-tests
+```
+
+# Integration Test Rules
+
+- When writing integration tests, always use `SessionConfig.DEFAULT_USER` and `SessionConfig.DEFAULT_PASSWORD` for the user and password instead of hardcoding values.
+
+# Build Commands
+
+```bash
+# Full build (produces distribution in distribution/target/)
+mvn clean package -pl distribution -am -DskipTests
+
+# Build server only
+mvn clean package -DskipTests
+
+# Build CLI only
+mvn clean package -pl iotdb-client/cli -am -DskipTests
+
+# Code formatting check / auto-fix (Google Java Format via Spotless)
+mvn spotless:check -P with-integration-tests
+mvn spotless:apply -P with-integration-tests
+
+# Format integration test code
+mvn spotless:apply -P with-integration-tests
+```
+
+# Running Tests
+
+```bash
+# Unit tests for a specific module
+mvn test -pl iotdb-core/datanode
+
+# Single unit test class
+mvn test -pl iotdb-core/datanode -Dtest=ClassName
+
+# Single unit test method
+mvn test -pl iotdb-core/datanode -Dtest=ClassName#methodName
+
+# Integration tests — Simple mode (1 ConfigNode + 1 DataNode, tree model)
+mvn clean verify -DskipUTs -pl integration-test -am -P with-integration-tests
+
+# Single IT test class — Simple mode (1 ConfigNode + 1 DataNode, tree model)
+mvn clean verify -DskipUTs -Dit.test=ClassName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -P with-integration-tests -am -PSimpleIT
+
+# Integration tests — Cluster mode (1 ConfigNode + 3 DataNodes, tree model)
+mvn clean verify -DskipUTs -pl integration-test -am -PClusterIT -P with-integration-tests
+
+# Single IT test class — Cluster mode (1 ConfigNode + 3 DataNodes, tree model)
+mvn clean verify -DskipUTs -Dit.test=ClassName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -P with-integration-tests -am -PClusterIT
+
+# Integration tests — Table model simple
+mvn clean verify -DskipUTs -pl integration-test -am -PTableSimpleIT -P with-integration-tests
+
+# Single IT test class — Table model simple
+mvn clean verify -DskipUTs -Dit.test=ClassName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -P with-integration-tests -am -PTableSimpleIT
+
+# Integration tests — Table model cluster
+mvn clean verify -DskipUTs -pl integration-test -am -PTableClusterIT -P with-integration-tests
+
+# Single IT test class — Table model cluster
+mvn clean verify -DskipUTs -Dit.test=ClassName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -P with-integration-tests -am -PTableClusterIT
+
+
+# Before running ITs in IDE for the first time (generates template-node):
+mvn clean package -DskipTests -pl integration-test -am -P with-integration-tests
+```
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000000..fd152a916ee
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,22 @@
+<!--
+
+ 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.
+
+-->
+
+See [AGENTS.md](./AGENTS.md) for all project guidelines, code style rules, build commands, and test instructions.
\ No newline at end of file