Skip to content

Commit 9a29f52

Browse files
committed
feat: init serena onboarding & project memory files
Introduces the .serena directory with onboarding documentation, project architecture, code style, workflows, and related memory files for HugeGraph Toolchain. These files provide guidelines and quick start information for new developers, covering project overview, design patterns, code conventions, testing, and development workflows.
1 parent e2a9dd4 commit 9a29f52

9 files changed

+3005
-0
lines changed

.serena/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/cache

.serena/memories/README_INDEX.md

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Memory Index - HugeGraph Toolchain Project
2+
3+
## Onboarding Complete ✓
4+
5+
This project has been successfully initialized with Serena MCP. Below is an index of all available memory files.
6+
7+
## Available Memories (7 Core Files)
8+
9+
### Core Project Information
10+
11+
1. **project_overview.md** (125 lines)
12+
- Project purpose and goals
13+
- All 6 modules (client, loader, hubble, tools, client-go, spark-connector)
14+
- Technology stack (Java 8, Node.js 18.20.8, Go, React, Spring Boot)
15+
- Module dependencies and relationships
16+
- External dependencies
17+
- Project structure
18+
19+
### Code Quality and Style
20+
21+
2. **code_style_and_conventions.md** (311 lines)
22+
- Java code style (indentation, naming, formatting)
23+
- Naming conventions (classes, methods, variables)
24+
- Import rules and prohibited imports
25+
- Maven POM style
26+
- Frontend code style (TypeScript, CSS/Less)
27+
- Go code style
28+
- Design patterns used in each module
29+
- File organization standards
30+
- Commit message format
31+
32+
3. **task_completion_checklist.md** (372 lines) ⭐ **IMPORTANT**
33+
- Code quality checks before committing
34+
- Testing requirements
35+
- Build verification steps
36+
- Documentation update checklist
37+
- Git pre-commit checklist
38+
- Pull request checklist
39+
- CI/CD pipeline details
40+
- Common issues and solutions
41+
- Release-specific tasks
42+
43+
### Architecture and Design
44+
45+
4. **architecture_and_design_patterns.md** (571 lines)
46+
- Overall system architecture
47+
- Module-specific architectures:
48+
- hugegraph-client: Layered architecture, Manager pattern
49+
- hugegraph-loader: Pipeline architecture
50+
- hugegraph-hubble: Frontend (React+MobX) + Backend (Spring Boot)
51+
- hugegraph-tools: Command pattern
52+
- Design patterns (Factory, Builder, Strategy, Observer, Repository)
53+
- Cross-cutting concerns (error handling, logging)
54+
- Configuration management
55+
56+
### Testing
57+
58+
5. **testing_infrastructure.md** (634 lines)
59+
- Testing philosophy (unit, integration, functional)
60+
- Test organization and structure
61+
- Module-specific testing:
62+
- hugegraph-client: UnitTestSuite, ApiTestSuite, FuncTestSuite
63+
- hugegraph-loader: Test profiles (unit, file, hdfs, jdbc, kafka)
64+
- hugegraph-hubble: Backend (Spring Test) + Frontend (Jest)
65+
- hugegraph-client-go: Go standard testing
66+
- CI/CD testing pipelines
67+
- Test coverage tools and targets
68+
- Common testing patterns
69+
- Debugging tests
70+
71+
### Development Workflows
72+
73+
6. **common_development_workflows.md** (657 lines)
74+
- Daily development workflows:
75+
- Starting new features
76+
- Fixing bugs
77+
- Adding tests
78+
- Refactoring code
79+
- Module-specific workflows
80+
- Troubleshooting common issues
81+
- Release workflow
82+
- Useful development commands
83+
- Git hooks setup
84+
- IDE configuration (IntelliJ IDEA, VS Code)
85+
86+
## Quick Start Guide
87+
88+
### For New Developers
89+
90+
1. **Read First**:
91+
- `project_overview.md` - Understand what the project is
92+
- `common_development_workflows.md` - Learn essential commands and workflows
93+
94+
2. **Before Making Changes**:
95+
- `code_style_and_conventions.md` - Learn coding standards
96+
- `task_completion_checklist.md` - Know what to check before committing
97+
98+
3. **When Working on Code**:
99+
- `architecture_and_design_patterns.md` - Understand design patterns
100+
101+
4. **When Writing Tests**:
102+
- `testing_infrastructure.md` - Learn testing approach
103+
104+
### For System Setup
105+
106+
**Prerequisites** (macOS):
107+
```bash
108+
# Java 11 (required)
109+
/usr/libexec/java_home -V
110+
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
111+
112+
# Maven
113+
brew install maven
114+
115+
# Node.js 18.20.8 (for Hubble)
116+
nvm install 18.20.8
117+
nvm use 18.20.8
118+
npm install -g yarn
119+
120+
# Python 3 (for Hubble build)
121+
brew install python3
122+
pip3 install -r hugegraph-hubble/hubble-dist/assembly/travis/requirements.txt
123+
```
124+
125+
**Build Entire Project**:
126+
```bash
127+
mvn clean install -DskipTests -Dmaven.javadoc.skip=true -ntp
128+
```
129+
130+
**Run Tests**:
131+
```bash
132+
# Client tests
133+
cd hugegraph-client
134+
mvn test -Dtest=UnitTestSuite -ntp
135+
136+
# Loader tests
137+
cd hugegraph-loader
138+
mvn test -P unit -ntp
139+
140+
# Hubble tests
141+
cd hugegraph-hubble/hubble-fe
142+
yarn test
143+
```
144+
145+
## Essential Commands Cheat Sheet
146+
147+
### Build Commands
148+
```bash
149+
# Full project
150+
mvn clean install -DskipTests -Dmaven.javadoc.skip=true -ntp
151+
152+
# Specific module (e.g., client)
153+
mvn install -pl hugegraph-client -am -DskipTests -ntp
154+
155+
# Hubble (requires dependencies built first)
156+
mvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp
157+
cd hugegraph-hubble
158+
mvn -e compile package -Dmaven.test.skip=true -ntp
159+
```
160+
161+
### Testing Commands
162+
```bash
163+
# Client unit tests
164+
cd hugegraph-client && mvn test -Dtest=UnitTestSuite -ntp
165+
166+
# Loader tests
167+
cd hugegraph-loader && mvn test -P unit -ntp
168+
169+
# Single test
170+
mvn test -Dtest=ClassName#methodName -ntp
171+
```
172+
173+
### Code Quality
174+
```bash
175+
# Checkstyle
176+
mvn checkstyle:check
177+
178+
# License check
179+
mvn apache-rat:check
180+
181+
# EditorConfig validation
182+
mvn editorconfig:check
183+
```
184+
185+
### Git Commands (IMPORTANT: Always use --no-pager)
186+
```bash
187+
# View history
188+
git --no-pager log --oneline -10
189+
190+
# View changes
191+
git --no-pager diff HEAD~1
192+
```
193+
194+
**See `common_development_workflows.md` for complete command reference**
195+
196+
## Key Project Facts
197+
198+
- **Language**: Java 8 (main), Go, TypeScript
199+
- **Build Tool**: Maven 3.x
200+
- **Test Framework**: JUnit 4 + Mockito
201+
- **Frontend**: React + TypeScript + MobX (Node.js 18.20.8)
202+
- **Backend**: Spring Boot
203+
- **Version**: 1.7.0
204+
- **License**: Apache 2.0
205+
- **Repository**: https://github.com/apache/hugegraph-toolchain
206+
207+
## Common Pitfalls to Avoid
208+
209+
1.**DON'T** use `git log` without `--no-pager` flag
210+
2.**DON'T** commit without running checkstyle and tests
211+
3.**DON'T** use star imports (`import org.apache.*`)
212+
4.**DON'T** use `System.out.println` (use logger instead)
213+
5.**DON'T** forget Apache 2.0 license headers
214+
6.**DON'T** use tabs (use 4 spaces for Java, 2 for frontend)
215+
7.**DON'T** exceed 100 character line length
216+
8.**DON'T** commit code that fails CI checks
217+
218+
## Getting Help
219+
220+
- **Documentation**: https://hugegraph.apache.org/docs/
221+
- **Issues**: https://github.com/apache/hugegraph-toolchain/issues
222+
- **Mailing List**: dev@hugegraph.apache.org
223+
- **Memory Files**: Check `.serena/memories/` directory
224+
225+
## Memory Statistics
226+
227+
- **Total Memory Files**: 7 (including this index)
228+
- **Total Lines**: ~2,900+
229+
- **Total Size**: ~85KB
230+
- **Coverage Areas**:
231+
- Project overview and structure
232+
- Code style and conventions
233+
- Architecture and design patterns
234+
- Testing infrastructure
235+
- Development workflows
236+
- Task completion checklists
237+
238+
## Last Updated
239+
240+
Onboarding completed: 2025-11-05
241+
242+
---
243+
244+
**Note**: All memories are stored in `.serena/memories/` directory and can be read using Serena MCP tools.

0 commit comments

Comments
 (0)