--- title: 贡献指南 description: 如何为 py-xiaozhi 项目贡献代码 sidebar: false outline: deep ---
# 贡献指南

如何为 py-xiaozhi 项目贡献代码 🚀

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