288 lines
10 KiB
Markdown
288 lines
10 KiB
Markdown
# RC_Legged 项目规范
|
||
|
||
## 1. 项目概述
|
||
|
||
RC_Legged 是一个四轮足强化学习（RL）机器狗项目，涵盖机械设计、硬件电路、嵌入式软件和控制算法全栈开发。
|
||
|
||
### 仓库地址
|
||
|
||
- **Gitea 远程仓库**: `https://git.zeitvex.com/Robocon/RC_Legged.git`
|
||
- **SSH**: `git@git.zeitvex.com:Robocon/RC_Legged.git`
|
||
|
||
---
|
||
|
||
## 2. 仓库目录结构规范
|
||
|
||
```
|
||
RC_Legged/
|
||
├── 00_reference/ # 参考项目与文档（只读，不改动）
|
||
├── 01_doc/ # 项目文档（设计文档、会议记录、需求文档）
|
||
├── 02_mechanical/ # 机械设计（SolidWorks/STL/URDF/STEP）
|
||
│ ├── CAD/ # 源文件
|
||
│ ├── STL/ # 3D 打印文件
|
||
│ └── URDF/ # URDF 描述文件
|
||
├── 03_hardware/ # 硬件电路设计（KiCad/Altium）
|
||
│ ├── PCB/ # PCB 工程文件
|
||
│ ├── BOM/ # 物料清单
|
||
│ └── datasheet/ # 芯片/模块数据手册
|
||
├── 04_firmware/ # 嵌入式固件（STM32/ESP32 等）
|
||
│ ├── motor_driver/ # 电机驱动固件
|
||
│ └── sensor_board/ # 传感器板固件
|
||
├── 05_software/ # 上层软件
|
||
│ ├── rl_training/ # 强化学习训练代码
|
||
│ │ ├── configs/ # 训练配置
|
||
│ │ ├── envs/ # 环境定义
|
||
│ │ └── logs/ # 训练日志（.gitignore）
|
||
│ ├── ros_ws/ # ROS 工作空间
|
||
│ │ ├── src/
|
||
│ │ └── scripts/
|
||
│ └── utils/ # 通用工具脚本
|
||
├── 06_assets/ # 媒体资源（渲染图、演示视频等）
|
||
├── .gitignore
|
||
├── .pre-commit-config.yaml # Pre-commit 配置
|
||
├── README.md # 项目总览
|
||
└── 项目规范.md # 本文件
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 分支管理策略
|
||
|
||
### 3.1 分支结构
|
||
|
||
```
|
||
main ─────●────────────●────────────────●── 最稳定，仅里程碑合并
|
||
\ / /
|
||
main-nightly ──●────●──●────●─────────●─────────── 每日构建/集成测试
|
||
\ \ / \ /
|
||
task-<name> ─────●──●────────●──●──────────●──── 具体任务分支（实验/算法/feature）
|
||
\ /
|
||
task-<name>-infra ─────────●────────────────●─────── 核心代码修补分支（紧急修复）
|
||
```
|
||
|
||
### 3.2 分支职责
|
||
|
||
| 分支 | 角色 | 说明 |
|
||
|------|------|------|
|
||
| `main` | 项目所有负责人 | 最保守，只合并经过充分验证的里程碑版本。每次合并应为 **no-ff**（保留合并记录）。 |
|
||
| `main-nightly` | 主要维护人员 | 日常集成测试目标。任务分支达标后先合入此分支，稳定后再合入 `main`。 |
|
||
| `task-<name>` | 具体任务开发者 | 自己维护，主要用于 task 配置和实验记录。**只允许修改对应子目录内的文件**。 |
|
||
| `task-<name>-infra` | 任务开发者（极端情况） | 当必须修改 `main-nightly` 核心代码才能跑通当前训练时使用，快速验证后合入 `main-nightly`。 |
|
||
|
||
### 3.3 分支操作规则
|
||
|
||
1. **`main` 分支**：禁止直接推送。只能通过 Pull Request 从 `main-nightly` 合并，且必须经过 Code Review。
|
||
2. **`main-nightly` 分支**：原则上禁止直接推送。任务分支通过 PR 合入，需经过基本验证。
|
||
3. **`task-*` 分支**：从 `main-nightly` 创建，开发者自行推送。
|
||
4. **`task-*-infra` 分支**：从 `main-nightly` 创建，只包含核心代码改动，**不允许包含任何 task 配置文件**，合入后立即删除。
|
||
5. **配置代码与逻辑代码分离**：训练 config 文件和核心逻辑代码必须在不同的分支维护。只允许 config 分支从 logic 分支 merge。在里程碑之前，logic 分支不吸收任何 config 分支改动。
|
||
|
||
---
|
||
|
||
## 4. 提交（Commit）规范
|
||
|
||
### 4.1 Commit Message 格式
|
||
|
||
```
|
||
[tag] 一句话描述（不超过 72 字符）
|
||
|
||
（空一行后可补充详细说明，例如改动动机、注意事项等）
|
||
```
|
||
|
||
### 4.2 标签规则
|
||
|
||
| 标签 | 含义 | 示例 |
|
||
|------|------|------|
|
||
| `[add]` | 新增功能/文件 | `[add] 四足逆运动学求解器` |
|
||
| `[update]` | 修改已有功能 | `[update] 优化步态切换逻辑` |
|
||
| `[fix]` | 修复 Bug | `[fix] 电机 CAN 通讯超时处理` |
|
||
| `[remove]` | 删除功能/文件 | `[remove] 废弃旧版遥控器协议` |
|
||
| `[format]` | 代码格式化/重构 | `[format] 统一命名规范` |
|
||
| `[log]` | 实验记录/日志提交 | `[log] 第3轮训练结果，reward 收敛至0.85` |
|
||
| `[doc]` | 文档相关 | `[doc] 添加CAN总线协议说明` |
|
||
| `[hardware]` | 硬件相关改动 | `[hardware] PCB v1.2 修改电源走线` |
|
||
| `[mechanical]` | 机械相关改动 | `[mechanical] 大腿连杆加厚2mm` |
|
||
|
||
### 4.3 Commit 原则
|
||
|
||
1. **一个 Commit 只做一件事**。如果一次改动了多个不相关的问题，必须拆分为多个 commit。
|
||
2. **Commit Message 必须说清楚改动内容**。只看 message 就能理解改了什么，否则需要修正。
|
||
3. **Task 配置文件和核心代码不得混在同一个 commit 中**。
|
||
4. **未通过 Pre-commit 检查的代码不允许 commit**。
|
||
5. **如果 commit 历史有问题，必须先修复再继续开发**。
|
||
|
||
---
|
||
|
||
## 5. 代码质量规范
|
||
|
||
### 5.1 Pre-commit 自动检查
|
||
|
||
- 使用 [pre-commit](https://pre-commit.com/) 工具实现提交前自动检查。
|
||
- 安装：`pip install pre-commit`
|
||
- 启用：在仓库根目录执行 `pre-commit install`
|
||
- 手动运行：`pre-commit run --all-files`
|
||
- 所有检查项必须全部通过（绿色/蓝色）方可 commit。
|
||
- `.pre-commit-config.yaml` 需包含：代码格式化（Clang-Format / Black）、Python 语法检查（Flake8 / Ruff）、YAML 检查、文件末尾换行符检查等。
|
||
|
||
### 5.2 代码风格
|
||
|
||
- **C/C++**：遵循 Google C++ Style Guide，使用 `.clang-format` 统一格式。
|
||
- **Python**：遵循 PEP 8，使用 Black 格式化。
|
||
- **ROS**：遵循 ROS C++/Python 编码规范。
|
||
- **命名**：
|
||
- 文件名：小写 + 下划线（`imu_driver.cpp`）
|
||
- 类名：大驼峰（`ImuDriver`）
|
||
- 函数/变量：小写 + 下划线（`read_imu_data()`）
|
||
- 宏/常量：全大写 + 下划线（`IMU_TIMEOUT_MS`）
|
||
|
||
### 5.3 接口变更流程
|
||
|
||
1. 首先尝试在现有接口定义下完成需求。
|
||
2. 如必须修改接口，向项目负责人 + 所有使用者提交申请。
|
||
3. 通过后，使用 **Pull Request** 标记变更过程，关联相关 Issue。
|
||
|
||
---
|
||
|
||
## 6. Pull Request 与代码审查（Code Review）
|
||
|
||
### 6.1 PR 流程
|
||
|
||
1. 在 `task-*` 或 `task-*-infra` 分支上完成开发并推送。
|
||
2. 在 Gitea 上创建 Pull Request：
|
||
- **来源分支**：`task-*` → **目标分支**：`main-nightly`
|
||
- **来源分支**：`main-nightly` → **目标分支**：`main`
|
||
3. PR 标题格式：`[tag] 简短描述`（与 commit message 一致）。
|
||
4. PR 描述中说明：改动内容、验证方式、影响范围。
|
||
|
||
### 6.2 审查要求
|
||
|
||
- 必须由至少 1 名项目成员 Review 后方可合并。
|
||
- 审查重点：功能正确性、接口兼容性、代码风格、是否包含无关文件。
|
||
- 如有修改意见，PR 作者修改后重新请求 Review。
|
||
|
||
### 6.3 合并方式
|
||
|
||
- 合入 `main-nightly`：使用 **Squash Merge**（保持 nightly 历史清晰）。
|
||
- 合入 `main`：使用 **Merge Commit (no-ff)**（保留完整分支历史）。
|
||
|
||
---
|
||
|
||
## 7. Gitea 配置
|
||
|
||
### 7.1 仓库设置
|
||
|
||
- **可见性**：私有（Private）
|
||
- **默认分支**：`main`
|
||
- **分支保护**（`main` 分支）：
|
||
- 禁止直接推送
|
||
- 要求 PR 审查通过后才能合并
|
||
- 要求 PR 必须基于最新 `main`
|
||
- 禁用强制推送
|
||
|
||
### 7.2 初始推送
|
||
|
||
```bash
|
||
git init
|
||
git checkout -b main
|
||
git add .
|
||
git commit -m "[init] RC_Legged 项目初始化"
|
||
git remote add origin https://git.zeitvex.com/Robocon/RC_Legged.git
|
||
git push -u origin main
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 硬件测试规范
|
||
|
||
### 8.1 真机测试要求
|
||
|
||
1. **全程录像**：每次真机测试必须有独立相机全程拍摄视频。
|
||
2. **ROS Bag 记录**：完整系统测试时必须用 ROS Bag 记录所有 message 数据。
|
||
- 使用 `ros2 bag record -s mcap -o <bag_name> /topic1 /topic2 ...`
|
||
- 推荐编写 `rosbag.sh` 脚本自动记录所有传感器数据。
|
||
- 所有与项目相关的电脑需安装 [Foxglove Studio](https://foxglove.dev/) 用于查看 bag。
|
||
3. **可视化配置**：所有 ROS 系统必须配置 RViz + `robot_state_publisher` + `joint_state_publisher`。
|
||
|
||
### 8.2 急停方案
|
||
|
||
所有真机测试脚本必须包含：
|
||
- 除 `Ctrl+C` 外的独立急停机制（如遥控器急停按钮）。
|
||
- 急停触发后立即进入 **Damping Mode**，无任何等待延迟。
|
||
- 推荐方案：控制程序监听遥控器急停信号，触发后立即终止程序。
|
||
|
||
---
|
||
|
||
## 9. .gitignore 示例
|
||
|
||
```gitignore
|
||
# 编译产出
|
||
build/
|
||
devel/
|
||
install/
|
||
*.o
|
||
*.elf
|
||
*.hex
|
||
|
||
# Python
|
||
__pycache__/
|
||
*.pyc
|
||
*.pyo
|
||
.venv/
|
||
venv/
|
||
|
||
# IDE
|
||
.vscode/
|
||
.idea/
|
||
*.swp
|
||
*.swo
|
||
|
||
# 训练产出
|
||
05_software/rl_training/logs/
|
||
05_software/rl_training/checkpoints/
|
||
wandb/
|
||
|
||
# ROS
|
||
*.bag
|
||
*.mcap
|
||
|
||
# 系统
|
||
.DS_Store
|
||
Thumbs.db
|
||
|
||
# 机械
|
||
*.sldprt
|
||
*.sldasm
|
||
*.step
|
||
*.stp
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 项目里程碑工作流
|
||
|
||
```
|
||
[日常开发]
|
||
task-xxx 分支开发 → 提交 → 推送 → PR → Code Review → 合入 main-nightly
|
||
|
||
[里程碑发布]
|
||
main-nightly 经过充分测试
|
||
→ 创建 PR: main-nightly → main
|
||
→ 项目负责人 Review
|
||
→ 合入 main
|
||
→ 创建 Git Tag: v1.0.0, v1.1.0, ...
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 参考项目
|
||
|
||
| 项目 | 类型 | 地址 |
|
||
|------|------|------|
|
||
| EDULITE_A3 | 四足机器人 | `00_reference/EDULITE_A3/` |
|
||
| OpenDog | 四足机器人 | `00_reference/open-dog/` |
|
||
| reBot-DevArm | 机械臂 | `00_reference/reBot-DevArm/` |
|
||
|
||
---
|
||
|
||
*本规范参考上述开源项目及行业最佳实践编写，随项目推进持续完善。*
|