Switchyard LLM路由贡献者指南：从Fork仓库到DCO签名的完整PR流程

Switchyard LLM路由贡献者指南：从Fork仓库到DCO签名的完整PR流程

【免费下载链接】SwitchyardSwitchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.项目地址: https://gitcode.com/GitHub_Trending/switch/Switchyard

Switchyard 是一个开源的LLM 路由项目：它让 LLM 应用在不改变原生 OpenAI / Anthropic API 兼容性的前提下，灵活地在多个模型和提供商之间路由流量，实现成本控制与性能优化。如果你想为它贡献代码，本文是一份从零开始的贡献者指南——带你走通Fork 仓库 → 建分支 → 本地检查 → Conventional Commits → DCO 签名 → 提交 PR的完整流程，每一步都给出可操作的命令和避坑提示。

动手前：30秒看懂仓库结构

Switchyard 用 Rust 编写，附带 Python 绑定。在提交任何改动前，先确认你要改的文件属于哪个 crate（每个 crate 有明确职责边界，写错位置是新手最常见的 PR 问题）：

详细边界约定见 AGENTS.md 和 DEVELOPMENT.md。

💡小改动（错别字、文档、100 行以内的修复）可以直接开 PR；大改动（新功能、重构）请先开 Issue 与维护者确认方向，避免白做。

第1步：Fork 仓库并配置开发环境

先 Fork 仓库，然后克隆到你的本地（upstream指向官方仓库，方便日后同步）：

git clone https://gitcode.com/GitHub_Trending/switch/Switchyard cd Switchyard git remote add upstream <你的Fork地址>

Switchyard 使用 uv 管理 Python 环境，一条uv sync即可装好依赖和开发工具（pytest、ruff、mypy）：

uv sync source .venv/bin/activate

最后安装本地 Git 钩子——它会替你提前执行 CI 里的两项关键检查（lint 与提交信息格式），强烈建议装：

uvx pre-commit install --install-hooks --hook-type pre-commit --hook-type commit-msg

钩子配置定义在 .pre-commit-config.yaml 中。

第2步：用规范前缀命名功能分支

分支名直接决定评审者对改动类型的预期，请使用以下前缀：

• feature/...— 新功能，如feature/add-new-router-backend
• fix/...— Bug 修复，如fix/async-context-leak
• docs/...— 文档更新
• refactor/...— 不改变行为的结构调整
• test/...— 测试补充

git checkout -b feature/your-feature

第3步：本地跑通全部检查（与 CI 同款）

所有改动在推送前必须通过 5 道关卡，它们在 CI 上每次 push 都会重跑。与其在 CI 上等失败，不如本地先跑：

uv run ruff check . # Python lint，要求 0 错误 uv run mypy switchyard # 严格类型检查 uv run pytest tests/ -v # Python 测试 cargo fmt --all --check # Rust 格式化 cargo clippy --workspace --all-targets -- -D warnings # Rust lint cargo test --workspace # Rust 测试

lint 报错太多？先让工具自动修复一轮：

uv run ruff check --fix .

✅ 好消息：默认单元测试不需要任何 API Key、不访问网络，本地即可完整跑通。

第4步：Conventional Commits + DCO 签名提交

这是最容易卡壳的一步，两个要求缺一不可：

① 提交信息必须符合 Conventional Commits 规范（由commit-msg钩子和本地 commitlint 强制校验，规则见 .commitlintrc.json）：

• ✅fix: handle async context cleanup in ProxyContext
• ✅feat: add stage-router routing backend
• ❌Fixed stuff/Updated code

可用的类型前缀：featfixdocsrefactortestperfbuildcichorerevertstyle，scope 可省略，如fix(cli): preserve command arguments。

② 每个提交必须带 DCO 签名（Developer Certificate of Origin，开发者原创声明）。只需在 commit 时加-s参数：

git commit -s -m "feat: add stage-router routing backend"

它会在提交信息末尾自动追加：

Signed-off-by: Your Name <your@email.com>

这等价于你以书面形式声明：该代码由你原创、或有权利以项目许可证提交。没有 Signed-off-by 的提交会被 DCO 检查直接拒绝，且通常无法补救——这是新手 PR 被拒的头号原因。完整的 DCO 声明文本见 CONTRIBUTING.md 的 "Signing Your Work" 章节。

🤖 用 AI 工具写代码是被允许的，但你必须理解并能解释 PR 中的每一处改动。

第5步：推送、开 PR 并迎接评审

本地检查全绿后推送分支，向main发起 PR：

git push -u origin feature/your-feature

开 PR 时注意 4 个要点：

1. 按模板填写描述：项目提供了 PR 模板，只需回答 What（改了什么）、Why（动机）、Notes for reviewers（评审者从哪看起）三个问题。
2. PR 标题也用 Conventional Commits 格式——因为合并时采用 Squash Merge，PR 标题会成为最终提交信息。
3. 关联 Issue：在描述中写Closes #42，合并后自动关闭。
4. 按建议追加 commit，不要 force-push：评审反馈请用后续提交回应，除非维护者明确要求。

评审是自动发起的：.github/CODEOWNERS 已配置所有 PR 必须由核心团队（switchyard_team）审核，你无需手动指定评审人。合并前CI Success与DCO两个状态检查是硬性要求。

PR 被卡住？常见原因速查

写在最后

完整的贡献流程以 CONTRIBUTING.md 为准，环境搭建细节见 DEVELOPMENT.md，行为准则见 CODE_OF_CONDUCT.md。Switchyard 欢迎从错别字修复到新功能的一切大小的贡献——现在，Fork 一个仓库，签下你的第一个Signed-off-by吧 🚀

【免费下载链接】SwitchyardSwitchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.项目地址: https://gitcode.com/GitHub_Trending/switch/Switchyard