DeepChat
Series

贡献指南

DeepChat

贡献指南

感谢您对 DeepChat 的贡献兴趣！本页面将指导您如何为 DeepChat 项目做出贡献，无论是代码、文档、翻译，还是其他形式的贡献。作为一个开源项目，我们欢迎并高度重视社区的参与。

贡献途径

您可以通过多种方式为 DeepChat 做出贡献：

代码贡献

  1. 修复 Bug

  2. 实现新功能

    • 浏览标记为 enhancement 或 feature request 的 Issues
    • 在实现前，先在相关 Issue 下评论表明您的意图
    • 大型功能应先讨论实现方案

  3. 性能优化

    • 提高应用速度、减少资源消耗
    • 优化数据结构和算法
    • 提升用户体验的各方面改进

  4. 代码重构

    • 改进代码可读性和可维护性
    • 确保在不改变功能的前提下进行重构
    • 遵循项目的代码风格和最佳实践

非代码贡献

  1. 文档改进

    • 修复文档中的错误或不一致内容
    • 增加缺失的内容或解释
    • 提供更清晰的例子和用例
    • 改进文档的组织结构

  2. 翻译工作

    • 将应用界面翻译到其他语言
    • 帮助翻译文档内容
    • 维护和更新现有翻译

  3. 用户支持

    • 在社区论坛和聊天群组中回答问题
    • 创建常见问题的解答
    • 帮助新用户入门

  4. 设计贡献

    • 提供 UI/UX 改进建议
    • 创建或改进图标和图形资源
    • 设计新功能的界面原型

  5. 测试和质量保证

    • 报告 Bug 和使用问题
    • 参与新功能的测试
    • 编写和改进自动化测试

开发环境设置

准备工作

在开始贡献代码前，请确保您已准备好以下内容：

  1. GitHub 账号: 访问 GitHubopen in new window 注册一个账号（如果还没有）
  2. Git 客户端: 安装 Gitopen in new window 或 GitHub Desktop
  3. 开发环境: 根据项目需要安装以下工具
    • Node.js (18.x 或更高版本)
    • npm 或 yarn
    • 推荐的代码编辑器：VS Code

获取源码

  1. Fork 仓库:

  2. 克隆仓库:

    git clone https://github.com/YOUR_USERNAME/deepchat.git
cd deepchat

  3. 设置上游仓库:

    git remote add upstream https://github.com/thinkinai/deepchat.git

安装依赖

# 使用 npm
npm install

# 或使用 yarn
yarn install

运行开发环境

# 开发模式运行应用
npm run dev

# 或使用 yarn
yarn dev

此命令会启动一个本地开发服务器，通常在 http://localhost:3000 上访问。

开发流程

创建新分支

在开始任何工作前，请从最新的主分支创建一个新的功能或修复分支：

# 确保您的主分支是最新的
git checkout main
git pull upstream main

# 创建并切换到新分支
git checkout -b feature/your-feature-name
# 或
git checkout -b fix/issue-you-are-fixing

编码规范

请遵循项目的编码风格和最佳实践：

  1. 代码风格:

    • 项目使用 ESLint 和 Prettier 进行代码格式化
    • 运行 npm run lint 检查代码格式问题
    • 运行 npm run format 自动修复格式问题

  2. 命名约定:

    • 使用有意义的变量和函数名
    • 组件使用 PascalCase（如 UserProfile）
    • 函数和变量使用 camelCase（如 getUserData）
    • 常量使用 UPPER_SNAKE_CASE（如 MAX_RETRY_COUNT）

  3. 注释规范:

    • 为复杂逻辑添加注释
    • 使用 JSDoc 风格为函数添加文档
    • 保持注释与代码同步更新

  4. 提交信息规范:

测试

在提交更改前，请确保您的代码通过以下测试：

  1. 运行现有测试:

    npm run test

  2. 添加新测试:

    • 为新功能添加单元测试
    • 为修复的 Bug 添加回归测试
    • 确保测试覆盖率不会下降

  3. 本地验证:

    • 在提交前在本地开发环境验证您的更改
    • 确保没有控制台错误或警告
    • 测试不同的浏览器和设备（如可能）

提交更改

完成更改并通过测试后，提交您的代码：

# 添加更改的文件
git add .

# 提交更改
git commit -m "feat: add new feature X"
# 或
git commit -m "fix: resolve issue with Y"

# 推送到您的 fork
git push origin feature/your-feature-name

创建 Pull Request

  1. 访问您的 GitHub fork 页面

  2. 点击 "Compare & pull request" 按钮

  3. 填写 PR 模板，包括：

    • 清晰的标题描述您的更改
    • 详细说明实现的功能或修复的问题
    • 关联相关的 Issue（使用 Fixes #123 或 Relates to #456）
    • 添加任何其他相关信息

  4. 提交 PR 后，DeepChat 团队成员将审核您的代码

  5. 可能需要根据反馈进行更改

  6. 一旦通过审核，您的代码将被合并到主分支

文档贡献指南

文档结构

DeepChat 的文档使用 Markdown 格式，位于 docs 目录下：

docs/
├── guide/          # 用户指南
├── api/            # API 文档
├── examples/       # 示例和教程
└── ...

修改文档

  1. 查找需要改进的文档:

    • 检查有 documentation 标签的 Issues
    • 寻找不清晰或过时的内容
    • 确定缺失的主题

  2. 创建文档分支:

    git checkout -b docs/improve-getting-started

  3. 编写文档:

    • 使用清晰简洁的语言
    • 遵循现有文档的风格和格式
    • 加入示例和图片增强理解
    • 修正拼写和语法错误

  4. 预览更改:

    npm run docs:dev

    然后在浏览器中访问显示的地址（通常是 http://localhost:3000）

  5. 提交文档 PR:

    • 遵循与代码贡献相同的 PR 流程
    • 标记为 documentation 类型

文档风格指南

为保持文档一致性，请遵循以下准则：

  1. 语言和风格:

    • 使用简单明了的语言
    • 直接向读者说话（使用"您"而不是"用户"）
    • 使用主动语态而非被动语态
    • 保持专业但友好的语气

  2. 格式和结构:

    • 使用标题组织内容（# 一级标题，## 二级标题，等等）
    • 使用列表和表格增强可读性
    • 代码示例使用代码块（```）包围
    • 重要信息使用引用块（>）突出显示

  3. 图片和媒体:

    • 提供清晰的图片和截图
    • 压缩图片以减少文件大小
    • 为所有图片添加替代文本(alt text)
    • 将图片放在 docs/public/images 目录下

翻译贡献指南

翻译工作流程

  1. 加入翻译团队:

  2. 领取翻译任务:

    • 查看当前翻译优先级
    • 认领未翻译或需要更新的文件

  3. 进行翻译:

    • 翻译文件位于 src/locales/{语言代码}/ 目录
    • 保持原始格式和变量不变
    • 注意文化差异和习惯表达

  4. 提交翻译:

    • 通过 PR 提交翻译内容
    • 在 PR 描述中说明翻译的语言和文件

翻译质量准则

  1. 术语一致性:

    • 查阅并遵循项目术语表
    • 保持技术术语的一致翻译
    • 不确定时保留英文原文（括号内注明译文）

  2. 文化适应性:

    • 考虑目标语言的文化背景
    • 使用当地习惯的表达方式
    • 避免直译导致的理解障碍

  3. 技术准确性:

    • 确保翻译不改变技术含义
    • 理解上下文后再翻译
    • 如有疑问，在 PR 中提出或联系团队

审核过程

代码审核

提交 PR 后，审核流程如下：

  1. 自动检查:

    • CI 会自动运行测试和代码风格检查
    • 确保没有构建错误

  2. 团队审核:

    • 至少一名核心团队成员会审核您的代码
    • 审核重点包括：
      • 代码质量和风格
      • 功能完整性
      • 测试覆盖率
      • 文档完整性

  3. 反馈和迭代:

    • 根据审核意见进行修改
    • 推送更改到同一 PR 分支
    • 回复评论说明您的更改或解释

  4. 最终合并:

    • 通过所有审核后，核心团队成员会合并您的 PR
    • 您的贡献将在下一个版本发布时包含

审核标准

我们在审核时会考虑以下几点：

  • 可用性: 功能是否易于理解和使用？
  • 可维护性: 代码是否易于维护和扩展？
  • 性能: 实现是否高效？
  • 兼容性: 是否与现有功能和API兼容？
  • 测试: 是否有足够的测试覆盖？
  • 文档: 是否有适当的文档？

获得帮助

如果您在贡献过程中需要帮助：

  1. 提问渠道:

    • GitHub Issues: 技术问题和讨论
    • Discord #development 频道: 快速问答
    • 开发者邮件列表: 深入讨论

  2. 贡献者指导:

    • 初次贡献者可以寻找标有 good first issue 的任务
    • 需要指导时，可以在 Issue 或 PR 中 @提及维护者

  3. 开发会议:

    • 加入双周开发者会议（查看社区日历）
    • 讨论正在进行的工作和计划
    • 获取直接反馈和支持

贡献者认可

我们高度重视所有贡献者的工作，认可方式包括：

  1. 贡献者名单:

  2. 贡献者徽章:

    • 在社区论坛获得特殊的贡献者徽章
    • 不同级别的贡献获得不同徽章

  3. 功能署名:

    • 重大功能的文档中会包含实现者的署名
    • 发布说明会提及主要贡献者

  4. 社区亮点:

    • 在社区通讯和社交媒体上展示优秀贡献
    • 定期的贡献者专访

行为准则

我们希望 DeepChat 社区成为一个友好、包容的环境。所有贡献者都应遵守行为准则open in new window，主要包括：

  • 使用友好和包容的语言
  • 尊重不同的观点和经验
  • 优雅地接受建设性批评
  • 关注社区最佳利益
  • 对其他社区成员表示同理心

任何不当行为可以通过电子邮件 conduct@deepchat.thinkinai.xyz 私下报告。

常见问题

问: 我是新手，如何开始贡献？ 答: 查找标记为 good first issue 的任务，这些通常较简单且有清晰的指导。也可以从文档改进或错误报告开始。

问: 如何知道某个问题是否已有人在处理？ 答: 查看 Issue 的评论，通常有人会表明他们正在处理。如果不确定，可以先发表评论询问。

问: PR 合并需要多长时间？ 答: 这取决于更改的复杂性。简单修复通常在几天内审核，而大型功能可能需要更长时间。如果超过一周没有响应，可以在 PR 中评论请求审核。

问: 我能为子项目或插件做贡献吗？ 答: 是的，DeepChat 有多个子项目和插件。每个可能有自己的贡献指南，但基本原则相似。

问: 我的贡献没被接受，下一步怎么办？ 答: 不要气馁！询问为什么，了解项目的需求，或寻找其他可以贡献的方式。有时候一个贡献不合适可能只是因为时机或方向问题。

感谢您对 DeepChat 的贡献！每一份贡献，无论大小，都会帮助我们构建更好的工具和社区。我们期待看到您的创意和工作。

贡献流程

这里应放置一张贡献流程或社区贡献者的图片。

Last Updated 3/26/2025, 9:20:57 AM
ON THIS PAGE