This is an automated email from the ASF dual-hosted git repository. jin pushed a commit to branch serena in repository https://gitbox.apache.org/repos/asf/incubator-hugegraph.git
commit 3ac2649c68eee6e72a7d2a6f0e358ee16aeabfe3 Author: imbajin <[email protected]> AuthorDate: Wed Nov 5 18:54:01 2025 +0800 feat: init serena memory system & add memories Introduced the .serena directory with project configuration (project.yml), .gitignore, and comprehensive documentation files covering architecture, code style, ecosystem, implementation guidelines, key file locations, project overview, suggested commands, and a task completion checklist. These additions provide essential onboarding, development, and operational guidance for the project. --- .serena/.gitignore | 1 + .serena/memories/architecture_and_modules.md | 99 +++++++++++++++ .serena/memories/code_style_and_conventions.md | 92 ++++++++++++++ .serena/memories/ecosystem_and_related_projects.md | 63 ++++++++++ .../implementation_patterns_and_guidelines.md | 104 +++++++++++++++ .serena/memories/key_file_locations.md | 87 +++++++++++++ .serena/memories/project_overview.md | 35 ++++++ .serena/memories/suggested_commands.md | 131 +++++++++++++++++++ .serena/memories/task_completion_checklist.md | 139 +++++++++++++++++++++ .serena/project.yml | 84 +++++++++++++ 10 files changed, 835 insertions(+) diff --git a/.serena/.gitignore b/.serena/.gitignore new file mode 100644 index 000000000..14d86ad62 --- /dev/null +++ b/.serena/.gitignore @@ -0,0 +1 @@ +/cache diff --git a/.serena/memories/architecture_and_modules.md b/.serena/memories/architecture_and_modules.md new file mode 100644 index 000000000..bd2402d6a --- /dev/null +++ b/.serena/memories/architecture_and_modules.md @@ -0,0 +1,99 @@ +# Architecture and Module Structure + +## Three-Tier Architecture + +### 1. Client Layer +- Gremlin/Cypher query interfaces +- REST API endpoints +- Multiple client language bindings + +### 2. 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 + +### 3. Storage Layer +- Pluggable backend implementations +- Each backend extends `hugegraph-core` abstractions +- Implements `BackendStore` interface + +## Multi-Module Structure + +The project consists of 7 main modules: + +### 1. hugegraph-server (13 submodules) +Core graph engine, REST APIs, and backend implementations: +- `hugegraph-core` - Core graph engine and abstractions +- `hugegraph-api` - REST API implementations (includes OpenCypher in `opencypher/`) +- `hugegraph-dist` - Distribution packaging and scripts +- `hugegraph-test` - Test suites (unit, core, API, TinkerPop) +- `hugegraph-example` - Example code +- Backend implementations: + - `hugegraph-rocksdb` (default) + - `hugegraph-hstore` (distributed) + - `hugegraph-hbase` + - `hugegraph-mysql` + - `hugegraph-postgresql` + - `hugegraph-cassandra` + - `hugegraph-scylladb` + - `hugegraph-palo` + +### 2. hugegraph-pd (8 submodules) +Placement Driver for distributed deployments (meta server): +- `hg-pd-core` - Core PD logic +- `hg-pd-service` - PD service implementation +- `hg-pd-client` - Client library +- `hg-pd-common` - Shared utilities +- `hg-pd-grpc` - gRPC protocol definitions (auto-generated) +- `hg-pd-cli` - Command line interface +- `hg-pd-dist` - Distribution packaging +- `hg-pd-test` - Test suite + +### 3. hugegraph-store (9 submodules) +Distributed storage backend with RocksDB and Raft: +- `hg-store-core` - Core storage logic +- `hg-store-node` - Storage node implementation +- `hg-store-client` - Client library +- `hg-store-common` - Shared utilities +- `hg-store-grpc` - gRPC protocol definitions (auto-generated) +- `hg-store-rocksdb` - RocksDB integration +- `hg-store-cli` - Command line interface +- `hg-store-dist` - Distribution packaging +- `hg-store-test` - Test suite + +### 4. hugegraph-commons +Shared utilities across modules: +- Locks and concurrency utilities +- Configuration management +- RPC framework components + +### 5. hugegraph-struct +Data structure definitions shared between modules. +**Important**: Must be built before PD and Store modules. + +### 6. install-dist +Distribution packaging and release management: +- License and NOTICE files +- Dependency management scripts +- Release documentation + +### 7. hugegraph-cluster-test +Cluster integration tests for distributed deployments + +## Cross-Module Dependencies + +``` +hugegraph-commons → (shared by all modules) +hugegraph-struct → hugegraph-pd + hugegraph-store +hugegraph-core → (extended by all backend implementations) +``` + +## Distributed Architecture (Optional) + +For production distributed deployments: +- **hugegraph-pd**: Service discovery, partition management, metadata +- **hugegraph-store**: Distributed storage with Raft (3+ nodes) +- **hugegraph-server**: Multiple server instances (3+) +- Communication: All use gRPC with Protocol Buffers + +**Status**: Distributed components (PD + Store) are in BETA \ No newline at end of file diff --git a/.serena/memories/code_style_and_conventions.md b/.serena/memories/code_style_and_conventions.md new file mode 100644 index 000000000..eb44a54ff --- /dev/null +++ b/.serena/memories/code_style_and_conventions.md @@ -0,0 +1,92 @@ +# Code Style and Conventions + +## Code Style Configuration +- **Import**: Use `hugegraph-style.xml` in your IDE (IntelliJ IDEA recommended) +- **EditorConfig**: `.editorconfig` file defines style rules (validated in CI) +- **Checkstyle**: `style/checkstyle.xml` defines additional rules + +## Core Style Rules (from .editorconfig) + +### General +- Charset: UTF-8 +- End of line: LF (Unix-style) +- Insert final newline: true +- Max line length: 100 characters (120 for XML) +- Visual guides at column 100 + +### Java Files +- Indent: 4 spaces (not tabs) +- Continuation indent: 8 spaces +- Wrap on typing: true +- Wrap long lines: true + +### Import Organization +``` +$* +| +java.** +| +javax.** +| +org.** +| +com.** +| +* +``` +- Class count to use import on demand: 100 +- Names count to use import on demand: 100 + +### Formatting Rules +- Line comments not at first column +- Align multiline: chained methods, parameters in calls, binary operations, assignments, ternary, throws, extends, array initializers +- Wrapping: normal (wrap if necessary) +- Brace forcing: + - if: if_multiline + - do-while: always + - while: if_multiline + - for: if_multiline +- Enum constants: split_into_lines + +### Blank Lines +- Max blank lines in declarations: 1 +- Max blank lines in code: 1 +- Blank lines between package declaration and header: 1 +- Blank lines before right brace: 1 +- Blank lines around class: 1 +- Blank lines after class header: 1 + +### Documentation +- Add `<p>` tag on empty lines: true +- Do not wrap if one line: true +- Align multiline annotation parameters: true + +### XML Files +- Indent: 4 spaces +- Max line length: 120 +- Text wrap: off +- Space inside empty tag: true + +### Maven +- Compiler source/target: Java 11 +- Max compiler errors: 500 +- Compiler args: `-Xlint:unchecked` +- Source encoding: UTF-8 + +## Lombok Usage +- Version: 1.18.30 +- Scope: provided +- Optional: true + +## License Headers +- All source files MUST include Apache Software License header +- Validated by apache-rat-plugin and skywalking-eyes +- Exclusions defined in pom.xml (line 171-221) +- gRPC generated code excluded from license check + +## Naming Conventions +- Package names: lowercase, dot-separated (e.g., org.apache.hugegraph) +- Class names: PascalCase +- Method names: camelCase +- Constants: UPPER_SNAKE_CASE +- Variables: camelCase \ No newline at end of file diff --git a/.serena/memories/ecosystem_and_related_projects.md b/.serena/memories/ecosystem_and_related_projects.md new file mode 100644 index 000000000..393217f8d --- /dev/null +++ b/.serena/memories/ecosystem_and_related_projects.md @@ -0,0 +1,63 @@ +# HugeGraph Ecosystem and Related Projects + +## Core Repository (This Project) +**Repository**: apache/hugegraph (server) +**Purpose**: Core graph database engine (OLTP) + +## Related Repositories + +### 1. hugegraph-toolchain +**Repository**: https://github.com/apache/hugegraph-toolchain +**Components**: +- **hugegraph-loader**: Bulk data loading tool +- **hugegraph-hubble**: Web-based visualization dashboard +- **hugegraph-tools**: Command-line utilities +- **hugegraph-client**: Java client SDK + +### 2. hugegraph-computer +**Repository**: https://github.com/apache/hugegraph-computer +**Purpose**: Distributed graph computing framework (OLAP) +**Features**: PageRank, Connected Components, Shortest Path, Community Detection + +### 3. hugegraph-ai +**Repository**: https://github.com/apache/incubator-hugegraph-ai +**Purpose**: Graph AI, LLM, and Knowledge Graph integration +**Features**: Graph-enhanced LLM, KG construction, Graph RAG, NL to Gremlin/Cypher + +### 4. hugegraph-website +**Repository**: https://github.com/apache/hugegraph-doc +**Purpose**: Official documentation and website +**URL**: https://hugegraph.apache.org/ + +## Integration Points + +### Data Pipeline +``` +Data Sources → hugegraph-loader → hugegraph-server + ↓ + ┌───────────────────┼───────────────────┐ + ↓ ↓ ↓ + hugegraph-hubble hugegraph-computer hugegraph-ai + (Visualization) (Analytics) (AI/ML) +``` + +## External Integrations + +### Big Data Platforms +- Apache Flink, Apache Spark, HDFS + +### Storage Backends +- RocksDB (default), HBase, Cassandra, ScyllaDB, MySQL, PostgreSQL + +### Query Languages +- Gremlin (Apache TinkerPop), Cypher (OpenCypher), REST API + +## Version Compatibility +- Server: 1.7.0 +- TinkerPop: 3.5.1 +- Java: 11+ required + +## Use Cases +- Social networks, Fraud detection, Recommendation systems +- Knowledge graphs, Network analysis, Supply chain management +- IT operations, Bioinformatics \ No newline at end of file diff --git a/.serena/memories/implementation_patterns_and_guidelines.md b/.serena/memories/implementation_patterns_and_guidelines.md new file mode 100644 index 000000000..c4862fbd5 --- /dev/null +++ b/.serena/memories/implementation_patterns_and_guidelines.md @@ -0,0 +1,104 @@ +# Implementation Patterns and Guidelines + +## Backend Development + +### Backend Architecture Pattern +- All backends extend abstractions from `hugegraph-server/hugegraph-core` +- Implement the `BackendStore` interface +- Each backend is a separate Maven module under `hugegraph-server/` +- Backend selection configured in `hugegraph.properties` via `backend` property + +### Available Backends +- **RocksDB** (default, embedded): `hugegraph-rocksdb` +- **HStore** (distributed, production): `hugegraph-hstore` +- **Legacy** (≤1.5.0): MySQL, PostgreSQL, Cassandra, ScyllaDB, HBase, Palo + +### Backend Testing Profiles +- `memory`: In-memory backend for fast unit tests +- `rocksdb`: RocksDB for realistic local tests +- `hbase`: HBase for distributed scenarios +- `hstore`: HStore for production-like distributed tests + +## gRPC Protocol Development + +### Protocol Buffer Definitions +- PD protos: `hugegraph-pd/hg-pd-grpc/src/main/proto/` +- Store protos: `hugegraph-store/hg-store-grpc/src/main/proto/` + +### Code Generation +When modifying `.proto` files: +1. Run `mvn clean compile` to regenerate gRPC stubs +2. Generated Java code goes to `*/grpc/` packages +3. Output location: `target/generated-sources/protobuf/` +4. Generated files excluded from Apache RAT checks +5. All inter-service communication uses gRPC + +## Authentication System + +### Default State +- Authentication **disabled by default** +- Enable via `bin/enable-auth.sh` or configuration +- **Required for production deployments** + +### Implementation Location +`hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/` + +### Multi-Level Security Model +- Users, Groups, Projects, Targets, Access control + +## TinkerPop Integration + +### Compliance +- Full Apache TinkerPop 3 implementation +- Custom optimization strategies +- Supports both Gremlin and OpenCypher query languages + +### Query Language Support +- **Gremlin**: Native via TinkerPop integration +- **OpenCypher**: Implementation in `hugegraph-api/opencypher/` + +## Testing Patterns + +### Test Suite Organization +- **UnitTestSuite**: Pure unit tests, no external dependencies +- **CoreTestSuite**: Core functionality tests with backend +- **ApiTestSuite**: REST API integration tests +- **StructureStandardTest**: TinkerPop structure compliance +- **ProcessStandardTest**: TinkerPop process compliance + +### Backend Selection in Tests +Use Maven profiles: +```bash +-P core-test,memory # Fast in-memory +-P core-test,rocksdb # Persistent local +-P api-test,rocksdb # API with persistent backend +``` + +## Distribution and Packaging + +### Creating Distribution +```bash +mvn clean package -DskipTests +``` +Output: `install-dist/target/hugegraph-<version>.tar.gz` + +## Code Organization + +### Package Structure +``` +org.apache.hugegraph +├── backend/ # Backend implementations +├── api/ # REST API endpoints +├── core/ # Core graph engine +├── schema/ # Schema definitions +├── traversal/ # Traversal and query processing +├── task/ # Background tasks +├── auth/ # Authentication/authorization +└── util/ # Utilities +``` + +### Module Dependencies +- Commons is shared by all modules +- Struct must be built before PD and Store +- Backend modules depend on core +- Test module depends on all server modules \ No newline at end of file diff --git a/.serena/memories/key_file_locations.md b/.serena/memories/key_file_locations.md new file mode 100644 index 000000000..dae4cc350 --- /dev/null +++ b/.serena/memories/key_file_locations.md @@ -0,0 +1,87 @@ +# Key File and Directory Locations + +## Project Root +The project root contains the multi-module Maven structure. + +## Configuration Files + +### Build Configuration +- `pom.xml` - Root Maven POM (multi-module) +- `.editorconfig` - Code style rules +- `style/checkstyle.xml` - Checkstyle rules +- `.licenserc.yaml` - License checker config + +### Documentation +- `README.md` - Project overview +- `BUILDING.md` - Build instructions +- `CONTRIBUTING.md` - Contribution guide +- `AGENTS.md` - AI agent development guide +- `LICENSE` - Apache License 2.0 +- `NOTICE` - Copyright notices + +## Server Module (hugegraph-server) + +### Core Implementation +- `hugegraph-core/src/main/java/org/apache/hugegraph/` - Core engine + - `backend/` - Backend interface + - `schema/` - Schema management + - `traversal/` - Query processing + - `task/` - Background tasks + +### API Layer +- `hugegraph-api/src/main/java/org/apache/hugegraph/api/` - REST APIs + - `graph/` - GraphAPI + - `schema/` - SchemaAPI + - `gremlin/` - GremlinAPI + - `cypher/` - CypherAPI + - `auth/` - AuthAPI + - `opencypher/` - OpenCypher implementation + +### Backend Implementations +- `hugegraph-rocksdb/` - RocksDB backend (default) +- `hugegraph-hstore/` - HStore distributed backend +- `hugegraph-hbase/` - HBase backend +- `hugegraph-mysql/` - MySQL backend +- `hugegraph-postgresql/` - PostgreSQL backend +- `hugegraph-cassandra/` - Cassandra backend +- `hugegraph-scylladb/` - ScyllaDB backend +- `hugegraph-palo/` - Palo backend + +### Distribution and Scripts +- `hugegraph-dist/src/assembly/static/` - Distribution files + - `bin/` - Shell scripts (init-store.sh, start-hugegraph.sh, stop-hugegraph.sh, etc.) + - `conf/` - Configuration files (hugegraph.properties, rest-server.properties, gremlin-server.yaml, log4j2.xml) + - `lib/` - JAR dependencies + - `logs/` - Log files + +### Testing +- `hugegraph-test/src/main/java/org/apache/hugegraph/` - Test suites + - `unit/` - Unit tests + - `core/` - Core functionality tests + - `api/` - API integration tests + - `tinkerpop/` - TinkerPop compliance tests + +## PD Module (hugegraph-pd) +- `hg-pd-core/` - Core PD logic +- `hg-pd-service/` - Service implementation +- `hg-pd-client/` - Client library +- `hg-pd-grpc/src/main/proto/` - Protocol definitions +- `hg-pd-dist/src/assembly/static/` - Distribution files + +## Store Module (hugegraph-store) +- `hg-store-core/` - Core storage logic +- `hg-store-node/` - Storage node +- `hg-store-client/` - Client library +- `hg-store-grpc/src/main/proto/` - Protocol definitions +- `hg-store-dist/src/assembly/static/` - Distribution files + +## Commons Module (hugegraph-commons) +- Shared utilities, RPC framework + +## Struct Module (hugegraph-struct) +- Data structure definitions (must be built before PD and Store) + +## Distribution Module (install-dist) +- `release-docs/` - LICENSE, NOTICE, licenses/ +- `scripts/dependency/` - Dependency management scripts +- `target/` - Build output (hugegraph-<version>.tar.gz) \ No newline at end of file diff --git a/.serena/memories/project_overview.md b/.serena/memories/project_overview.md new file mode 100644 index 000000000..27ac0ecae --- /dev/null +++ b/.serena/memories/project_overview.md @@ -0,0 +1,35 @@ +# Apache HugeGraph Project Overview + +## Project Purpose +Apache HugeGraph is a fast-speed and highly-scalable graph database that supports billions of vertices and edges (10+ billion scale). It is designed for OLTP workloads with excellent performance and scalability. + +## Key Capabilities +- Graph database compliant with Apache TinkerPop 3 framework +- Supports both Gremlin and Cypher query languages +- Schema metadata management (VertexLabel, EdgeLabel, PropertyKey, IndexLabel) +- Multi-type indexes (exact, range, complex conditions) +- Pluggable backend storage architecture +- Integration with big data platforms (Flink/Spark/HDFS) +- Complete graph ecosystem (computing, visualization, AI/ML) + +## Technology Stack +- **Language**: Java 11+ (required) +- **Build Tool**: Apache Maven 3.5+ (required) +- **Graph Framework**: Apache TinkerPop 3.5.1 +- **RPC**: gRPC with Protocol Buffers +- **Storage Backends**: + - RocksDB (default, embedded) + - HStore (distributed, production) + - Legacy (≤1.5.0): MySQL, PostgreSQL, Cassandra, ScyllaDB, HBase, Palo + +## Project Version +- Current version: 1.7.0 (managed via `${revision}` property) +- Version management uses Maven flatten plugin for CI-friendly versioning + +## License +- Apache License 2.0 +- All code must include Apache license headers +- Third-party dependencies require proper license documentation + +## Repository Structure +This is a multi-module Maven project \ No newline at end of file diff --git a/.serena/memories/suggested_commands.md b/.serena/memories/suggested_commands.md new file mode 100644 index 000000000..a86f324b4 --- /dev/null +++ b/.serena/memories/suggested_commands.md @@ -0,0 +1,131 @@ +# Suggested Development Commands + +## Quick Reference + +### Prerequisites Check +```bash +java -version # Must be 11+ +mvn -version # Must be 3.5+ +``` + +### Build Commands +```bash +# Full build without tests (fastest) +mvn clean install -DskipTests + +# Full build with all tests +mvn clean install + +# Build specific module (e.g., server) +mvn clean install -pl hugegraph-server -am -DskipTests + +# Compile only +mvn clean compile -U -Dmaven.javadoc.skip=true -ntp + +# Build distribution package +mvn clean package -DskipTests +# Output: install-dist/target/hugegraph-<version>.tar.gz +``` + +### Testing Commands +```bash +# Unit tests (memory backend) +mvn test -pl hugegraph-server/hugegraph-test -am -P unit-test,memory + +# 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 +mvn test -pl hugegraph-server/hugegraph-test -am -P api-test,rocksdb + +# TinkerPop compliance tests (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 + +# Run single test class +mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory -Dtest=YourTestClass + +# PD module tests (build struct first) +mvn install -pl hugegraph-struct -am -DskipTests +mvn test -pl hugegraph-pd/hg-pd-test -am + +# Store module tests (build struct first) +mvn install -pl hugegraph-struct -am -DskipTests +mvn test -pl hugegraph-store/hg-store-test -am +``` + +### Code Quality & Validation +```bash +# License header check (Apache RAT) +mvn apache-rat:check -ntp + +# Code style check (EditorConfig) +mvn editorconfig:check + +# Compile with warnings +mvn clean compile -Dmaven.javadoc.skip=true +``` + +### Server Operations +```bash +# Scripts location: hugegraph-server/hugegraph-dist/src/assembly/static/bin/ + +# Initialize storage backend +bin/init-store.sh + +# Start HugeGraph server +bin/start-hugegraph.sh + +# Stop HugeGraph server +bin/stop-hugegraph.sh + +# Start Gremlin console +bin/gremlin-console.sh + +# Enable authentication +bin/enable-auth.sh + +# Dump effective configuration +bin/dump-conf.sh + +# Monitor server +bin/monitor-hugegraph.sh +``` + +### Git Operations (macOS/Darwin) +```bash +# View git log (avoid pager) +git --no-pager log -n 20 --oneline + +# View git diff (avoid pager) +git --no-pager diff + +# Check git status +git status +``` + +### Docker Commands (Test/Dev) +```bash +# Start HugeGraph in Docker (RocksDB backend) +docker run -itd --name=graph -p 8080:8080 hugegraph/hugegraph:1.5.0 + +# Start with preloaded sample graph +docker run -itd --name=graph -e PRELOAD=true -p 8080:8080 hugegraph/hugegraph:1.5.0 +``` + +### Distributed Components Build (BETA) +```bash +# 1. Build hugegraph-struct (required dependency) +mvn install -pl hugegraph-struct -am -DskipTests + +# 2. Build hugegraph-pd (Placement Driver) +mvn clean package -pl hugegraph-pd -am -DskipTests + +# 3. Build hugegraph-store (distributed storage) +mvn clean package -pl hugegraph-store -am -DskipTests + +# 4. Build hugegraph-server with HStore backend +mvn clean package -pl hugegraph-server -am -DskipTests +``` \ No newline at end of file diff --git a/.serena/memories/task_completion_checklist.md b/.serena/memories/task_completion_checklist.md new file mode 100644 index 000000000..ec6a84be4 --- /dev/null +++ b/.serena/memories/task_completion_checklist.md @@ -0,0 +1,139 @@ +# Task Completion Checklist + +When completing a coding task, follow these steps to ensure quality and compliance: + +## 1. Code Quality Checks (MANDATORY) + +### License Header Check +Run Apache RAT to verify all files have proper license headers: +```bash +mvn apache-rat:check -ntp +``` +Fix any violations by adding the Apache license header. + +### Code Style Check +Run EditorConfig validation: +```bash +mvn editorconfig:check +``` +Fix violations according to `.editorconfig` rules. + +### Compilation Check +Compile with warnings enabled: +```bash +mvn clean compile -Dmaven.javadoc.skip=true +``` +Resolve all compiler warnings, especially unchecked operations. + +## 2. Testing (REQUIRED) + +### Determine Test Scope +Check project README or ask user for test commands. Common patterns: + +#### Server Module Tests +- Unit tests: +```bash +mvn test -pl hugegraph-server/hugegraph-test -am -P unit-test,memory +``` +- Core tests (choose backend): +```bash +mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,memory +mvn test -pl hugegraph-server/hugegraph-test -am -P core-test,rocksdb +``` +- API tests: +```bash +mvn test -pl hugegraph-server/hugegraph-test -am -P api-test,rocksdb +``` + +#### PD Module Tests +```bash +# Build struct dependency first +mvn install -pl hugegraph-struct -am -DskipTests +# Run PD tests +mvn test -pl hugegraph-pd/hg-pd-test -am +``` + +#### Store Module Tests +```bash +# Build struct dependency first +mvn install -pl hugegraph-struct -am -DskipTests +# Run Store tests +mvn test -pl hugegraph-store/hg-store-test -am +``` + +### Run Appropriate Tests +Execute tests relevant to your changes: +- For bug fixes: run existing tests to verify fix +- For new features: write and run new tests +- For refactoring: run all affected module tests + +## 3. Dependencies Management + +If adding new third-party dependencies: + +1. Add license file to `install-dist/release-docs/licenses/` +2. Declare dependency in `install-dist/release-docs/LICENSE` +3. Append NOTICE (if exists) to `install-dist/release-docs/NOTICE` +4. Update dependency list: +```bash +./install-dist/scripts/dependency/regenerate_known_dependencies.sh +``` +Or manually update `install-dist/scripts/dependency/known-dependencies.txt` + +## 4. Build Verification + +Build the affected module(s) with tests: +```bash +mvn clean install -pl <module> -am +``` + +## 5. Documentation (if applicable) + +- Update JavaDoc for public APIs +- Update README if adding user-facing features +- Update AGENTS.md if adding dev-facing information + +## 6. Commit Preparation + +### NEVER Commit Unless Explicitly Asked +- Do NOT auto-commit changes +- Only commit when user explicitly requests it +- This is CRITICAL to avoid surprising users + +### When Asked to Commit +- Write clear commit messages: +``` +Fix bug: <brief description> + +fix #ISSUE_ID +``` +- Include issue ID if available +- Describe what and how the change works + +## 7. Pre-PR Checklist + +Before creating a Pull Request, ensure: +- [ ] All license checks pass +- [ ] All code style checks pass +- [ ] All relevant tests pass +- [ ] Code compiles without warnings +- [ ] Dependencies properly documented (if added) +- [ ] Changes tested locally +- [ ] Commit message is clear and references issue + +## Common CI Workflows + +Your changes will be validated by: +- `server-ci.yml`: Compiles + unit/core/API tests (memory, rocksdb, hbase) +- `licence-checker.yml`: License header validation +- `pd-store-ci.yml`: PD and Store module tests +- `commons-ci.yml`: Commons module tests +- `cluster-test-ci.yml`: Distributed cluster tests + +## Notes + +- **Test Backend Selection**: Use `memory` for quick tests, `rocksdb` for realistic tests, `hbase` for distributed scenarios +- **TinkerPop Tests**: Only run on release branches (release-*/test-*) +- **Raft Tests**: Only run when branch name starts with `test` or `raft` +- **Build Time**: Full build can take 5-15 minutes depending on hardware +- **Test Time**: Test suites can take 10-30 minutes depending on backend \ No newline at end of file diff --git a/.serena/project.yml b/.serena/project.yml new file mode 100644 index 000000000..5db60ba6b --- /dev/null +++ b/.serena/project.yml @@ -0,0 +1,84 @@ +# list of languages for which language servers are started; choose from: +# al bash clojure cpp csharp csharp_omnisharp +# dart elixir elm erlang fortran go +# haskell java julia kotlin lua markdown +# nix perl php python python_jedi r +# rego ruby ruby_solargraph rust scala swift +# terraform typescript typescript_vts zig +# Note: +# - For C, use cpp +# - For JavaScript, use typescript +# Special requirements: +# - csharp: Requires the presence of a .sln file in the project folder. +# When using multiple languages, the first language server that supports a given file will be used for that file. +# The first language is the default language and the respective language server will be used as a fallback. +# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored. +languages: +- java + +# the encoding used by text files in the project +# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings +encoding: "utf-8" + +# whether to use the project's gitignore file to ignore files +# Added on 2025-04-07 +ignore_all_files_in_gitignore: true + +# list of additional paths to ignore +# same syntax as gitignore, so you can use * and ** +# Was previously called `ignored_dirs`, please update your config if you are using that. +# Added (renamed) on 2025-04-07 +ignored_paths: [] + +# whether the project is in read-only mode +# If set to true, all editing tools will be disabled and attempts to use them will result in an error +# Added on 2025-04-18 +read_only: false + +# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details. +# Below is the complete list of tools for convenience. +# To make sure you have the latest list of tools, and to view their descriptions, +# execute `uv run scripts/print_tool_overview.py`. +# +# * `activate_project`: Activates a project by name. +# * `check_onboarding_performed`: Checks whether project onboarding was already performed. +# * `create_text_file`: Creates/overwrites a file in the project directory. +# * `delete_lines`: Deletes a range of lines within a file. +# * `delete_memory`: Deletes a memory from Serena's project-specific memory store. +# * `execute_shell_command`: Executes a shell command. +# * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced. +# * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type). +# * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type). +# * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes. +# * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file. +# * `initial_instructions`: Gets the initial instructions for the current project. +# Should only be used in settings where the system prompt cannot be set, +# e.g. in clients you have no control over, like Claude Desktop. +# * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol. +# * `insert_at_line`: Inserts content at a given line in a file. +# * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol. +# * `list_dir`: Lists files and directories in the given directory (optionally with recursion). +# * `list_memories`: Lists memories in Serena's project-specific memory store. +# * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building). +# * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context). +# * `read_file`: Reads a file within the project directory. +# * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store. +# * `remove_project`: Removes a project from the Serena configuration. +# * `replace_lines`: Replaces a range of lines within a file with new content. +# * `replace_symbol_body`: Replaces the full definition of a symbol. +# * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen. +# * `search_for_pattern`: Performs a search for a pattern in the project. +# * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase. +# * `switch_modes`: Activates modes by providing a list of their names +# * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information. +# * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task. +# * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed. +# * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store. +excluded_tools: [] + +# initial prompt for the project. It will always be given to the LLM upon activating the project +# (contrary to the memories, which are loaded on demand). +initial_prompt: "" + +project_name: "server" +included_optional_tools: []
