This is an automated email from the ASF dual-hosted git repository. JackieTien97 pushed a commit to branch ty/consolidate-agent-instructions in repository https://gitbox.apache.org/repos/asf/iotdb.git
commit 000b215868182939fd6230a791dae7546b64e30c Author: JackieTien97 <[email protected]> AuthorDate: Wed Oct 21 11:58:41 2026 +0800 [Docs] Consolidate repository agent instructions in AGENTS.md --- AGENTS.md | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- CLAUDE.md | 178 ------------------------------------------------------- CONTRIBUTING.md | 21 +++++++ THREAT_MODEL.md | 4 +- pom.xml | 1 - 5 files changed, 202 insertions(+), 182 deletions(-) diff --git a/AGENTS.md b/AGENTS.md deleted file mode 120000 index 681311eb9cf..00000000000 --- a/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -CLAUDE.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..cb1d54cae57 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,179 @@ +<!-- + + 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. + +--> + +# AGENTS.md + +This file provides repository-wide guidance for coding agents working on Apache IoTDB. +For setup and compatibility notes, see [Coding agents](CONTRIBUTING.md#coding-agents). + +## Project Overview + +Apache IoTDB is a time series database for IoT data. It uses a distributed architecture with ConfigNodes (metadata/coordination) and DataNodes (storage/query). Data is stored in TsFile columnar format (separate repo: https://github.com/apache/tsfile). Current version is 2.0.11-SNAPSHOT. + +## Build Commands + +```bash +# Full build (skip tests) +mvn clean package -pl distribution -am -DskipTests + +# Build a specific module (e.g., datanode) +mvn clean package -pl iotdb-core/datanode -am -DskipTests + +# Run unit tests for a specific module +mvn clean test -pl iotdb-core/datanode + +# Run a single test class +mvn clean test -pl iotdb-core/datanode -Dtest=ClassName + +# Run a single test method +mvn clean test -pl iotdb-core/datanode -Dtest=ClassName#methodName + +# Build with Chinese log & error messages +mvn clean package -pl distribution -am -DskipTests -P with-zh-locale + +# Format code (requires JDK 17+; auto-skipped on JDK <17) +mvn spotless:apply + +# Check formatting without applying +mvn spotless:check +``` + +## Integration Tests + +Before editing or running integration tests, read and follow +[integration-test/AGENTS.md](integration-test/AGENTS.md). It contains the IT authoring rules, +formatting and build commands, test profiles, targeted verification, and Edge/IDE instructions. +Keep IT-specific rules and commands in that module-level file. + +## Code Style + +- **Apache License header**: Every new file committed to the repository MUST include the Apache License 2.0 header. Use the comment syntax appropriate for the file type (e.g., `<!-- -->` for `.md`, `/* */` for `.java`, `#` for `.properties`/`.py`). JSON files are exempt (no comment syntax). Refer to existing files in the repo for the exact format. +- **Spotless** with Google Java Format (GOOGLE style). Import order: `org.apache.iotdb`, blank, `javax`, `java`, static. +- **Checkstyle** is also configured (see `checkstyle.xml` at project root). +- Java source/target level is 17 (compiled with `maven.compiler.release=17` on JDK 17+). + +## Architecture + +### Node Types + +- **ConfigNode** (`iotdb-core/confignode`): Manages cluster metadata, schema regions, data regions, partition tables. Coordinates via Ratis consensus. +- **DataNode** (`iotdb-core/datanode`): Handles data storage, query execution, and client connections. The main server component. +- **AINode** (`iotdb-core/ainode`): Python-based node for AI/ML inference tasks. + +### Edge Distribution + +- `EdgeNode` (`iotdb-core/confignode/src/main/java/org/apache/iotdb/edge/EdgeNode.java`) starts the ConfigNode and DataNode in one JVM for resource-constrained single-node deployments. +- `distribution/src/assembly/edge.xml` produces the additional `apache-iotdb-<version>-edge-bin.zip` artifact. Keep its `edge-bin` assembly id unique so it cannot replace an existing attached artifact. +- Edge-specific system defaults live under `iotdb-core/node-commons/src/assembly/resources/conf/edge/`. Standard node, all-in-one, and integration-test assemblies must continue to exclude `edge/**`. +- Edge launchers must reuse the configuration-aware port checks in `scripts/conf/iotdb-common.sh`. Stop scripts must match both the `EdgeNode` main class and the exact `IOTDB_HOME`; never fall back to a global process-name kill. +- Package node-independent tools that work with the combined process. Exclude scripts that require standalone node launchers or environment files, including destructive, daemon-management, and health-check scripts. +- After packaging changes, run a clean distribution build, check that every existing distribution artifact is still produced, and inspect the Edge zip contents and startup/shutdown behavior. + +### Dual Data Model + +IoTDB supports two data models operating on the same storage: +- **Tree model**: Traditional IoT hierarchy (e.g., `root.ln.wf01.wt01.temperature`). SQL uses path-based addressing. +- **Table model** (relational): SQL table semantics. Grammar lives in `iotdb-core/relational-grammar/`. Query plan code under `queryengine/plan/relational/`. + +### Key DataNode Subsystems (`iotdb-core/datanode`) + +- **queryengine**: SQL parsing, planning, optimization, and execution. + - `plan/parser/` - ANTLR-based SQL parser + - `plan/statement/` - AST statement nodes + - `plan/planner/` - Logical and physical planning (tree model: `TreeModelPlanner`, table model: under `plan/relational/`) + - `plan/optimization/` - Query optimization rules + - `execution/operator/` - Physical operators (volcano-style iterator model) + - `execution/exchange/` - Inter-node data exchange + - `execution/fragment/` - Distributed query fragment management +- **storageengine**: Write path, memtable, flush, WAL, compaction, TsFile management. + - `dataregion/` - DataRegion lifecycle, memtable, flush, compaction + - `dataregion/wal/` - Write-ahead log + - `buffer/` - Memory buffer management +- **schemaengine**: Schema (timeseries metadata) management. +- **pipe**: Data sync/replication framework (source -> processor -> sink pipeline). +- **consensus**: DataNode-side consensus integration. +- **subscription**: Client subscription service for streaming data changes. + +### Consensus (`iotdb-core/consensus`) + +Pluggable consensus protocols: Simple (single-node), Ratis (Raft-based), IoT Consensus (optimized for IoT writes). Factory pattern via `ConsensusFactory`. + +### Protocol Layer (`iotdb-protocol/`) + +Thrift IDL definitions for RPC between nodes. Generated sources are produced automatically during build. Sub-modules: `thrift-commons`, `thrift-confignode`, `thrift-datanode`, `thrift-consensus`, `thrift-ainode`. + +### Client Libraries (`iotdb-client/`) + +- `session/` - Java Session API (primary client interface) +- `jdbc/` - JDBC driver +- `cli/` - Command-line client +- `client-cpp/`, `client-go/`, `client-py/` - Multi-language clients +- `service-rpc/` - Shared Thrift service definitions + +### API Layer (`iotdb-api/`) + +Extension point interfaces: `udf-api` (user-defined functions), `trigger-api` (event triggers), `pipe-api` (data sync plugins), `external-api`, `external-service-api`. + +## IDE Setup + +After `mvn package`, right-click the root project in IntelliJ and choose "Maven -> Reload Project" to add generated source roots (Thrift and ANTLR). + +Generated source directories that need to be on the source path: +- `**/target/generated-sources/thrift` +- `**/target/generated-sources/antlr4` + +## Common Pitfalls + +### Build + +- **Missing Thrift compiler**: The local machine may not have the `thrift` binary installed. Running `mvn clean package -pl <module> -am -DskipTests` will fail at the `iotdb-thrift` module. **Workaround**: To verify your changes compile, use `mvn compile -pl <module>` (without `-am` or `clean`) to leverage existing target caches. +- **Pre-existing compilation errors in unrelated modules**: The datanode module may have pre-existing compile errors in other subsystems (e.g., pipe, copyto) that cause `mvn clean test -pl iotdb-core/datanode -Dtest=XxxTest` to fail during compilation. **Workaround**: First run `mvn compile -pl iotdb-core/datanode` to confirm your changed files compile successfully. If the errors are in files you did not modify, they are pre-existing and do not affect your changes. +- **Single-module / no-`clean` compiles hide cross-module and i18n errors**: `mvn compile -pl <module>` (the thrift workaround above) builds only that module against the **installed** jars in `~/.m2` and the existing `target/` classes; an incremental `mvn test-compile` without `clean` reuses stale `target/*.class`. If you add/rename a `*Messages` constant (or any cross-module API) in module B but `~/.m2`/`target/` still holds B's old artifact, module A referencing the new symbol compiles [...] + +### i18n (Chinese Messages) + +The project uses compile-time i18n via the `build-helper-maven-plugin`. The property `i18n.locale` (default: `en`) controls which source directory is added: `src/main/i18n/${i18n.locale}`. Activating `-P with-zh-locale` sets `i18n.locale=zh`, swapping English message constant classes for Chinese ones. Each module that participates has both `src/main/i18n/en/` and `src/main/i18n/zh/` directories containing Java classes with identical structure but different string literals. + +**Rule — never inline a user-facing English string literal.** Every string a user, operator, or log reader will see MUST be a `public static final String` constant in the module's `*Messages` class (e.g. `DataNodeQueryMessages`), referenced as `MessagesClass.CONSTANT` — never a `"raw literal"`. This applies to: `LOGGER/log.info|warn|error|debug|trace(...)`, `throw new …Exception(…)`, `super(…)` in exception constructors, `resp.setMessage(…)`, the message arg of `requireNonNull/checkArgum [...] + +**Naming a new constant** (deterministic, matches existing files): `<PREFIX>_<NORMALIZED>_<HASH>` where `PREFIX` is `LOG_` for `LOGGER`/log calls, `MESSAGE_` for `setMessage(...)`, and `EXCEPTION_` for `throw new …(…)`, `super(…)`, and the message arg of `requireNonNull/checkArgument/checkState/checkNotNull` (the three prefixes the codebase already uses — ~`LOG_`/`MESSAGE_`/`EXCEPTION_`); `NORMALIZED` is the English value uppercased with non-alphanumeric runs collapsed to `_` and `%s`/`% [...] + +**Verify before commit**: +- `mvn spotless:apply -pl <module>` (the PostToolUse formatter does not add the i18n import; spotless does). +- Compile **both** locales: `mvn test-compile -DskipTests` AND `mvn test-compile -P with-zh-locale -DskipTests` (the `.github/workflows/zh-locale-compile.yml` CI enforces the zh build). +- The `en` and `zh` files must stay in key parity (same constant names) with identical format-specifier counts; a raw-literal scan of main java must return nothing. + +### Code Style + +- **Always run `mvn spotless:apply` after editing Java files**: Spotless runs `spotless:check` automatically during the `compile` phase. Format violations cause an immediate BUILD FAILURE. Make it a habit to run `mvn spotless:apply -pl <module>` right after editing, not at the end. +- **Always run `black` and `isort` after editing Python files under `iotdb-core/ainode/`**: The AINode Code Style Check CI runs `black --check .` and `isort --check-only --profile black .` on that directory. Run `cd iotdb-core/ainode && black . && isort --profile black .` before committing. Requires `pip install black==25.1.0 isort==6.0.1`. +- **Gson version compatibility**: `JsonObject.isEmpty()` / `JsonArray.isEmpty()` may not be available in the Gson version used by this project. Use `size() > 0` instead and add a comment explaining why. + +## Git Commit + +- Do NOT add `Co-Authored-By` trailer to commit messages. + +## Security + +Security model: [SECURITY.md](./SECURITY.md) + +Agents that scan this repository should consult `SECURITY.md` and the +threat model it links before reporting issues. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 5ef345696db..00000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,178 +0,0 @@ -<!-- - - 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. - ---> - -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -Apache IoTDB is a time series database for IoT data. It uses a distributed architecture with ConfigNodes (metadata/coordination) and DataNodes (storage/query). Data is stored in TsFile columnar format (separate repo: https://github.com/apache/tsfile). Current version is 2.0.11-SNAPSHOT. - -## Build Commands - -```bash -# Full build (skip tests) -mvn clean package -pl distribution -am -DskipTests - -# Build a specific module (e.g., datanode) -mvn clean package -pl iotdb-core/datanode -am -DskipTests - -# Run unit tests for a specific module -mvn clean test -pl iotdb-core/datanode - -# Run a single test class -mvn clean test -pl iotdb-core/datanode -Dtest=ClassName - -# Run a single test method -mvn clean test -pl iotdb-core/datanode -Dtest=ClassName#methodName - -# Build with Chinese log & error messages -mvn clean package -pl distribution -am -DskipTests -P with-zh-locale - -# Format code (requires JDK 17+; auto-skipped on JDK <17) -mvn spotless:apply - -# Check formatting without applying -mvn spotless:check -``` - -## Integration Tests - -Before editing or running integration tests, read and follow -[integration-test/AGENTS.md](integration-test/AGENTS.md). It contains the IT authoring rules, -formatting and build commands, test profiles, targeted verification, and Edge/IDE instructions. -Keep IT-specific rules and commands in that module-level file. - -## Code Style - -- **Apache License header**: Every new file committed to the repository MUST include the Apache License 2.0 header. Use the comment syntax appropriate for the file type (e.g., `<!-- -->` for `.md`, `/* */` for `.java`, `#` for `.properties`/`.py`). JSON files are exempt (no comment syntax). Refer to existing files in the repo for the exact format. -- **Spotless** with Google Java Format (GOOGLE style). Import order: `org.apache.iotdb`, blank, `javax`, `java`, static. -- **Checkstyle** is also configured (see `checkstyle.xml` at project root). -- Java source/target level is 17 (compiled with `maven.compiler.release=17` on JDK 17+). - -## Architecture - -### Node Types - -- **ConfigNode** (`iotdb-core/confignode`): Manages cluster metadata, schema regions, data regions, partition tables. Coordinates via Ratis consensus. -- **DataNode** (`iotdb-core/datanode`): Handles data storage, query execution, and client connections. The main server component. -- **AINode** (`iotdb-core/ainode`): Python-based node for AI/ML inference tasks. - -### Edge Distribution - -- `EdgeNode` (`iotdb-core/confignode/src/main/java/org/apache/iotdb/edge/EdgeNode.java`) starts the ConfigNode and DataNode in one JVM for resource-constrained single-node deployments. -- `distribution/src/assembly/edge.xml` produces the additional `apache-iotdb-<version>-edge-bin.zip` artifact. Keep its `edge-bin` assembly id unique so it cannot replace an existing attached artifact. -- Edge-specific system defaults live under `iotdb-core/node-commons/src/assembly/resources/conf/edge/`. Standard node, all-in-one, and integration-test assemblies must continue to exclude `edge/**`. -- Edge launchers must reuse the configuration-aware port checks in `scripts/conf/iotdb-common.sh`. Stop scripts must match both the `EdgeNode` main class and the exact `IOTDB_HOME`; never fall back to a global process-name kill. -- Package node-independent tools that work with the combined process. Exclude scripts that require standalone node launchers or environment files, including destructive, daemon-management, and health-check scripts. -- After packaging changes, run a clean distribution build, check that every existing distribution artifact is still produced, and inspect the Edge zip contents and startup/shutdown behavior. - -### Dual Data Model - -IoTDB supports two data models operating on the same storage: -- **Tree model**: Traditional IoT hierarchy (e.g., `root.ln.wf01.wt01.temperature`). SQL uses path-based addressing. -- **Table model** (relational): SQL table semantics. Grammar lives in `iotdb-core/relational-grammar/`. Query plan code under `queryengine/plan/relational/`. - -### Key DataNode Subsystems (`iotdb-core/datanode`) - -- **queryengine**: SQL parsing, planning, optimization, and execution. - - `plan/parser/` - ANTLR-based SQL parser - - `plan/statement/` - AST statement nodes - - `plan/planner/` - Logical and physical planning (tree model: `TreeModelPlanner`, table model: under `plan/relational/`) - - `plan/optimization/` - Query optimization rules - - `execution/operator/` - Physical operators (volcano-style iterator model) - - `execution/exchange/` - Inter-node data exchange - - `execution/fragment/` - Distributed query fragment management -- **storageengine**: Write path, memtable, flush, WAL, compaction, TsFile management. - - `dataregion/` - DataRegion lifecycle, memtable, flush, compaction - - `dataregion/wal/` - Write-ahead log - - `buffer/` - Memory buffer management -- **schemaengine**: Schema (timeseries metadata) management. -- **pipe**: Data sync/replication framework (source -> processor -> sink pipeline). -- **consensus**: DataNode-side consensus integration. -- **subscription**: Client subscription service for streaming data changes. - -### Consensus (`iotdb-core/consensus`) - -Pluggable consensus protocols: Simple (single-node), Ratis (Raft-based), IoT Consensus (optimized for IoT writes). Factory pattern via `ConsensusFactory`. - -### Protocol Layer (`iotdb-protocol/`) - -Thrift IDL definitions for RPC between nodes. Generated sources are produced automatically during build. Sub-modules: `thrift-commons`, `thrift-confignode`, `thrift-datanode`, `thrift-consensus`, `thrift-ainode`. - -### Client Libraries (`iotdb-client/`) - -- `session/` - Java Session API (primary client interface) -- `jdbc/` - JDBC driver -- `cli/` - Command-line client -- `client-cpp/`, `client-go/`, `client-py/` - Multi-language clients -- `service-rpc/` - Shared Thrift service definitions - -### API Layer (`iotdb-api/`) - -Extension point interfaces: `udf-api` (user-defined functions), `trigger-api` (event triggers), `pipe-api` (data sync plugins), `external-api`, `external-service-api`. - -## IDE Setup - -After `mvn package`, right-click the root project in IntelliJ and choose "Maven -> Reload Project" to add generated source roots (Thrift and ANTLR). - -Generated source directories that need to be on the source path: -- `**/target/generated-sources/thrift` -- `**/target/generated-sources/antlr4` - -## Common Pitfalls - -### Build - -- **Missing Thrift compiler**: The local machine may not have the `thrift` binary installed. Running `mvn clean package -pl <module> -am -DskipTests` will fail at the `iotdb-thrift` module. **Workaround**: To verify your changes compile, use `mvn compile -pl <module>` (without `-am` or `clean`) to leverage existing target caches. -- **Pre-existing compilation errors in unrelated modules**: The datanode module may have pre-existing compile errors in other subsystems (e.g., pipe, copyto) that cause `mvn clean test -pl iotdb-core/datanode -Dtest=XxxTest` to fail during compilation. **Workaround**: First run `mvn compile -pl iotdb-core/datanode` to confirm your changed files compile successfully. If the errors are in files you did not modify, they are pre-existing and do not affect your changes. -- **Single-module / no-`clean` compiles hide cross-module and i18n errors**: `mvn compile -pl <module>` (the thrift workaround above) builds only that module against the **installed** jars in `~/.m2` and the existing `target/` classes; an incremental `mvn test-compile` without `clean` reuses stale `target/*.class`. If you add/rename a `*Messages` constant (or any cross-module API) in module B but `~/.m2`/`target/` still holds B's old artifact, module A referencing the new symbol compiles [...] - -### i18n (Chinese Messages) - -The project uses compile-time i18n via the `build-helper-maven-plugin`. The property `i18n.locale` (default: `en`) controls which source directory is added: `src/main/i18n/${i18n.locale}`. Activating `-P with-zh-locale` sets `i18n.locale=zh`, swapping English message constant classes for Chinese ones. Each module that participates has both `src/main/i18n/en/` and `src/main/i18n/zh/` directories containing Java classes with identical structure but different string literals. - -**Rule — never inline a user-facing English string literal.** Every string a user, operator, or log reader will see MUST be a `public static final String` constant in the module's `*Messages` class (e.g. `DataNodeQueryMessages`), referenced as `MessagesClass.CONSTANT` — never a `"raw literal"`. This applies to: `LOGGER/log.info|warn|error|debug|trace(...)`, `throw new …Exception(…)`, `super(…)` in exception constructors, `resp.setMessage(…)`, the message arg of `requireNonNull/checkArgum [...] - -**Naming a new constant** (deterministic, matches existing files): `<PREFIX>_<NORMALIZED>_<HASH>` where `PREFIX` is `LOG_` for `LOGGER`/log calls, `MESSAGE_` for `setMessage(...)`, and `EXCEPTION_` for `throw new …(…)`, `super(…)`, and the message arg of `requireNonNull/checkArgument/checkState/checkNotNull` (the three prefixes the codebase already uses — ~`LOG_`/`MESSAGE_`/`EXCEPTION_`); `NORMALIZED` is the English value uppercased with non-alphanumeric runs collapsed to `_` and `%s`/`% [...] - -**Verify before commit**: -- `mvn spotless:apply -pl <module>` (the PostToolUse formatter does not add the i18n import; spotless does). -- Compile **both** locales: `mvn test-compile -DskipTests` AND `mvn test-compile -P with-zh-locale -DskipTests` (the `.github/workflows/zh-locale-compile.yml` CI enforces the zh build). -- The `en` and `zh` files must stay in key parity (same constant names) with identical format-specifier counts; a raw-literal scan of main java must return nothing. - -### Code Style - -- **Always run `mvn spotless:apply` after editing Java files**: Spotless runs `spotless:check` automatically during the `compile` phase. Format violations cause an immediate BUILD FAILURE. Make it a habit to run `mvn spotless:apply -pl <module>` right after editing, not at the end. -- **Always run `black` and `isort` after editing Python files under `iotdb-core/ainode/`**: The AINode Code Style Check CI runs `black --check .` and `isort --check-only --profile black .` on that directory. Run `cd iotdb-core/ainode && black . && isort --profile black .` before committing. Requires `pip install black==25.1.0 isort==6.0.1`. -- **Gson version compatibility**: `JsonObject.isEmpty()` / `JsonArray.isEmpty()` may not be available in the Gson version used by this project. Use `size() > 0` instead and add a comment explaining why. - -## Git Commit - -- Do NOT add `Co-Authored-By` trailer to commit messages. - -## Security - -Security model: [SECURITY.md](./SECURITY.md) - -Agents that scan this repository should consult `SECURITY.md` and the -threat model it links before reporting issues. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7a5191cad6e..c369a96f2be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,6 +79,27 @@ Precautions: * Do not use special Unicode chars, e.g., U+FF1A * Do not use the character of dollar (as we will use Latex to generate pdf files) +## Coding agents + +[AGENTS.md](AGENTS.md) is the shared entry point for repository-wide build, testing, and coding +instructions. Follow any module-level `AGENTS.md` as well, including +[integration-test/AGENTS.md](integration-test/AGENTS.md) when working on integration tests. +Maintain shared guidance in these files. + +For Claude Code contributors: + +* Upgrade to a current release. Direct `AGENTS.md` support was introduced in v2.1.277; + v2.1.281 or later is needed for some sessions, including Amazon Bedrock or sessions with + telemetry disabled. +* By default, a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in the working directory + or an ancestor directory takes precedence over `AGENTS.md`. To load both, open `/config` + and set **Project instructions** to `claude-md-and-agents-md`. +* Start a new session after upgrading and check that the repository's `AGENTS.md` appears in + `/memory` (available for directly loaded `AGENTS.md` files since v2.1.280). + +See the [Claude Code loading and configuration rules](https://code.claude.com/docs/en/memory#agentsmd) +for details. + ## Code Formatting We use the [Spotless diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md index 4191f5e07d8..eaf4a7d1b9a 100644 --- a/THREAT_MODEL.md +++ b/THREAT_MODEL.md @@ -24,12 +24,12 @@ limitations under the License. - **Reporting cross-reference:** findings that violate a §8 property should be reported privately per the ASF process (`[email protected]` → `[email protected]`); findings that fall under §3 or §9 will be closed citing this document. - **Provenance legend:** *(documented)* = stated in IoTDB's own docs/repo; *(maintainer)* = confirmed by an IoTDB PMC member through this process; *(inferred)* = reasoned from architecture/domain knowledge, not yet confirmed. The high-stakes inferred claims were routed to §14 and have since been resolved across two PMC review passes; the residual *(inferred)* tags are low-stakes environmental details the PMC can confirm or correct at leisure. - **Draft confidence:** a v0 that has had **two PMC review passes**. First pass (HTHou, issue-comment review 2026-06-03): deployment posture, default-credential disposition, default-enabled protocols (REST/MQTT off; client Thrift SSL off), extension-privilege model, and the resource/DoS line. Second pass (JackieTien97, PR review 2026-06-04): the previously-open items — TsFile/SDK boundary, inter-node posture (trusted-network; no transport encryption), inter-node TLS (none today), cluster [...] -- **What IoTDB is:** Apache IoTDB is a time-series database management system for IoT data — collection, storage, query, and analysis. It runs as a server (standalone, or a distributed cluster of ConfigNodes for metadata/coordination and DataNodes for storage/query), stores data in the TsFile columnar format, and is accessed over a Thrift-based RPC protocol via a SQL-like language and JDBC/session clients. *(documented — README, repo `CLAUDE.md`)* +- **What IoTDB is:** Apache IoTDB is a time-series database management system for IoT data — collection, storage, query, and analysis. It runs as a server (standalone, or a distributed cluster of ConfigNodes for metadata/coordination and DataNodes for storage/query), stores data in the TsFile columnar format, and is accessed over a Thrift-based RPC protocol via a SQL-like language and JDBC/session clients. *(documented — README, repo `AGENTS.md`)* ## §2 Scope and intended use - **Primary use:** an operator-deployed time-series database server, written to by IoT/device data pipelines and read by analytics clients, over the network. IoTDB should generally be treated as operator-deployed infrastructure, deployed inside a **trusted network by default**, with the application/ingestion tier in front of it. *(maintainer — HTHou: "IoTDB should generally be treated as operator-deployed infrastructure … trusted-network-by-default")* -- **Deployment shapes:** standalone single-node, and a distributed cluster (ConfigNode + DataNode roles, optional AINode for model execution, inter-node/control-plane RPC, and consensus). *(documented — repo `CLAUDE.md`)* +- **Deployment shapes:** standalone single-node, and a distributed cluster (ConfigNode + DataNode roles, optional AINode for model execution, inter-node/control-plane RPC, and consensus). *(documented — repo `AGENTS.md`)* - **Caller roles** (this is a network service, not an in-process library — the "caller" splits): - **client** — connects over the Thrift session protocol / JDBC / SQL; authenticates with a username/password and is constrained by RBAC privileges. Treated as **untrusted** beyond its granted privileges. The authenticated client RPC surface is the main in-model boundary. *(maintainer — HTHou: "the client RPC surface as the main in-model boundary")* - **operator/admin** — the `root` superuser and whoever controls the deployment, configs, and the host. **Trusted** for the instance. *(inferred)* diff --git a/pom.xml b/pom.xml index 65e622de726..c6bbd90cdda 100644 --- a/pom.xml +++ b/pom.xml @@ -706,7 +706,6 @@ <exclude>**/.gitmodules</exclude> <exclude>**/.git-blame-ignore-revs</exclude> <exclude>**/git.properties</exclude> - <exclude>AGENTS.md</exclude> <!-- Maven related files --> <exclude>**/target/**</exclude> <!-- Eclipse related files -->
