XCDesktop/CONTRIBUTING.md

贡献指南

感谢你对 XCDesktop 项目的兴趣！我们欢迎任何形式的贡献，包括但不限于：

• 🐛 报告 Bug
• 💡 提出新功能建议
• 📝 完善文档
• 💻 提交代码修复或新功能
• 🔧 改进构建流程

开发环境搭建

前置要求

• Node.js 18+
• npm 9+
• Git

克隆项目

git clone https://github.com/your-repo/XCDesktop.git
cd XCDesktop

安装依赖

npm install

启动开发服务器

# 启动前端开发服务器
npm run dev

# 或启动完整 Electron 开发环境（推荐）
npm run electron:dev

代码检查

# 运行 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 规范：

<type>(<scope>): <description>

[optional body]

[optional footer]

类型（type）

类型	说明
feat	新功能
fix	Bug 修复
docs	文档更新
style	代码格式调整
refactor	代码重构
perf	性能优化
test	测试相关
chore	构建或辅助工具变动

示例

# 新功能
git commit -m "feat(file-system): 添加文件拖拽功能"

# Bug 修复
git commit -m "fix(editor): 修复数学公式渲染错误"

# 文档更新
git commit -m "docs: 更新 README 安装步骤"

Pull Request 流程

创建分支

# 从主分支创建新分支
git checkout -b feature/your-feature-name

# 或创建修复分支
git checkout -b fix/bug-description

提交代码

# 暂存修改
git add .

# 提交修改
git commit -m "feat(module): 添加新功能"

推送分支

# 推送到远程仓库
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. 使用对应的模板并提供详细信息

行为准则

请尊重所有参与项目的开发者，保持友好和专业的交流环境。

---

感谢你的贡献！🎉