Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
225 lines (164 loc) · 4.85 KB

CONTRIBUTING.md

File metadata and controls

225 lines (164 loc) · 4.85 KB
Raw

贡献指南

感谢你对代码知识图谱项目的关注！本文档将帮助你参与项目开发。

开发环境搭建

前置条件

  • Java 17+ — 后端运行时
  • Maven 3.8+ — 后端构建
  • Node.js 18+ — 前端运行时
  • Docker & Docker Compose — 基础设施服务
  • Git — 版本管理

本地开发设置

# 1. Fork 并克隆项目
git clone https://github.com/YOUR_USERNAME/code-knowledge-graph.git
cd code-knowledge-graph

# 2. 启动基础设施
docker-compose up -d neo4j postgres redis

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，至少配置 LLM_API_KEY

# 4. 启动后端
cd backend
mvn spring-boot:run

# 5. 启动前端（另一个终端）
cd frontend
npm install
npm run dev

关键端口

服务 端口 说明
后端 API 8080 Spring Boot REST API
前端 5173 Vite 开发服务器
Neo4j HTTP 7474 Neo4j Browser
Neo4j Bolt 7687 Neo4j 数据库连接
PostgreSQL 5432 业务数据存储
Redis 6379 会话/缓存

代码风格

后端 (Java)

  • 遵循 Google Java Style Guide 基本规范
  • 使用 4 空格缩进
  • 类和接口使用 PascalCase
  • 方法和变量使用 camelCase
  • 常量使用 UPPER_SNAKE_CASE
  • 每个公共类和方法应有 Javadoc 注释
  • 使用 Lombok 减少样板代码（@Data、@Builder、@Slf4j 等）

前端 (Vue / TypeScript)

  • 遵循 Vue 官方风格指南 推荐规则
  • 使用 2 空格缩进
  • 组件文件名使用 PascalCase（如 GraphView.vue）
  • 组合式 API (Composition API) 优先
  • 使用 TypeScript 类型注解

通用

  • 每行不超过 120 字符
  • 文件使用 UTF-8 编码
  • 行尾使用 LF（\n）

提交规范

Commit Message 格式

使用 Conventional Commits 格式：

<type>(<scope>): <subject>

<body>

Co-Authored-By: ...

Type 类型

类型 说明
feat 新功能
fix Bug 修复
docs 文档更新
style 代码格式（不影响逻辑）
refactor 代码重构（不新增功能也不修复 Bug）
test 测试相关
chore 构建或辅助工具变更
ci CI/CD 配置变更

示例

feat(qa): add streaming QA endpoint with SSE support

Implement Server-Sent Events streaming for QA responses,
enabling real-time answer generation feedback.

Scope 范围

范围 说明
qa 智能问答模块
parse 代码解析模块
graph 图谱模块
project 项目管理模块
quality 代码质量模块
mcp MCP 服务模块
frontend 前端模块
infra 基础设施
docs 文档

Pull Request 流程

1. 创建分支

# 从 main 创建功能分支
git checkout main
git pull origin main
git checkout -b feat/your-feature-name

分支命名规范：

  • 功能：feat/feature-name
  • 修复：fix/bug-name
  • 重构：refactor/scope-name
  • 文档：docs/what-changed

2. 开发与测试

# 确保测试通过
cd backend && mvn test
cd frontend && npm run lint

# 编写新测试覆盖新增逻辑

3. 提交 PR

  • 标题遵循 Conventional Commits 格式
  • 描述中说明变更内容和原因
  • 关联相关 Issue（如 Closes #123）
  • 确保 CI 通过
  • 请求至少一位 Reviewer

PR 检查清单

  • 代码遵循项目代码风格
  • 新功能有对应测试
  • 所有测试通过
  • 无编译警告
  • 文档已同步更新（如有必要）
  • 无硬编码的密钥或密码

测试要求

后端测试

# 运行全部测试
cd backend
mvn test

# 运行指定测试类
mvn test -Dtest=QAServiceTest

# 运行指定测试方法
mvn test -Dtest=QAServiceTest#testAskV2

单元测试使用 H2 内存数据库，无需外部服务。

集成测试需要启动 Neo4j：

docker-compose up -d neo4j
mvn test -Dtest=QAServiceTest

前端测试

cd frontend
npm run lint    # 代码检查
npm run build   # 构建验证

测试命名

  • 测试类名：XxxTest.java
  • 测试方法名：使用中文或英文描述测试场景，推荐格式 should_ExpectedBehavior_When_Condition

项目结构

详见 README.md 的项目结构章节，关键目录：

  • backend/src/main/java/com/example/ckg/ — 后端源码
  • frontend/src/ — 前端源码
  • docs/ — 项目文档
  • docker/ — Docker 配置

问题反馈

  • 使用 GitHub Issues 提交 Bug 报告或功能建议
  • 提交 Bug 时请包含：复现步骤、期望行为、实际行为、环境信息

行为准则

  • 尊重所有贡献者
  • 建设性的讨论和反馈
  • 专注于对项目最有利的事情