# 贡献指南 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) 发布。