贡献指南
如何为 android-xiaozhi 项目贡献代码 🚀
前言
感谢您对 android-xiaozhi 项目感兴趣！我们非常欢迎社区成员参与贡献，无论是修复错误、改进文档还是添加新功能。本指南将帮助您了解如何向项目提交贡献。
开发环境准备
基本要求
- Flutter SDK 3.7.0 或更高版本
- Dart SDK 3.7.0 或更高版本
- Git 版本控制系统
- Android Studio 或 Visual Studio Code (带 Flutter 插件)
- Android SDK (用于 Android 开发)
- Xcode (用于 iOS 开发，仅 macOS)
获取源代码
首先，在 GitHub 上 Fork 本项目到您自己的账号
- 访问 android-xiaozhi 项目页面
- 点击右上角的"Fork"按钮
- 等待 Fork 完成，您将被重定向到您的仓库副本
克隆您 fork 的仓库到本地：
git clone https://github.com/YOUR_USERNAME/xiaozhi-android.git
cd xiaozhi-android-client- 添加上游仓库作为远程源：
git remote add upstream https://github.com/TOM88812/xiaozhi-android-client.git你可以使用 git remote -v 命令确认远程仓库已正确配置：
git remote -v
# 应显示：
# origin https://github.com/YOUR_USERNAME/xiaozhi-android-client.git (fetch)
# origin https://github.com/YOUR_USERNAME/xiaozhi-android-client.git (push)
# upstream https://github.com/TOM88812/xiaozhi-android-client.git (fetch)
# upstream https://github.com/TOM88812/xiaozhi-android-client.git (push)安装开发依赖
# 安装Flutter依赖
flutter pub get开发流程
与主仓库保持同步
在开始工作之前，确保您的本地仓库与主项目保持同步是非常重要的。以下是同步本地仓库的步骤：
- 切换到您的主分支（
main）：
git checkout main- 拉取上游仓库的最新更改：
git fetch upstream- 将上游主分支的更改合并到您的本地主分支：
git merge upstream/main- 将更新后的本地主分支推送到您的 GitHub 仓库：
git push origin main创建分支
在开始任何工作之前，请确保从最新的上游主分支创建新的分支：
# 获取最新的上游代码（如上节所述）
git fetch upstream
git checkout -b feature/your-feature-name upstream/main为分支命名时，可以遵循以下约定：
feature/xxx：新功能开发fix/xxx：修复 bugdocs/xxx：文档更新test/xxx：测试相关工作refactor/xxx：代码重构
编码规范
我们使用 Flutter 官方推荐的代码风格指南。在提交代码前，请确保您的代码符合以下要求：
- 使用 2 个空格进行缩进
- 行长度不超过 120 个字符
- 使用有意义的变量和函数名称
- 为公共 API 添加文档注释
- 使用 Dart 类型系统
我们推荐使用 Flutter 的静态代码分析工具来帮助您遵循编码规范：
# 使用 dart analyze 检查代码
flutter analyze测试
在提交之前，请确保所有测试都能通过：
flutter test提交变更
提交前的检查清单
在提交您的代码之前，请确保完成以下检查：
- 代码是否符合 Flutter 编码规范
- 是否添加了必要的测试用例
- 所有测试是否通过
- 是否添加了适当的文档
- 是否解决了您计划解决的问题
- 是否与最新的上游代码保持同步
提交变更
在开发过程中，养成小批量、频繁提交的习惯。这样可以使您的更改更容易跟踪和理解：
# 查看更改的文件
git status
# 暂存更改
git add lib/feature.dart test/feature_test.dart
# 提交更改
git commit -m "feat: add new feature X"解决冲突
如果您在尝试合并上游更改时遇到冲突，请按照以下步骤解决：
- 首先了解冲突的位置：
git status- 打开冲突文件，您会看到类似以下标记：
上游代码- 修改文件以解决冲突，删除冲突标记
- 解决完所有冲突后，暂存并提交：
git add .
git commit -m "fix: resolve merge conflicts"提交规范
我们使用约定式提交规范来格式化 Git 提交消息。提交消息应该遵循以下格式：
<类型>[可选 作用域]: <描述>
[可选 正文]
[可选 脚注]常用的提交类型包括：
feat：新功能fix：错误修复docs：文档更改style：不影响代码含义的变更（如空格、格式化等）refactor：既不修复错误也不添加功能的代码重构perf：提高性能的代码更改test：添加或修正测试chore：对构建过程或辅助工具和库的更改
例如：
feat(tts): 添加新的语音合成引擎支持
添加对百度语音合成API的支持，包括以下功能：
- 支持多种音色选择
- 支持语速和音量调节
- 支持中英文混合合成
修复 #123推送更改
完成代码更改后，将您的分支推送到您的 GitHub 仓库：
git push origin feature/your-feature-name如果您已经创建了 Pull Request，并且需要更新它，只需再次推送到同一分支即可：
# 在进行更多更改后
git add .
git commit -m "refactor: improve code based on feedback"
git push origin feature/your-feature-name创建 Pull Request 前同步最新代码
在创建 Pull Request 前，建议再次与上游仓库同步，以避免潜在的冲突：
# 获取上游最新代码
git fetch upstream
# 将上游最新代码变基到您的特性分支
git rebase upstream/main
# 如果出现冲突，解决冲突并继续变基
git add .
git rebase --continue
# 强制推送更新后的分支到您的仓库
git push --force-with-lease origin feature/your-feature-name注意：使用 --force-with-lease 比直接使用 --force 更安全，它可以防止覆盖他人推送的更改。
创建 Pull Request
当您完成功能开发或问题修复后，请按照以下步骤创建 Pull Request：
- 将您的更改推送到 GitHub：
git push origin feature/your-feature-name访问 GitHub 上您 fork 的仓库页面，点击 "Compare & pull request" 按钮
填写 Pull Request 表单：
- 使用清晰的标题，遵循提交消息格式
- 在描述中提供详细信息
- 引用相关 issue（使用
#issue编号格式） - 如果这是一个进行中的工作，请添加
[WIP]前缀到标题
提交 Pull Request，等待项目维护者审核
Pull Request 的生命周期
- 创建：提交您的 PR
- CI 检查：自动化测试和代码风格检查
- 代码审核：维护者会审核您的代码并提供反馈
- 修订：根据反馈修改您的代码
- 批准：一旦您的 PR 被批准
- 合并：维护者会将您的 PR 合并到主分支
文档贡献
如果您想改进项目文档，请按照以下步骤操作：
按照上述步骤 Fork 项目并克隆到本地
文档位于
documents/docs目录下，使用 Markdown 格式安装文档开发依赖：
cd documents
pnpm install- 启动本地文档服务器：
pnpm docs:dev在浏览器中访问
http://localhost:5173/xiaozhi-android/预览您的更改完成更改后，提交您的贡献并创建 Pull Request
文档编写准则
- 使用清晰、简洁的语言
- 提供实际示例
- 对复杂概念进行详细解释
- 包含适当的截图或图表（需要时）
- 避免技术术语过多，必要时提供解释
- 保持文档结构一致
问题反馈
如果您发现了问题但暂时无法修复，请在 GitHub 上创建 Issue。创建 Issue 时，请包含以下信息：
- 问题的详细描述
- 重现问题的步骤
- 预期行为和实际行为
- 您的操作系统和 Python 版本
- 相关的日志输出或错误信息
代码审核
提交 Pull Request 后，项目维护者将会审核您的代码。在代码审核过程中：
- 请耐心等待反馈
- 及时响应评论和建议
- 必要时进行修改并更新您的 Pull Request
- 保持礼貌和建设性的讨论
处理代码审核反馈
- 认真阅读所有评论和建议
- 针对每个要点作出回应或更改
- 如果您不同意某个建议，礼貌地解释您的理由
- 修改完成后，在 PR 中留言通知审核者
成为项目维护者
如果您持续为项目做出有价值的贡献，您可能会被邀请成为项目的维护者。作为维护者，您将有权限审核和合并其他人的 Pull Request。
维护者的职责
- 审核 Pull Request
- 管理 issue
- 参与项目规划
- 回答社区问题
- 帮助引导新贡献者
行为准则
请尊重所有项目参与者，遵循以下行为准则：
- 使用包容性语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注社区最佳利益
- 对其他社区成员表示同理心
常见问题解答
我应该从哪里开始贡献？
- 查看标记为 "good first issue" 的问题
- 修复文档中的错误或不清晰的部分
- 添加更多测试用例
- 解决您自己在使用过程中发现的问题
我提交的 PR 已经很久没有回应了，我该怎么办？
在 PR 中留言，礼貌地询问是否需要进一步的改进或澄清。请理解维护者可能很忙，需要一些时间来审核您的贡献。
我可以贡献哪些类型的更改？
- 错误修复
- 新功能
- 性能改进
- 文档更新
- 测试用例
- 代码重构
致谢
再次感谢您为项目做出贡献！您的参与对我们非常重要，共同努力让 android-xiaozhi 变得更好！