VGalaxies commented on code in PR #2998:
URL: https://github.com/apache/hugegraph/pull/2998#discussion_r3195924284
##########
AGENTS.md:
##########
@@ -1,261 +1,107 @@
# AGENTS.md
-This file provides guidance to an AI coding tool when working with code in
this repository.
+Single source of truth for AI coding agents.
+README.md covers human-facing deployment/ecosystem context; only consult it on
demand.
-## Project Overview
+## Stack & Modules
-Apache HugeGraph is a fast-speed and highly-scalable graph database that
supports billions of vertices and edges. It is compliant with Apache TinkerPop
3 and supports both Gremlin and Cypher query languages.
+Apache HugeGraph — Apache TinkerPop 3 compliant graph database.
+Java 11+, Maven 3.5+. Version managed via `${revision}` (currently `1.8.0`).
-**Technology Stack**:
-- Java 11+ (required)
-- Apache Maven 3.5+
-- Apache TinkerPop 3.5.1
-- gRPC for distributed communication
-- RocksDB as default storage backend
-
-## Architecture
-
-### Multi-Module Structure
-
-This is a Maven multi-module project with 7 main modules:
-
-1. **hugegraph-server**: Core graph engine, REST APIs, and backend
implementations (13 submodules)
-2. **hugegraph-pd**: Placement Driver (meta server) for distributed
deployments (8 submodules)
-3. **hugegraph-store**: Distributed storage backend with RocksDB and Raft (9
submodules)
-4. **hugegraph-commons**: Shared utilities (locks, configs, RPC framework)
-5. **hugegraph-struct**: Data structure definitions
-6. **install-dist**: Distribution packaging
-7. **hugegraph-cluster-test**: Cluster integration tests
-
-### Three-Tier Architecture
-
-```bash
-Client Layer (Gremlin/Cypher queries, REST APIs)
- ↓
-Server Layer (hugegraph-server)
- ├─ REST API Layer (hugegraph-api): GraphAPI, SchemaAPI, GremlinAPI,
CypherAPI, AuthAPI
- ├─ Graph Engine Layer (hugegraph-core): Schema management, traversal
optimization, task scheduling
- └─ Backend Interface: Abstraction over storage backends
- ↓
-Storage Layer (pluggable backends)
- ├─ RocksDB (default, embedded)
- ├─ HStore (distributed, production)
- └─ Legacy: MySQL, PostgreSQL, Cassandra, ScyllaDB, HBase, Palo
+```
+Client (Gremlin / Cypher / REST)
+ │
+Server = hugegraph-server
+ ├─ hugegraph-api REST, Gremlin/Cypher, auth
+ ├─ hugegraph-core engine, schema, traversal, BackendStore interface
+ └─ Backend impls rocksdb (default, embedded) │ hstore (distributed)
+ ▼
+ hugegraph-pd (placement) + hugegraph-store (Raft)
```
-### Distributed Components (Optional)
-
-For production distributed deployments:
-- **hugegraph-pd**: Service discovery, partition management, metadata
coordination
-- **hugegraph-store**: Distributed storage with Raft consensus (typically 3+
nodes)
-- **hugegraph-server**: Multiple server instances (typically 3+)
-
-All inter-service communication uses gRPC with Protocol Buffers.
+Top-level modules: `hugegraph-server` · `hugegraph-pd` · `hugegraph-store` ·
+`hugegraph-commons` (shared utils & RPC) · `hugegraph-struct` (data types; dep
of PD/Store).
-### Key Architectural Patterns
+Server submodules worth knowing: `hugegraph-core`, `hugegraph-api`,
+`hugegraph-rocksdb`, `hugegraph-hstore`, `hugegraph-test`, `hugegraph-dist`.
-1. **Pluggable Backend Architecture**: Storage backends implement the
`BackendStore` interface, allowing new backends without modifying core code
-2. **TinkerPop Compliance**: Full Apache TinkerPop 3 implementation with
custom optimization strategies
-3. **gRPC Communication**: All distributed components communicate via gRPC
(proto definitions in `*/grpc/` directories)
-4. **Multi-Language Queries**: Native Gremlin support + OpenCypher
implementation in `hugegraph-api/opencypher`
+## Code Search Anchors
-## Build & Development Commands
+| Area | Path |
+|---|---|
+| Graph engine |
`hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/` |
+| REST APIs |
`hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/` |
+| Backend interface |
`hugegraph-server/hugegraph-core/.../backend/store/BackendStore.java` |
+| Auth | `hugegraph-server/hugegraph-api/.../api/auth/` |
+| gRPC protos | `hugegraph-{pd,store}/hg-{pd,store}-grpc/src/main/proto/` |
-### Prerequisites Check
-```bash
-# Verify Java version (11+ required)
-java -version
+Config roots (under each dist module's `src/assembly/static/conf/`):
+- Server — `hugegraph.properties`, `rest-server.properties`,
`gremlin-server.yaml`
+- PD / Store — `application.yml`
-# Verify Maven version (3.5+ required)
-mvn -version
-```
+## Build
-### Full Build
```bash
-# Clean build with all modules
+# All modules
mvn clean install -DskipTests
-# Build with tests
-mvn clean install
-
-# Build specific module (e.g., server only)
+# Single module
mvn clean install -pl hugegraph-server -am -DskipTests
```
-### Testing
+Distributed build order (for HStore-enabled dev):
-#### Server Module Tests
```bash
-# Unit tests (memory backend)
-mvn test -pl hugegraph-server/hugegraph-test -am -P unit-test
-
-# Core tests with specific backend
-mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory
-mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,rocksdb
-mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,hbase
-
-# API tests with backend
-mvn test -pl hugegraph-server/hugegraph-test -am -P api-test,rocksdb
-
-# TinkerPop compliance tests (for release branches)
-mvn test -pl hugegraph-server/hugegraph-test -am -P
tinkerpop-structure-test,memory
-mvn test -pl hugegraph-server/hugegraph-test -am -P
tinkerpop-process-test,memory
-```
-
-#### PD & Store Module Tests
-```bash
-# Build and test hugegraph-struct first (dependency)
-mvn install -pl hugegraph-struct -am -DskipTests
-
-# Test PD module
-mvn test -pl hugegraph-pd/hg-pd-test -am
-
-# Test Store module
-mvn test -pl hugegraph-store/hg-store-test -am
+mvn install -pl hugegraph-struct -am -DskipTests # 1. shared data types
+mvn clean package -pl hugegraph-pd -am -DskipTests # 2. placement driver
+mvn clean package -pl hugegraph-store -am -DskipTests # 3. distributed
storage
+mvn clean package -pl hugegraph-server -am -DskipTests # 4. server
```
-### Code Quality & Validation
+Runtime scripts (human-run) live in
`hugegraph-server/hugegraph-dist/src/assembly/static/bin/`:
+`init-store.sh`, `start-hugegraph.sh`, `stop-hugegraph.sh`.
-```bash
-# License header check (Apache RAT)
-mvn apache-rat:check
-
-# Code style check (EditorConfig)
-mvn editorconfig:check
+## Testing
-# Compile with warnings
-mvn clean compile -Dmaven.javadoc.skip=true
-```
+Server tests implicitly prefix `mvn test -pl hugegraph-server/hugegraph-test
-am`:
-### Running the Server
+| Profile | Suffix |
+|---|---|
+| Unit | `-P unit-test` |
+| Core | `-P core-test,rocksdb` (swap `rocksdb` for `memory` / `hbase`) |
+| API | `-P api-test,rocksdb` |
+| TinkerPop structure / process | `-P
tinkerpop-{structure,process}-test,memory` |
+| Single class | `-P core-test,rocksdb -Dtest=YourTestClass` |
-Scripts are located in
`hugegraph-server/hugegraph-dist/src/assembly/static/bin/`:
+PD / Store tests (need `hugegraph-struct` installed first):
```bash
-# Initialize storage backend
-bin/init-store.sh
-
-# Start server
-bin/start-hugegraph.sh
-
-# Stop server
-bin/stop-hugegraph.sh
-
-# Gremlin console
-bin/gremlin-console.sh
-
-# Enable authentication
-bin/enable-auth.sh
-```
-
-### Creating Distribution Package
-
-```bash
-# Build distribution tarball (auto-enabled by default)
-mvn clean package -DskipTests
-
-# Skip assembly creation (if needed)
-mvn clean package -DskipTests -Dskip-assembly-hugegraph
-
-# Output: install-dist/target/hugegraph-<version>.tar.gz
-```
-
-## Important File Locations
-
-### Configuration Files
-- Server configs: `hugegraph-server/hugegraph-dist/src/assembly/static/conf/`
- - `hugegraph.properties` - Main server configuration
- - `rest-server.properties` - REST API settings
- - `gremlin-server.yaml` - Gremlin server configuration
-- PD configs: `hugegraph-pd/hg-pd-dist/src/assembly/static/conf/`
-- Store configs: `hugegraph-store/hg-store-dist/src/assembly/static/conf/`
-
-### Proto Definitions (gRPC)
-- PD protos: `hugegraph-pd/hg-pd-grpc/src/main/proto/`
-- Store protos: `hugegraph-store/hg-store-grpc/src/main/proto/`
-
-### Core Implementation Paths
-- Graph engine:
`hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/`
-- REST APIs:
`hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/`
-- Backend implementations: `hugegraph-server/hugegraph-{backend}/` (e.g.,
`hugegraph-rocksdb`)
-
-## Development Workflow
-
-### Code Style
-Configure your IDE to use `.editorconfig` for code style and
`style/checkstyle.xml` for Checkstyle rules
-
-### Adding Dependencies
-
-When adding third-party dependencies:
-1. Add license files to `install-dist/release-docs/licenses/`
-2. Declare dependency in `install-dist/release-docs/LICENSE`
-3. Append NOTICE info to `install-dist/release-docs/NOTICE` (if upstream has
NOTICE)
-4. Update `install-dist/scripts/dependency/known-dependencies.txt` (run
`regenerate_known_dependencies.sh`)
-
-### Backend Development
-
-When working on storage backends:
-- All backends extend `hugegraph-server/hugegraph-core` abstractions
-- Implement the `BackendStore` interface
-- Each backend is a separate Maven module in `hugegraph-server/`
-- Backend selection is configured in `hugegraph.properties` via the `backend`
property
-
-### gRPC Protocol Changes
-
-When modifying `.proto` files:
-- Generated Java code goes to `*/grpc/` packages (excluded from Apache RAT
checks)
-- Run `mvn clean compile` to regenerate gRPC stubs
-- Generated files are in `target/generated-sources/protobuf/`
-
-### Authentication System
-
-Authentication is optional and disabled by default:
-- Enable via `bin/enable-auth.sh` or configuration
-- Auth implementation:
`hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/`
-- Multi-level: Users, Groups, Projects, Targets, Access control
-- Required for production deployments
-
-## Common Workflows
-
-### Running a Single Test Class
-```bash
-# Use Maven's -Dtest parameter
-mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory
-Dtest=YourTestClass
+mvn install -pl hugegraph-struct -am -DskipTests
+mvn test -pl hugegraph-pd/hg-pd-test -am # or hg-store-test
Review Comment:
Can we spell out the Store test command here instead of relying on `# or
hg-store-test`? Agents will likely copy the line literally, so adding `mvn test
-pl hugegraph-store/hg-store-test -am` would make PD/Store coverage unambiguous.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
