Skip to content

Commit c8ecb0c

Browse files
imbajinimbajin
committed
Update AGENTS.md
1 parent b01e5b9 commit c8ecb0c

1 file changed

Lines changed: 75 additions & 78 deletions

File tree

‎AGENTS.md‎

Lines changed: 75 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,107 @@
11
# AGENTS.md
22

3-
Development reference for AI coding agents. See [README.md](README.md) if the task really needs project overview or architecture context.
3+
Single source of truth for AI coding agents.
4+
README.md covers human-facing deployment/ecosystem context; only consult it on demand.
45

5-
## Key Architectural Patterns
6+
## Stack & Modules
67

7-
1. **Pluggable Backend Architecture**: Storage backends implement the `BackendStore` interface — new backends require no core changes. Active backends: RocksDB (default/embedded), HStore (distributed)
8-
2. **gRPC Communication**: All distributed components (PD, Store, Server) communicate via gRPC. Proto definitions in `*/grpc/` directories
9-
3. **Multi-Language Queries**: Native Gremlin support(Main) + OpenCypher translation(Backup)
8+
Apache HugeGraph — Apache TinkerPop 3 compliant graph database.
9+
Java 11+, Maven 3.5+. Version managed via `${revision}` (currently `1.8.0`).
1010

11-
## Build Commands
12-
13-
Requires Java 11 for compilation and testing.
14-
15-
```bash
16-
# Full build (all modules)
17-
mvn clean install -DskipTests
18-
19-
# Single module (e.g., server only)
20-
mvn clean install -pl hugegraph-server -am -DskipTests
11+
```
12+
Client (Gremlin / Cypher / REST)
13+
│
14+
Server = hugegraph-server
15+
├─ hugegraph-api REST, Gremlin/Cypher, auth
16+
├─ hugegraph-core engine, schema, traversal, BackendStore interface
17+
└─ Backend impls rocksdb (default, embedded) │ hstore (distributed)
18+
▼
19+
hugegraph-pd (placement) + hugegraph-store (Raft)
2120
```
2221

23-
## Testing
24-
25-
All test commands target `hugegraph-server/hugegraph-test` with `-am` flag:
26-
27-
| Profile | Command |
28-
|---------|---------|
29-
| Unit tests | `mvn test -P unit-test` |
30-
| Core tests | `mvn test -P core-test,rocksdb` |
31-
| API tests | `mvn test -P api-test,rocksdb` |
32-
| TinkerPop structure | `mvn test -P tinkerpop-structure-test,memory` |
33-
| TinkerPop process | `mvn test -P tinkerpop-process-test,memory` |
34-
| Single test class | `mvn test -P core-test,rocksdb -Dtest=YourTestClass` |
22+
Top-level modules: `hugegraph-server` · `hugegraph-pd` · `hugegraph-store` ·
23+
`hugegraph-commons` (shared utils & RPC) · `hugegraph-struct` (data types; dep of PD/Store).
3524

36-
All commands above implicitly start with `mvn test -pl hugegraph-server/hugegraph-test -am`.
25+
Server submodules worth knowing: `hugegraph-core`, `hugegraph-api`,
26+
`hugegraph-rocksdb`, `hugegraph-hstore`, `hugegraph-test`, `hugegraph-dist`.
3727

38-
#### PD & Store Tests
28+
## Code Search Anchors
3929

40-
```bash
41-
# Build dependency first
42-
mvn install -pl hugegraph-struct -am -DskipTests
43-
44-
mvn test -pl hugegraph-pd/hg-pd-test -am
45-
mvn test -pl hugegraph-store/hg-store-test -am
46-
```
30+
| Area | Path |
31+
|---|---|
32+
| Graph engine | `hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/` |
33+
| REST APIs | `hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/` |
34+
| Backend interface | `hugegraph-server/hugegraph-core/.../backend/store/BackendStore.java` |
35+
| Auth | `hugegraph-server/hugegraph-api/.../api/auth/` |
36+
| gRPC protos | `hugegraph-{pd,store}/hg-{pd,store}-grpc/src/main/proto/` |
4737

48-
## Development Conventions
38+
Config roots (under each dist module's `src/assembly/static/conf/`):
39+
- Server — `hugegraph.properties`, `rest-server.properties`, `gremlin-server.yaml`
40+
- PD / Store — `application.yml`
4941

50-
- Any code change (bug fix or feature) must have sufficient test coverage for the affected logic
51-
- Check existing suites in `hugegraph-server/hugegraph-test` before writing new tests
52-
53-
## Code Quality
54-
55-
Run before every commit:
42+
## Build
5643

5744
```bash
58-
mvn editorconfig:format # Apply code style (root .editorconfig)
59-
mvn clean compile -Dmaven.javadoc.skip=true # Compile with warnings
60-
```
61-
62-
Key rules from `.editorconfig`: 100-char line limit, 4-space indent, LF endings, UTF-8.
45+
# All modules
46+
mvn clean install -DskipTests
6347

64-
## Running the Server
48+
# Single module
49+
mvn clean install -pl hugegraph-server -am -DskipTests
50+
```
6551

66-
Scripts in `hugegraph-server/hugegraph-dist/src/assembly/static/bin/`:
52+
Distributed build order (for HStore-enabled dev):
6753

6854
```bash
69-
bin/init-store.sh # Initialize storage backend
70-
bin/start-hugegraph.sh # Start server
71-
bin/stop-hugegraph.sh # Stop server
55+
mvn install -pl hugegraph-struct -am -DskipTests # 1. shared data types
56+
mvn clean package -pl hugegraph-pd -am -DskipTests # 2. placement driver
57+
mvn clean package -pl hugegraph-store -am -DskipTests # 3. distributed storage
58+
mvn clean package -pl hugegraph-server -am -DskipTests # 4. server
7259
```
7360

74-
## Configuration Files
61+
Runtime scripts (human-run) live in `hugegraph-server/hugegraph-dist/src/assembly/static/bin/`:
62+
`init-store.sh`, `start-hugegraph.sh`, `stop-hugegraph.sh`.
7563

76-
| Component | Path | Key Files |
77-
|-----------|------|-----------|
78-
| Server | `hugegraph-server/hugegraph-dist/src/assembly/static/conf/` | `hugegraph.properties`, `rest-server.properties`, `gremlin-server.yaml` |
79-
| PD | `hugegraph-pd/hg-pd-dist/src/assembly/static/conf/` | `application.yml` |
80-
| Store | `hugegraph-store/hg-store-dist/src/assembly/static/conf/` | `application.yml` |
64+
## Testing
8165

82-
## Development Workflows
66+
Server tests implicitly prefix `mvn test -pl hugegraph-server/hugegraph-test -am`:
8367

84-
### Adding Third-Party Dependencies
68+
| Profile | Suffix |
69+
|---|---|
70+
| Unit | `-P unit-test` |
71+
| Core | `-P core-test,rocksdb` (swap `rocksdb` for `memory` / `hbase`) |
72+
| API | `-P api-test,rocksdb` |
73+
| TinkerPop structure / process | `-P tinkerpop-{structure,process}-test,memory` |
74+
| Single class | `-P core-test,rocksdb -Dtest=YourTestClass` |
8575

86-
Follow ASF compliance: update `install-dist/release-docs/` (LICENSE, NOTICE, licenses/) and `install-dist/scripts/dependency/known-dependencies.txt`.
76+
PD / Store tests (need `hugegraph-struct` installed first):
8777

88-
### gRPC Protocol Changes
78+
```bash
79+
mvn install -pl hugegraph-struct -am -DskipTests
80+
mvn test -pl hugegraph-pd/hg-pd-test -am # or hg-store-test
81+
```
8982

90-
When modifying `.proto` files: Run `mvn clean compile` to regenerate gRPC stubs
83+
Before writing new tests, check existing suites under `hugegraph-server/hugegraph-test/`.
9184

92-
### Build Order & Cross-Module Dependencies
85+
## Style & Pre-commit
9386

94-
For distributed development, build in this order:
87+
- Line 100, 4-space indent, LF, UTF-8, **no star imports**
88+
- Commit format: `feat|fix|refactor(module): msg`
89+
- Run before pushing:
90+
```bash
91+
mvn editorconfig:format # enforce code style
92+
mvn clean compile -Dmaven.javadoc.skip=true # surface warnings
93+
```
9594

96-
```bash
97-
mvn install -pl hugegraph-struct -am -DskipTests # 1. Shared data structures
98-
mvn clean package -pl hugegraph-pd -am -DskipTests # 2. Placement Driver
99-
mvn clean package -pl hugegraph-store -am -DskipTests # 3. Distributed storage
100-
mvn clean package -pl hugegraph-server -am -DskipTests # 4. Server
101-
```
95+
## Cross-module notes
10296

103-
Key dependencies: `hugegraph-commons` is shared by all modules. `hugegraph-struct` must be built before PD and Store. Server backends depend on `hugegraph-core`.
97+
- `.proto` edits: `mvn clean compile` regenerates gRPC stubs under
98+
`target/generated-sources/protobuf/` (output packages `*/grpc/` are excluded from Apache RAT).
99+
- Adding a third-party dep: update `install-dist/release-docs/{LICENSE,NOTICE,licenses/}`
100+
and `install-dist/scripts/dependency/known-dependencies.txt`.
101+
- `hugegraph-commons` is shared by every module; `hugegraph-struct` must precede PD/Store;
102+
server backends depend on `hugegraph-core`.
104103

105-
## Reference Documents
104+
## Additional context files
106105

107-
| Resource | When to consult |
108-
|----------|-----------------|
109-
| `README.md` | Project overview, deployment topology, contribution guide |
110-
| `.serena/memories/` | Project agent memory; key files: `suggested_commands.md` (commands), `task_completion_checklist.md` (pre-commit checks) |
106+
`.serena/memories/` — notably `suggested_commands.md` and `task_completion_checklist.md`
107+
when a task needs depth beyond this file.

0 commit comments

Comments
 (0)