开发环境与工具

代码审查

GitHub 旨在提供一个框架，确保每次提交在被纳入代码库之前都经过审查。变更以拉取请求（PR）的形式上传到 GitHub，但只有在经过审查、通过一系列检查（CI）并获得维护者批准后，才会真正成为项目的一部分。GitHub 用于支持标准的开源实践：提交补丁，由项目成员审查后再应用到代码库。

应为拉取请求添加适当的 标签，并关联所有相关的 缺陷或功能跟踪议题 。

Zephyr 项目使用 GitHub 进行代码审查和 Git 代码树管理。开发者向任何 Zephyr 组件提交变更或增强功能时，都应使用 GitHub。GitHub Actions 会根据 Zephyr 项目仓库代码树中的 MAINTAINERS.yml 文件，按组件自动指派相应的审查者。审查完成后，只有少数发布管理者有权将拉取请求合并到主分支。

在合并代码前为审查者留出审查时间

Zephyr 是一个全球性项目，不局限于某个地区或时区。我们的开发者和贡献者遍布全球。通过拉取请求提出变更时，需要留出最短审查时间，让开发者和贡献者有机会审查变更并提出意见。变更分为不同类别，其中一些确实需要由相关领域专家和被修改子系统的负责人审查。许多变更属于“简单变更”类别，通过一般审查即可处理，无需排队等待维护者或代码负责人审查。此外，一些变更可能需要进一步讨论，并由技术指导委员会（TSC）或安全工作组作出决定。下图汇总了上述类别，并给出了各类别建议的最短审查时间：

Pull request classes

拉取请求类别

工作流

  • 变更作者可以在拉取请求中建议该变更应归属的类别。负责关注新提交变更的项目维护者或 TSC 成员可以修改拉取请求的标签，同时添加评论，说明将变更归入其他类别的理由。

  • 项目将使用标签系统对拉取请求进行分类。

  • 最短审查时间结束前，不应合并变更。

类别/标签

紧急修复

修复妨碍开发者开展日常工作的问题的任何变更，例如 CI 故障、测试故障，以及影响用户体验的小幅文档修正。

此类修复通过 CI 检查后，可随时合并。根据修复内容、问题严重程度以及是否有作者以外的人员可以进行审查，项目负责人可以在说明理由后，未经审查直接合并。

简单变更

简单变更是指足够直观、无需维护者或代码负责人参与的变更。此类变更不应改变子系统或组件的逻辑或设计。例如，简单变更可以是：

  • 文档变更

  • 配置变更

  • 构建系统的微调

  • 在不改变逻辑的前提下对代码逻辑进行小幅优化

  • 测试变更与修复

  • 为支持更多配置或开发板等而对示例进行的修改。

维护者

任何涉及子系统或组件逻辑或原始设计的变更，都需要由代码负责人或指定的子系统维护者审查。如果代码变更由负责人以外的贡献者或开发者发起，则需要将拉取请求指派给代码负责人。代码负责人必须向作者提供反馈，并请求其他开发者进行更多审查，推动拉取请求达到可合并状态。

安全

可能影响系统整体安全性的变更，需要由安全工作组的安全专家审查。

TSC 和工作组

引入新特性或功能，或改变整个系统工作方式的变更，需要由 TSC 或负责的工作组审查。例如，对于 破坏兼容性的 API 变更，需要在架构会议上介绍提案，以便相关利益方了解该变更。

拉取请求应有指定负责人

  • 拉取请求的指定负责人不应是该拉取请求的作者。

  • 拉取请求的负责人负责推动该拉取请求达到可合并状态

  • 负责人负责撤销过时的审查，并寻求其他开发者和贡献者的审查

  • 未经负责人批准，不应合并拉取请求。

作者不应合并未经审查的拉取请求

所有拉取请求都需要经过审查，作者不应在未经审查的情况下合并。以下情况例外：

  • 紧急修复：修复 CI 问题、回退更改以及修复系统故障

  • 发布相关更改：更改版本文件、添加标签以及其他不涉及代码更改的发布相关活动。

开发者和贡献者应始终寻求审查，但有时审查者无法参与，而代码更改又需要尽快纳入代码树。

审查者不得在未提供意见或理由的情况下“请求更改”

对拉取请求提出的任何更改请求（-1）都必须说明理由。审查者应避免无理由地阻止拉取请求合并。如果审查者认为某项更改必须经过自己的审查才能合并，则应请求更改其类别，例如：

  • 琐碎更改 -> 维护者

  • 将拉取请求分配给自己，这意味着未经你批准，不应合并该拉取请求。

拉取请求在合并前应至少获得 2 个批准

拉取请求只有获得两次肯定的审查结果（批准）后才能合并。合并操作本身不算批准，拉取请求还需要获得两次批准才能合并。执行合并的人可以不批准而直接合并，也可以先批准再合并，以满足所需的 2 个批准。

审查者应持续跟踪自己提出过反馈的拉取请求

如果审查者在拉取请求中请求了更改，就应关注该拉取请求的状态，或回应提及自己的请求，以确认其反馈是否已得到处理。否则，负责人或仓库所有者应撤销否定的审查结果。撤销审查结果的标准如下：

  • 作者已明确处理了反馈或疑虑

  • 两周后，尽管作者多次提醒，审查者仍未重新查看该拉取请求

  • 审查与代码更改无关，或在没有正当理由的情况下要求进行结构性更改，例如：

    • 拆分 PR

    • 能否修复恰好出现在差异中的这段无关代码

    • 能否修复无关问题

    • 等等。

关闭长期无进展的议题和拉取请求

  • GitHub 上的拉取请求和议题区域并非讨论论坛。其中的条目都是我们需要落实并推动解决的事项。请使用邮件列表进行讨论。

  • 无论是议题还是拉取请求，原始提交者都需要回答问题，并对相关问题或更改作出澄清。如果请求发出一周后仍未收到回复，将再次尝试联系贡献者以获取回复。如果再过一周仍无回复，该条目可能会被关闭（草稿拉取请求和带有 DNM 标签的拉取请求除外）。

持续集成

提交到 GitHub 的所有更改都必须在仿真平台和架构上接受测试，以发现能够立即检测到的故障和回归问题。使用 Twister 进行测试时，还会对所有开发板和平台执行构建测试。文档更改也会经过审查和构建测试，以确保文档能够成功生成。

CI 测试运行期间发现的任何失败都会导致 CI 系统自动给出否定的审查结果。开发者应修复问题、修改补丁并重新提交。

CI 基础设施目前运行以下测试：

  • 运行 checkpatch 检查代码风格问题（发现错误时可投 -1 票；参见注释）

  • Gitlint：根据项目要求检查 Git 提交风格

  • 许可证检查：检查是否存在许可证冲突

  • 运行 twister 脚本

    • 在 QEMU 中运行内核测试（发现错误时可投 -1 票）

    • 为不同开发板构建各种示例（发现错误时可投 -1 票）

  • 验证文档能否正确构建。

备注

checkpatch 是一个 Perl 脚本，它使用正则表达式提取信息，而这些信息需要 C 语言解析器才能准确处理。因此，它有时会产生误报。已知情况包括以下这类结构：

static uint8_t __aligned(PAGE_SIZE) page_pool[PAGE_SIZE * POOL_PAGES];
IOPCTL_Type *base = config->base;

这两行都会产生关于 * 运算符两侧空格的诊断信息：第一行被误认为是指针类型声明，因而被认为应写为 PAGE_SIZE *POOL_PAGES ；第二行被误认为是乘法表达式，因而被认为应写为 IOPCTL_Type * base 。

当 CI 基础设施给出错误结果时，维护者可以覆盖 -1 票的结果。

为 GitHub 中的议题和拉取请求添加标签

本项目使用 GitHub 议题和拉取请求（PR）来跟踪和管理 Zephyr 项目的日常工作、长期工作以及贡献。我们使用 GitHub 标签 按领域、类型、优先级等对这些议题和 PR 进行分类和组织，以便查找相关条目并生成报告。

所有 GitHub 议题或拉取请求都必须带有适当的标签。议题和 PR 通常会分配多个标签，以便按不同的可用类别进行分类。审查 PR 时，如果标签缺失或不正确，维护者应予以修正。

这可以节省大家搜索的时间，减少 PR 或议题被遗忘的可能性，加快审查速度，避免重复报告问题等。

以下是我们目前使用的标签，按适用范围分组：

仅适用于议题的标签

标签

描述

priority: {high|medium|low}

用于对缺陷的影响程度和重要性进行分类。

注意：议题的优先级通常在缺陷分诊会议或 TSC 会议上设置或更改。

Regression

原本正常工作、如今却无法正常工作的功能（缺陷的子类型）。

Duplicate

此议题与另一个议题重复（请指明具体议题）。

Good first issue

适合首次贡献者处理。

Release Notes

需要在发行说明中作为已知问题提及并提供补充信息的议题。

仅适用于拉取请求的标签

该议题或 PR 描述了对稳定 API 的更改。

标签

描述

Hotfix

修复阻碍开发的问题。

Trivial

简单的改动，可以缩短审查时间，且任何人都可以审查，例如拼写错误修正、直截了当的单行错误修复等。

Maintainer

需要维护者审查。

Security Review

需要安全专家审查。

DNM

此 PR 不应合并（Do Not Merge）。对于尚未完成的工作，建议使用 GitHub 的“草稿”PR。

Needs review

此 PR 需要维护者关注。

Backport

此 PR 是向旧版本回移的改动，或应回移到旧版本。

Licensing

此 PR 存在许可证相关问题，需要许可证专家审查。

备注

对于所有适用于 PR 的标签：请注意，标签和 PR 的复杂度共同影响合并前应等待的时间，以确保充分审查。详情请参阅 审查流程 。

同时适用于拉取请求和议题的标签

标签

描述

area: {area-name}

表示受该错误或拉取请求影响的 Zephyr 子系统（例如 area: Kernel 、 area: I2C 、 area: Memory Management ）、项目职能（例如 area: Debugging 、 area: Documentation 、 area: Process ）或其他类别（例如 area: Coding Style 、 area: MISRA-C ）。

领域维护者应能通过领域标签进行筛选，找到与该领域相关的所有议题和 PR。

platform: {platform-name}

仅影响某个特定平台的议题或 PR。

TSC

TSC 是技术指导委员会（Technical Steering Committee）的缩写。如果时间允许，该议题将在下一次 TSC meeting 上讨论。

Breaking API Change

该议题或 PR 描述了对稳定 API 的破坏性变更。更多信息请参阅 引入破坏兼容性的 API 变更 。

bug

该议题报告了一个错误，或该 PR 修复了一个错误。

Coverity

Coverity 检测到的问题或其修复。

Waiting for response

Zephyr 开发者正在等待提交者回答问题或处理某个问题。

Blocked

受另一个 PR 或议题阻塞。

Stale

似乎已被搁置、需要作者关注的议题或 PR。

In progress

对于 PR：工作仍在进行中，暂不应合并。对于议题：正在处理中。

RFC

作者希望征求社区意见。如果是 PR，应将其视为草稿。

LTS

与长期支持版本分支相关。

EXT

与外部组件相关。