File size: 4,527 Bytes
87fc638 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | # 贡献指南 Contributing Guide
感谢你愿意为 **Letools-Learning** 贡献代码、文档或想法！本指南适用于所有外部和内部贡献者。
> 提交贡献即表示你同意遵守本仓库的 [行为准则 (Code of Conduct)](CODE_OF_CONDUCT.md)。
## 在开始之前 Before You Start
- **小改动**（typo、格式、文档补充）：直接发 PR，无需先开 Issue。
- **新功能 / 新模型接入 / 架构变更**：请**先开 Issue 讨论**，避免做完才发现方向不合适。
- **Bug 修复**：建议先开 Issue 描述复现路径，再 PR 关联。
## 开发流程 Development Workflow
### 1. Fork & Clone
```bash
git clone https://github.com/<your-name>/LeTools-Learning.git
cd LeTools-Learning
git remote add upstream https://github.com/LejuRobotics/LeTools-Learning.git
git submodule update --init --recursive
```
### 2. 创建特性分支 Branch Strategy
**禁止直接在 `master` 上提交。** 请基于 `master` 切新分支：
| 分支类型 | 命名规范 | 用途 |
| --- | --- | --- |
| 功能 | `feat/<short-name>` | 新功能 / 新模型 |
| 修复 | `fix/<short-name>` | Bug 修复 |
| 文档 | `docs/<short-name>` | 仅改文档 |
| 重构 | `refactor/<short-name>` | 不改变行为的内部重构 |
示例：
```bash
git checkout master && git pull upstream master
git checkout -b feat/add-newmodel-adapter
```
### 3. 提交规范 Commit Message
采用 [Conventional Commits](https://www.conventionalcommits.org/) 风格，便于自动生成 CHANGELOG：
```
<type>(<scope>): <subject>
<body, 可选>
```
`type` 取值：
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档变更
- `refactor`: 重构（不改行为）
- `perf`: 性能优化
- `test`: 测试相关
- `build`: 构建 / 依赖
- `ci`: CI 配置
- `chore`: 其它
示例：
```
feat(kuavo_server): add wall_x adapter
fix(kuavo_data): handle empty depth topic in rosbag converter
docs(readme): clarify Python 3.10 requirement for AGX Orin
```
### 4. 代码风格 Code Style
- **Python**：遵循 PEP 8；使用 `ruff` / `black` 格式化（行宽 100）。
- **YAML 配置**：缩进 2 空格，键名 snake_case。
- **文档**：中文文档与英文文档可并存；面向用户的命令、参数、路径必须可直接复制运行。
- **不要提交：** `.pyc`、`__pycache__/`、`outputs/`、本地训练日志、个人 IDE 配置、大文件 (>10MB)。
### 5. 提交 Pull Request
PR 标题遵循同样的 Conventional Commits 风格。PR 正文请包含：
- **What**: 这个 PR 做了什么？
- **Why**: 为什么需要这个改动？
- **How tested**: 如何验证？（命令、数据集、checkpoint 路径）
- **Breaking changes**: 是否破坏现有接口？
- **Related issues**: `Closes #123` / `Refs #456`
PR 提交后 CI 会运行基础检查。**请在自己本地确认通过后再请求 review**。
## 接入新模型 Adding a New Model
请遵循 [kuavo_server/docs/add_new_model.md](kuavo_server/docs/add_new_model.md) 中的完整 7 步流程：
1. 在 `kuavo_server/adapters/` 下创建 adapter
2. 仅在 adapter 内做 obs / action 转换
3. 在 `kuavo_server/builtin_adapters.py` 注册
4. 更新 `kuavo_server/README.md` 添加启动命令
5. （如果带训练）在 `configs/train/lerobot/` 或 `kuavo_model/external_models/` 下补全配置和文档
6. 提供至少一份 smoke test 命令
7. 在 PR 描述里说明已用何种数据 / checkpoint 跑通
## 文档贡献 Docs Contribution
文档源在 `docs/` 与各模块 `readme.md`。请：
- 中文为主，专有名词保留英文（如 `LeRobot`、`PI0`、`ROS`）。
- 提供可直接复制运行的命令（含完整路径占位符）。
- 任何 `<placeholder>` 必须在文末解释或在命令中标注。
- 不要在公开文档中暴露内部 IP / 内部 SaaS / 个人邮箱。
## 报告 Bug Reporting Bugs
请通过 [GitHub Issues](https://github.com/LejuRobotics/LeTools-Learning/issues/new) 提交，附：
- 环境信息：OS、Python 版本、CUDA 版本、ROS 版本、GPU 型号、commit hash
- 完整复现命令
- 完整 traceback
- 相关配置文件（必要时脱敏）
## 沟通渠道 Communication
- **Bug / 功能请求**：[GitHub Issues](https://github.com/LejuRobotics/LeTools-Learning/issues)
- **安全漏洞**：见 [SECURITY.md](SECURITY.md)
- **乐聚内部成员**：内部沟通流程见公司 Wiki，不在本仓库维护
## 许可证 License
提交贡献即表示你同意你的贡献以 [GNU General Public License v3.0](LICENSE) 发布。
|