贡献
感谢您有兴趣为 FreeRTOS 项目做出贡献。无论是漏洞报告、新功能、校正还是其他文件,
我们非常重视社区的反馈和贡献。请先阅读拉取请求流程,然后再
提交任何问题或拉取请求,以确保我们掌握所有必要信息来有效应对您的漏洞
报告或贡献。
拉取请求流程
本部分介绍将拉取请求 (PR) 提交到 GitHub 的
FreeRTOS 组织中的 GitHub 存储库时所经历的阶段。打开 PR 之前,请阅读并熟悉
CONTRIBUTING.md。
术语
- FreeRTOS 合作伙伴贡献者:
- 这些是来自社区的精英开发者和专家。
- FreeRTOS 团队:
- FreeRTOS 团队由“AWS 员工”组成。
- 代码所有者:
- 对于所有 FreeRTOS 存储库而言, “FreeRTOS 团队”和/或“FreeRTOS 合作伙伴贡献者”属于代码所有者。
- 贡献者:
- 提交拉取请求的人员。
- 受理人:
- 负责确定审核者和管理 PR 的 AWS 员工。他们会跟踪 PR 进度,
并确保及时审核和合并 PR。
- 审核者:
- 负责审核 PR 并向贡献者提供反馈的人员。如需合并 PR,
需要两次审批,其中一次必须来自存储库的代码所有者。
拉取请求生命周期
提交后的 PR 将经历以下阶段:
- 打开
- PR 已创建。
- 所有 GitHub 操作都已通过, 且 PR 准备接受审核。
- 会审
- PR 被分配给受理人。
- 受理人将 FreeRTOS 团队的一位审核者指派给 PR。
- 初次审核
- 审核者提供反馈并在需要时与贡献者讨论未决问题。
- 如果贡献者和审核者在讨论后认为不合并 PR,则
PR 会被关闭。
- PR 贡献者处理反馈并在需要时更改 PR。
- 审核者批准 PR 并指派第二位审核者。
- 二次审核
- 第二位审核者审核 PR,并在需要时提供反馈。
- PR 贡献者处理反馈并在需要时更改 PR。
- 第二审核者批准 PR。
- 测试
- 一位审核者测试 PR,确保其正常运行。
- 准备合并
在满足所有分支保护规则后, PR 的状态将变为“准备合并”。我们的分支保护规则要求以下内容:
- 至少两次审核。
- 一次审核来自特定存储库的代码所有者。
- 必须通过所有 PR 检查。
- 合并
- PR 已合并。
PR 的状态通过审核者和受理人添加的 GitHub 标签来指示。以下是最常见的状态
指示词:已会审、审核者已指派、概念确认/否定、首次代码审核进行中、首次代码审核完成、二次代码
审核进行中、二次代码审核完成、测试进行中和测试完成。
请注意,根据 PR 的类型,我们可能决定跳过一些阶段。例如,要求简单文档更新的 PR
可能不会经历上述所有阶段,但每个 PR 都需要获得两位审核者的批准。
我们的 PR 流程图示如下。
拉取请求流程图。 点击放大。
周转时间
审核 PR 所需时长无法预测。由于审核时长取决于变更复杂程度、
审核者是否有空以及团队的整体工作量,因此具体时长因 PR 而异。我们通常会根据以下时间框架
尝试处理每个 PR(周末和公共假日除外) :
- 会审:< 24 个小时
- 概念确认/否定:1-2 周
- 代码审核:1-2 周
- 测试:1-2周
处理审核者要求的更改
作者应在 4 周或更短时间内处理审核注释。如果作者无法在上述时间内处理注释,
我们将采取以下其中一项措施:
- 自行完成必要的更改并合并拉取请求。
- 关闭拉取请求。
加快审核的最佳做法
遵循以下最佳做法有助于让您的 PR 快速得到审核。
- 如果您计划向 FreeRTOS 提供新功能,请事先确认 FreeRTOS 团队和
社区想要并将接受此功能。您计划提出大规模更改或重大更改时尤为
如此。如需获得 FreeRTOS 团队和社区的确认和反馈,请在 FreeRTOS 论坛中创建帖子。
- PR 越小越好。有针对性的小 PR 将得到更快、更全面的审核,更方便回退,
被拒时浪费的精力更少。避免打开涉及多个概念的 PR。
- 请勿在同一个 PR 中混合重构、漏洞修复和功能开发等操作。假设您正在开发功能 X,
并且遇到命名糟糕的变量或不完整/不正确的注释。您应该考虑修复这些问题,但
需要打开另一个 PR,不要与功能 X 使用相同的 PR。
- 注释很重要。您开发的代码将需要长期维护。恰当的注释可为审核者、维护者和用户
提供背景信息,防止他们误解代码的目的。但是,
请勿添加注释来说明只需浏览代码就能显而易见的事情。(以下例子可以好好参考:
https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/。)
- 测试您的 PR。请在您的 PR 中为更改附上合适的单元测试和其他任何有用的测试,
并说明如何执行手动测试。单元测试的说明参见
编码标准、测试和风格指南页面
(位于此网站和 GitHub)。
允许反驳:有时审核者会犯错。如果审核者要求您更改 PR,而您
非常坚持自己的做法,您可以自由地与审核者讨论所请求变更的优点,同时
仍然遵循行为准则。您的意见可能被否决,但您也可能成功说服对方。
务实:稍微思考一下如何让您的 PR 更便于审核和合并。没有文档可以
取代常识和良好品味。此处分享的最佳做法和贡献准则(若得到遵循)将有助于
您的代码更轻松地得到审查和合并。
常见问题
为什么我的 PR 关闭了?
超过 4 周的拉取请求将被关闭。如果拉取请求包含活跃的审核注释,或者正在等待其他相关拉取请求的审核结果,
则可以例外处理。关闭后的拉取请求可以轻松重新创建,并且
关闭后重新打开拉取请求不会有多少损失。我们希望限制拉取请求的总数,
从而:
- 保持项目条理有序。
- 删除旧的拉取请求,因为其中的基础代码已随着时间的推移而更改,因此很难重新找到最初的基础。
- 鼓励代码速度。
为什么我的 PR 没有得到审核/合并?
- 这可能是因为新版本即将发布导致功能冻结。在此期间只会考虑
修复漏洞。如果您的拉取请求涉及新功能,则在发布之前不会优先处理。等待
发布。
- 也可能是因为没有遵循最佳做法。(参阅最佳做法。)一个常见的
情况是拉取请求太大,无法审核。假设您已涵盖 21 个文件,涉及 9347 条插入。当
潜在审核者拉取差异时就会放弃 - 这个拉取请求将需要几个小时来审核,
而他们现在没有这么多时间。等他们稍后有更多空闲时间(呵呵!)的时候就会处理。
- 如果您认为上述两种情况都不是您的原因,而且您的拉取请求没有得到关注,请在
PR 注释中提醒几次。如果所有方法都没有效果,请在 FreeRTOS 论坛上创建帖子,并附上
PR 的链接。
请注意: FreeRTOS 团队有权为了
FreeRTOS 社区的利益随时更新或更改这些指南和流程。因此,始终建议您查阅此页面,以便掌握最新指南
和流程。
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.