203 lines
3.9 KiB
Markdown
203 lines
3.9 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对 XCDesktop 项目的兴趣！我们欢迎任何形式的贡献，包括但不限于：
|
||
|
||
- 🐛 报告 Bug
|
||
- 💡 提出新功能建议
|
||
- 📝 完善文档
|
||
- 💻 提交代码修复或新功能
|
||
- 🔧 改进构建流程
|
||
|
||
## 开发环境搭建
|
||
|
||
### 前置要求
|
||
|
||
- Node.js 18+
|
||
- npm 9+
|
||
- Git
|
||
|
||
### 克隆项目
|
||
|
||
```bash
|
||
git clone https://github.com/your-repo/XCDesktop.git
|
||
cd XCDesktop
|
||
```
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 启动开发服务器
|
||
|
||
```bash
|
||
# 启动前端开发服务器
|
||
npm run dev
|
||
|
||
# 或启动完整 Electron 开发环境（推荐）
|
||
npm run electron:dev
|
||
```
|
||
|
||
### 代码检查
|
||
|
||
```bash
|
||
# 运行 ESLint
|
||
npm run lint
|
||
|
||
# 运行 TypeScript 类型检查
|
||
npm run check
|
||
```
|
||
|
||
## 代码规范
|
||
|
||
### 命名规范
|
||
|
||
- **文件命名**: 使用 kebab-case（如 `file-system.tsx`）
|
||
- **组件命名**: 使用 PascalCase（如 `FileTree.tsx`）
|
||
- **函数命名**: 使用 camelCase（如 `useFileTree`）
|
||
- **常量命名**: 使用 UPPER_SNAKE_CASE
|
||
|
||
### TypeScript 规范
|
||
|
||
- 尽量使用明确的类型定义，避免使用 `any`
|
||
- 优先使用接口（interface）而不是类型别名（type）定义对象结构
|
||
- 导出类型时使用 `export type`
|
||
|
||
### React 规范
|
||
|
||
- 使用函数组件和 Hooks
|
||
- 组件文件以 `.tsx` 为扩展名
|
||
- 纯逻辑文件以 `.ts` 为扩展名
|
||
|
||
### CSS 规范
|
||
|
||
- 使用 Tailwind CSS 进行样式开发
|
||
- 避免直接编写 CSS，优先使用 Tailwind 工具类
|
||
- 自定义样式放在组件同名的 `.module.css` 文件中
|
||
|
||
### Git 提交规范
|
||
|
||
我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
||
|
||
```
|
||
<type>(<scope>): <description>
|
||
|
||
[optional body]
|
||
|
||
[optional footer]
|
||
```
|
||
|
||
#### 类型（type）
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| feat | 新功能 |
|
||
| fix | Bug 修复 |
|
||
| docs | 文档更新 |
|
||
| style | 代码格式调整 |
|
||
| refactor | 代码重构 |
|
||
| perf | 性能优化 |
|
||
| test | 测试相关 |
|
||
| chore | 构建或辅助工具变动 |
|
||
|
||
#### 示例
|
||
|
||
```bash
|
||
# 新功能
|
||
git commit -m "feat(file-system): 添加文件拖拽功能"
|
||
|
||
# Bug 修复
|
||
git commit -m "fix(editor): 修复数学公式渲染错误"
|
||
|
||
# 文档更新
|
||
git commit -m "docs: 更新 README 安装步骤"
|
||
```
|
||
|
||
## Pull Request 流程
|
||
|
||
### 创建分支
|
||
|
||
```bash
|
||
# 从主分支创建新分支
|
||
git checkout -b feature/your-feature-name
|
||
|
||
# 或创建修复分支
|
||
git checkout -b fix/bug-description
|
||
```
|
||
|
||
### 提交代码
|
||
|
||
```bash
|
||
# 暂存修改
|
||
git add .
|
||
|
||
# 提交修改
|
||
git commit -m "feat(module): 添加新功能"
|
||
```
|
||
|
||
### 推送分支
|
||
|
||
```bash
|
||
# 推送到远程仓库
|
||
git push origin feature/your-feature-name
|
||
```
|
||
|
||
### 创建 Pull Request
|
||
|
||
1. 访问项目仓库
|
||
2. 点击 "Compare & pull request"
|
||
3. 填写 PR 标题和描述
|
||
4. 提交 PR
|
||
|
||
### PR 标题规范
|
||
|
||
请使用与提交信息相同的格式：
|
||
|
||
```
|
||
feat(file-system): 添加文件搜索功能
|
||
fix(editor): 修复保存内容丢失问题
|
||
```
|
||
|
||
## 项目结构概览
|
||
|
||
```
|
||
XCDesktop/
|
||
├── src/ # 前端源码
|
||
│ ├── components/ # UI 组件
|
||
│ ├── contexts/ # React Context
|
||
│ ├── hooks/ # 自定义 Hooks
|
||
│ ├── lib/ # 工具库
|
||
│ ├── modules/ # 功能模块
|
||
│ └── pages/ # 页面组件
|
||
├── api/ # 后端 API
|
||
├── electron/ # Electron 主进程
|
||
├── shared/ # 共享类型定义
|
||
└── notebook/ # 笔记存储目录
|
||
```
|
||
|
||
### 添加新模块
|
||
|
||
如需添加新功能模块，请参考以下步骤：
|
||
|
||
1. 在 `src/modules/` 下创建新模块目录
|
||
2. 在 `shared/modules/` 下定义模块配置
|
||
3. 在后端 `api/modules/` 下实现 API 接口
|
||
4. 使用模块注册系统进行注册
|
||
|
||
## 问题反馈
|
||
|
||
如果你发现了 Bug 或有新功能建议，请：
|
||
|
||
1. 搜索是否已有类似问题
|
||
2. 如果没有，创建新的 Issue
|
||
3. 使用对应的模板并提供详细信息
|
||
|
||
## 行为准则
|
||
|
||
请尊重所有参与项目的开发者，保持友好和专业的交流环境。
|
||
|
||
---
|
||
|
||
感谢你的贡献！🎉
|