从 Fork 到合并：完整流程
%%{init: {'theme': 'default', 'themeVariables': { 'primaryColor': '#fffaf3', 'primaryTextColor': '#1d2a30', 'primaryBorderColor': '#20323a', 'lineColor': '#66757d', 'secondaryColor': '#f5efe6', 'tertiaryColor': '#ffffff', 'fontFamily': 'Inter, system-ui, sans-serif', 'textColor': '#1d2a30', 'nodeBkg': '#ffffff', 'nodeBorder': '#20323a', 'nodeTextColor': '#1d2a30', 'clusterBkg': '#f5efe6', 'clusterBorder': '#20323a', 'titleColor': '#1d2a30', 'edgeLabelBackground': '#ffffff', 'edgeLabelColor': '#66757d', 'arrowheadColor': '#66757d'}}}%%
flowchart LR
classDef localBox fill:#dbe8f7,stroke:#4b7eb4,stroke-width:2px,color:#2a4a6a,font-weight:500
classDef checkNode fill:#f8e5b7,stroke:#cc951e,stroke-width:2.5px,color:#7a5a0a,font-weight:500
classDef remoteBox fill:#f6d0c3,stroke:#ca6a49,stroke-width:2px,color:#7a3a28,font-weight:500
classDef successBox fill:#dff0e6,stroke:#5f9e77,stroke-width:2.5px,color:#2d5a3f,font-weight:600
classDef step fill:#ffffff,stroke:#66757d,stroke-width:1.5px,color:#1d2a30
subgraph LOCAL["💻 你的本地"]
direction LR
A([Fork 仓库]):::step --> B([切分支]):::step
B --> C([改代码]):::step
C --> D{{跑 ruff + pytest}}:::checkNode
D --> E([push 到 Fork]):::step
end
E --> F([在 GitHub 开 PR]):::remoteBox
F --> G([Review]):::remoteBox
G --> H([合并到 main]):::successBox
# 1. Fork 后 clone 下来
git clone https://github.com/<你的用户名>/PhyAgentOS.git
cd PhyAgentOS
# 2. 加 upstream 方便同步
git remote add upstream https://github.com/SYSU-HCP-EAI/PhyAgentOS.git
# 3. 切分支（命名见下方建议）
git checkout -b feat/my-robot-driver
# 4. 开发完 push 到自己的 Fork
git push origin feat/my-robot-driver
# 5. 去 GitHub 页面点 "Open Pull Request"
分支命名参考：
feat/xxx— 新功能 / 新 driverfix/xxx— 修 bugdocs/xxx— 改文档refactor/xxx— 重构，不改行为
提交前必须跑的三项检查
建议在本地先完成检查，避免 CI 构建失败后再行修复。这三项检查均配置在 pyproject.toml 中，直接执行即可。
代码格式
ruff check .
ruff format .单元测试
pytest tests/
# 或只跑相关测试
pytest tests/test_hal_base_driver.py安装 dev 依赖
pip install -e ".[dev]"类型检查（建议）
# 读一下你改的方法调用处，
# 确认参数类型没有明显错配PR 描述规范
请按照以下模板撰写 PR 描述，清晰的说明有助于加快 Review 进度。
## 改了什么
一句话总结 + 逐条列出关键文件和逻辑变更。
## 怎么验证的
- 本地跑过什么命令？结果如何？
- 真机/仿真器验证的日志或截图（driver/plugin 必填）
- 文档渲染是否正常（docs 必填）
## 关联 Issue
Closes #123Driver / 插件 PR
必须附带：profile 路径、启动命令、至少一条动作的执行记录。
Bug Fix PR
必须说明：怎么复现、根因、修复后验证结果。有 Issue 请引用。
Docs PR
必须说明：改了哪几页、为什么改、哪里需要重点看。
Issue 分类：先对齐再动手
如不确定具体实现方案，建议先通过 Issue 进行讨论。以下为常用标签，正确标注有助于维护者快速响应。
| 标签 | 什么时候用 | 最好带上什么 |
|---|---|---|
| bug | 功能异常、崩溃、行为和文档对不上 | 复现步骤、环境信息、错误日志 |
| feature | 想要新能力、新工具、新协议字段 | 使用场景、期望接口、是否愿意自己做 |
| driver-request | 希望支持新机器人或硬件 | 设备型号、是否有 SDK、进度状态 |
| documentation | 文档缺了、错了、看不懂 | 具体页面、当前内容、建议怎么改 |
| good first issue | 适合新手的简单任务 | 明确范围、可参照的现有代码 |
合并门槛
Review 的目的是确保这段代码下一个人能看懂、能维护。以下四条全绿才能合并：
- CI 全绿 — Lint 和测试不能挂。
- 至少 1 个 Approve — 核心架构或协议变更建议等 2 个 Maintainer。
- 够自解释 — 复杂逻辑要有注释或文档。
- 不破坏现有接口 — 除非提前在 Issue/PR 里说明了迁移方案。
大型 PR 可能会被要求拆分为多个小 PR，以便加快 Review 进度并降低回滚风险。
第一次贡献？从这些开始
没硬件也能做
- 修文档错别字或死链
- 给已有 driver 补测试用例
- 优化文档站样式或导航
有硬件更好做
- 给新机器人写最小 driver + profile
- 补充一个 ROS2 adapter 的模板
- 写一个真机部署的 README