跳转至

源码贡献指南

通过 Github 贡献代码

如果你想要参与某个项目，但是并没有推送权限，这时可以对这个项目进行 Fork。Fork 时，GitHub 会在你的空间中创建一个完全属于你的项目副本，且你对其具有推送权限。将修改推送到 Fork 出的项目副本后，可以通过创建拉取请求（Pull Request，简称 PR）来让改动进入源版本库。创建了拉取请求后，就会开启一个可供审查代码的板块，项目的拥有者和贡献者可以在此讨论相关修改，直到项目拥有者对其感到满意，并且认为这些修改可以被合并到版本库。

对于组件仓库、各兵种机器人的开发仓库，请通过 GitHub 的 Fork 和 Pull Request 流程来提交代码。贡献流程简要介绍如下：

  • 将仓库 Fork 到自己的工作空间中
  • 将工作空间中的仓库克隆（clone）到本地
  • 从 master/main 分支创建自己的开发分支
  • 在自己的开发分支进行开发，为项目添加新的特性或改进项目，开发过程请遵循开发规范
  • 提交（commit）一些修改
  • 将这个分支推送（push）到 GitHub 上
  • 创建一个拉取请求（PR）
  • 项目拥有者审核代码，交流讨论，根据实际情况继续修改
  • 项目的拥有者将贡献合并（merge）到主分支或关闭（close）拉取请求

建议及时将最新的 master/main 分支同步到你的 Fork 中。

Commit 格式

使用以下格式提交 commit，不限制中英文：

Text Only
1
2
3
4
<type>(<scope>): <subject>
 - 必要栏位：type 代表 commit 的类别
 - 可选栏位：scope 代表 commit 影响的范围，如 Middlewares, Devices...
 - 必要栏位：subject 代表此 commit 的简短描述，50 字以内，结尾不要加句号

type 只允许使用以下类别：

<type> 说明
feat 新增/修改功能 (feature)
fix 修补bug (bug fix)
docs 文件 (documentation)
style 格式 (不影响程式码运行的变动white-space, formatting, missing semi colons, etc)
refactor 重构 (既不是新增功能，也不是修补bug 的程式码变动)
perf 改善效能 (A code change that improves performance)
test 增加测试 (when adding missing tests)
chore 建构程序或辅助工具的变动 (maintain)
revert 撤销回退先前的 commit

PR 要求

  • 请使用清晰的文字或图文，详细描述 PR 目标、涵盖的全部内容、反馈需求等
  • 请确保 PR 的内容足够精简且单一，且通过实际的测试

贡献系统组件（该部分将转移至仓库 README）

添加任何系统组件时，请在说明文档中注明文件依赖关系，并通过完善的测试后，在 HW-Components 仓库 提交 Pull Request.

添加板级驱动

板级设备驱动对应一种设备总线驱动，请基于 HAL 库开发。

依赖 仅允许包含系统相关的头文件 system.h

添加流程

  • 将一对新板级驱动文件 .c/.h 加入 bsp 目录
  • 在 board.h 中包含对应的头文件

添加中间件

中间件可以依赖于操作系统，但应独立于其他组件工作，具有可移植性。

依赖 允许中间件组件包含操作系统内核，允许包含 utils 实用工具组件；请包含系统配置文件 system.h

添加流程

  • 必要时，在 middlewares 目录下创建新中间件组件目录
  • 将新中间件文件.c/.h 加入 middlewares 目录或新创建的目录
  • 在系统配置文件 config.h 中添加对应的组件开关

添加实用工具

实用工具应完全独立工作，具有全平台通用性。请确保实用工具能实现预期功能后，再将其加入组件库。

依赖 不允许任何依赖

贡献算法（该部分将转移至仓库 README）

算法包含数学运算、控制器、滤波器、各类解算算法等，是机器人通用组件的一部分。添加新算法时，请在说明文档中注明文件依赖关系，并通过完善的测试后，在 HW-Components 仓库 提交 Pull Request.

算法应独立于操作系统和其他组件工作，具有可移植性。请单独仿真测试，确保算法运行符合预期后，再将其加入组件库。

依赖 允许算法组件包含 algorithms 目录下其他算法（请尽可能减少耦合），允许包含 utils 实用工具组件；允许包含系统相关的头文件 system.h

添加流程

  • 将一对新算法文件.c/.h加入./algorithms

贡献应用（该部分将转移至仓库 README）

在机器人嵌入式工程中添加的新应用可分为三种类型：设备应用、机器人模块和任务。设备应用对应于机器人实体上的设备，具有特定的属性或方法；模块对应于机器人实体上的功能模块或子系统，是设备应用的聚合或组合；任务则包含了模块的实例化，阐述特定任务的执行顺序和执行逻辑。

由于设备应用仍属于机器人通用组件的一部分，因此对于设备应用，请在说明文档中注明文件依赖关系，并通过完善的测试后，在 HW-Components 仓库 提交 Pull Request.

添加设备应用

设备应用独立于操作系统和上层实际应用数据，具有可移植性。推荐基于设备管理中间件（middleware）开发，使用其提供的统一驱动接口；或留出可供驱动注册的接口，使具体设备与驱动解耦。

在中间件支持不能满足功能实现的情况下，允许直接调用板级外设驱动；若没有驱动可用，请谨慎为队内编写的外设驱动增添新内容。

依赖 允许设备组件包含中间件层的“设备管理器”，允许包含 bsp 目录下的外设驱动，允许包含 utils 实用工具组件；请包含系统相关的头文件 system.h

添加流程

  • 将一对新设备文件.c/.h加入application/devices 目录
  • 在 device.h 中包含对应的 .h 文件，并进行对应设备的外设句柄设置

添加模块

新模块请基于现有组件开发；若没有合适的组件接口可供使用，请按照组件添加规则进行组件的贡献。

添加流程

  • 将文件加入工程的 application/modules 目录

添加任务

机器人开发中，任务的内容定义为 模块实例化 + 执行顺序和逻辑，应基于模块开发。在嵌入式系统的具体实现中，新任务应遵循现有框架，基于中间件等扩展组件，来实现任务初始化、调度、通信等所需功能。

添加流程

  • 将文件加入工程的 application/tasks 目录

附录

版本说明

版本号 发布日期 说明
2022.12.17 首次发布