第21章 参与贡献
Developer Contributing How to contribute to Voicebox 感谢你参与 Voicebox 的贡献！本指南将帮助你快速上手。
行为准则
保持尊重与包容 欢迎新成员并帮助他们学习 提供建设性的反馈 尊重不同的观点和经历
开始之前 在开始贡献之前，请确保你已：
阅读文档以理解 Voicebox 的工作原理 搭建开发环境 — 参见 开发环境搭建 探索代码库以了解项目结构 查看 docs/PROJECT_STATUS.md — 这是记录优先任务（Tier 1 → 3）、架构瓶颈以及正在评估的候选 TTS 引擎（包括部分引擎被排期至后端的原因）的动态工程路线图 检查现有 issues，确认是否有人正在处理类似的问题
贡献方式 报告 Bug 发现 Bug？请打开一个 issue 并提供复现步骤 提出功能需求 有个想法？发起讨论或打开一个 issue 改进文档 修复拼写错误，添加示例，或澄清说明 编写代码 修复 Bug、添加功能或优化性能
开发流程 1. Fork & Clone # 在 GitHub 上 Fork 仓库 # 然后克隆你的 fork git clone https://github.com/YOUR_USERNAME/voicebox.git cd voicebox 2. 创建分支 使用描述性强的分支名称： # 用于功能开发 git checkout -b feature/voice-effects
# 用于修复 Bug git checkout -b fix/audio-playback-issue
# 用于文档更新 git checkout -b docs/api-examples 3. 进行更改 请遵循以下指南： ▶ 代码风格 TypeScript/React: 使用 TypeScript 严格模式 优先使用带 hooks 的函数式组件 使用命名导出 使用 Biome 格式化（自动运行） Python: 遵循 PEP 8 使用类型提示 对 I/O 使用 async/await 使用 docstring 记录函数 Rust: 遵循 Rust 惯例 使用有意义的命名 显式处理错误 运行 rustfmt ▶ 提交信息 编写清晰、描述性强的 commit message： # 良好示例 git commit -m "Add voice profile export feature" git commit -m "Fix audio playback stopping after 30 seconds"
# 避免的示例 git commit -m "Update code" git commit -m "Fix bug" 格式要求： 使用祈使句（"Add feature" 而非 "Added feature"） 首行保持在 50 个字符以内 如有必要，添加详细描述 ▶ 测试 在应用中手动测试你的更改 确保后端 API 端点正常工作 检查 TypeScript/Python 错误 验证 UI 组件渲染正确 尽可能添加自动化测试
4. 推送并创建 PR # 推送你的分支 git push origin feature/your-feature-name
# 然后在 GitHub 上创建 pull request Pull Request 指南 创建 pull request 时： 示例： "Add voice profile export functionality" "Fix audio playback stopping after 30 seconds" "Improve generation speed with caching" 包含： 你做了哪些更改 为什么做这些更改 如何测试它们 截图（针对 UI 更改） 引用相关的 issues
如果行为发生变化，更新相关文档 为新端点添加 API 文档 如有必要，更新 README
代码符合风格指南 文档已更新 更改已测试 无破坏性更改（或已记录） CHANGELOG.md 已更新
项目结构 web/scripts/ 贡献领域 Bug 修复
检查现有 issues 中的 Bug 彻底测试你的修复 尽可能添加回归测试 新功能
在提出工作之前，检查 docs/PROJECT_STATUS.md 和路线图 — 状态文档列出了优先任务（Tier 1 → 3）、已知的架构瓶颈以及已在评估中的候选 TTS 引擎（包括部分已被排期的原因） 先在一个 issue 中讨论主要功能 保持功能聚焦且范围明确 添加新的 TTS 引擎？参见 TTS 引擎了解分阶段工作流程
文档
提高清晰度并修复拼写错误 添加代码示例 创建教程或指南 记录 API 端点 UI/UX 改进
提高可访问性 增强视觉设计 优化性能 添加动画/过渡效果 基础设施
改进构建过程 添加 CI/CD 改进 优化 bundle 大小 添加测试基础设施 API 开发 添加新的 API 端点时： 在 backend/main.py 中: @app.post("/api/new-endpoint") async def new_endpoint(data: RequestModel) -> ResponseModel: """Endpoint description.""" # 实现 return response 在 backend/models.py 中: class RequestModel(BaseModel): field: str
class ResponseModel(BaseModel): result: str just generate-api 这将使用类型安全的绑定更新 TypeScript 客户端。API 文档从 OpenAPI schema 自动生成。确保你的端点有适当的 docstring 和类型提示，然后重新生成文档： just generate-api 测试 目前测试主要依赖手动进行。添加测试时： 后端： cd backend pytest 前端： bun run test E2E（未来）： bun run test:e2e 发布流程 版本发布由维护者使用 bumpversion 管理： # 提升版本号 (patch, minor, 或 major) bumpversion patch
# 带标签推送 git push && git push --tags 当推送标签时，GitHub Actions 会自动构建并发布版本。 社区
GitHub Issues: 报告 Bug 和功能请求 GitHub Discussions: 一般性问题和想法 Discord: 实时聊天（即将上线）
致谢 贡献者将在以下地方获得认可：
CHANGELOG.md GitHub 贡献者列表 发布说明
许可证 通过贡献，你同意你的贡献将按照 MIT License 授权。 有问题？ 如果你有疑问：
检查文档 阅读 docs/PROJECT_STATUS.md 了解当前的工程优先级 搜索现有 issues 打开一个新的 issue 或讨论 查看仓库中的 CONTRIBUTING.md
感谢你为 Voicebox 做出贡献！ 🎉 在 GitHub 上编辑 架构 了解 Voicebox 的技术架构 构建 了解 Voicebox 如何针对生产环境构建
