Robocon/RC_Legged
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
RC_Legged/项目规范.md
T

10 KiB
Raw Permalink Blame History

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 工具实现提交前自动检查。
  • 安装：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 初始推送

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 用于查看 bag。
  3. 可视化配置：所有 ROS 系统必须配置 RViz + robot_state_publisher + joint_state_publisher。

8.2 急停方案

所有真机测试脚本必须包含：

  • 除 Ctrl+C 外的独立急停机制（如遥控器急停按钮）。
  • 急停触发后立即进入 Damping Mode，无任何等待延迟。
  • 推荐方案：控制程序监听遥控器急停信号，触发后立即终止程序。

9. .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/

本规范参考上述开源项目及行业最佳实践编写，随项目推进持续完善。

Reference in New Issue View Git Blame Copy Permalink