Repository navigation
Contribution Process
RVCK 的贡献基于 Github 进行，基本流程如下：
每个阶段描述如下：
请进入 Issue 页面 https://github.com/RVCK-Project/rvck/issues，通过点击 ”New issue” 创建 issue。
Issue 主要分以下几类：
-
Type-A: Baclport 上游主线的 new feature，包括改进。
-
Type-B: Backport 上游主线的 bugfix，注意对于此类 bugfix，必须在 RVCK 上也必须能复现。
-
Type-C: RVCK 自己维护的 vendor 的 BSP/Driver 的新增开发。
-
Type-D: RVCK 自己维护的 vendor 的 BSP/Driver 的 bugfix。
-
Type-E: 使用中发现的 RVCK 特有的需求，明确上游主线无该需求且不会被上游主线接纳，否则应归入 Type A。例子：为 RVCK 新增 rvck_defconfig，因为 RVCK 不使用 defconfig。
-
Type-F: 使用中发现的 RVCK 特有的故障, 明确上游主线不存在且仅在 RVCK 中复现，否则应归入 Type B。
编辑 issue 描述时需要注意以下事项：
-
建议一个 issue 只专注一个主题，不要把一些不相关的主题合并到一个 issue 中进行描述。
-
issue 需要描述的是两类事情：
-
故障：说清楚故障现象，复现步骤
-
新特性需求，描述要达到的目标
至于解决方案，应该是 PR 中去描述的内容，不应该在 issue 里描述。
issue 的例子可以参考 ISSUE #449
-
提出 Issue 后请等待我们的回应，并积极参与讨论。我们会评估 issue，明确合入的预估时间线。如果无异议，再进行后面的步骤。
提交者在 https://github\.com/RVCK\-Project/rvck/pulls 通过点击 “New pull request" 创建 PR。
-
和 issue 的提交类似，一个 PR 中我们建议不要包含多个主题或一个 PR 解决了多个 issue。一个 PR 应该专注于一个主题，一方面是为了 review 的清晰性，另一方面（也是更重要的）是因为 RVCK 的 PR 工作会作为后续发行版（譬如 openEuler）的内核（譬如 rvck-olk）摘录补丁的依据，如果一个 PR 中混杂了多个主题，对于发行版内核继续评审和摘取补丁会带来不便。
-
PR 描述中需要将该 PR 和其相关的 issue 关联起来，这样当我们 merge 该 PR 时，github 会自动关闭关联的 issue。具体关联方法参考 “Linking a pull request to an issue”。Quick Guide: 假设 PR #100 关联了 issue #99，那么我们可以在提交 PR 的描述中加入一行: "fixes #99"。
-
PR 描述中应该提供具体的测试说明。
-
PR 描述中要说清楚解决的问题和故障。特别地，对于解决 Type-A 和 Type-B 这类 backport 的 PR，需要在 PR 描述中解释清楚如下内容：
-
backport 的是补丁来自上游的哪个版本。需要注意的是，我们不建议 backport 和提交 PR 时间相比过于新的还处于开发周期中引入的 Type-B 上游补丁，除非有非常强的理由，因为 RVCK 是基于上游的一个稳定版本在开发（譬如 6.6.x 系列），该稳定版本也会 pick 上游主线的 bugfix 补丁，我们过早引入开发周期的 bugfix 补丁可能会在升级 RVCK 的基线（rvck-6.6）时和上游针对 6.6.x 也 backport 的补丁发生冲突。
-
Backport 的每一笔补丁的简单描述以及可能的相互之间的依赖。
-
-
对于 Type-C issue 的 PR，建议提供一份对硬件的说明。
RVCK 遵循 kernel.org 社区的规范（具体参考 “Submitting patches: the essential guide to getting your code into the kernel”）。添加以下额外要求，主要是在 commit message 上。
在 commit message 上，借鉴了 openEuler 内核的部分特点，在补丁的 subject 和commit message 之间，添加了一些用于补丁追踪的 tag，我们称之为 RVCK patch tag，与 commit message 之间用一条虚线隔开，例如下面这个例子中的第 3 行到第 7 行：
RISC-V: KVM: Save trap CSRs in kvm_riscv_vcpu_enter_exit()
mainline inclusion
from mainline-6.12-rc6
commit 3e7d154ad89b
category: feature
bugzilla: https://github.com/RVCK-Project/rvck/issues/256
--------------------------------
Save trap CSRs in the kvm_riscv_vcpu_enter_exit() function instead of
the kvm_arch_vcpu_ioctl_run() function so that HTVAL and HTINST CSRs
are accessed in more optimized manner while running under some other
hypervisor.
Signed-off-by: Anup Patel <apatel@ventanamicro.com>
Reviewed-by: Atish Patra <atishp@rivosinc.com>
Link: https://lore.kernel.org/r/20241020194734.58686-13-apatel@ventanamicro.com
Signed-off-by: Anup Patel <anup@brainfault.org>
Signed-off-by: Gao Rui <gao.rui@zte.com.cn>
其中每一行的描述针对不同类型的 issue 内容文字稍有不同
-
第 3 行：必须。如果是 Type-A 和 Type-B 的，写 "mainline inclusion", 表示是 backport 的上游主线代码，如果是其他类型的，可以写 "community inclusion" 或者 “dist inclusion” 以示来自非上游主线。
-
第 4 行：可选。对于 Type-A 和 Type-B 才需要，注明该 backport 的补丁是从哪个主线版本开始进入上游主线的
-
第 5 行：可选。对于 Type-A 和 Type-B 才需要，注明该 backport 的补丁在上游主线中的 commit ID（hashcode), 建议至少 12 位
-
第 6 行：必须。如果是新特性开发，填 feature，如果是故障修复，填 bugfix。
-
第 7 行：必须。该补丁对应的 RVCK 的 issue 的 URL。
其他注意事项：
-
对于 Type-A 和 Type-B 的改动，提交者需要在 commit message 的签名区的最下面签名。
-
摘取补丁时应该保证补丁修改尽量和 backport 的补丁保持一致，如果因为基线差异导致需要调整，请在 commit message 的签名区所添加的提交者的签名前插入一行说明（用 [] 括起来），以方便 review 代码的人了解 RVCK 和上游补丁存在着比较重要的差异，具体参考 [内核文档：修改补丁]。例子：
RISC-V: KVM: xxxxxx mainline inclusion from mainline-6.12-rc6 commit 123456789012 category: feature bugzilla: https://github.com/RVCK-Project/rvck/issues/xxx -------------------------------- xxxxxxx Signed-off-by: Anup Patel <apatel@ventanamicro.com> [something is modified due to some reason] Signed-off-by: backport submitter <Jack@xxx.com>
针对 Type-A 和 Type-B，有时候需要提前合入一些已经在 LKML 中出现但还未被接纳进入上游主线的补丁（注：针对此类补丁建议尽量避免，尽量等其进入内核主线再 backport），针对这类在提交时，需要在 PR 和补丁的 commit message 中添加如下额外工作，具体例子参考 PR #396：
-
将最新的邮件列表的 URL 贴在 PR 中，而非以 Refernce 的方式写在 commit message 中。同时写清楚这个 URL 对应的版本号（譬如 v16）
-
针对这种提前合入 RVCK 的补丁要说清楚这个补丁尚未进入主线，并给出理由为何我们要提前合入。
-
针对该 PR，除了关联的 issue 外，我们需要另外提一个用于跟踪该补丁上游合入进展的 issue。该 issue 用于跟踪该补丁在上游社区的进展以及其在 RVCK 中的更新迭代状态，我们可以在该补丁进入上游主线并且 RVCK backport 的内容与其对齐后关闭该 issue。在 PR 中注明该 issue，但不要将该 issue 和 PR 关联（关联的 issue 会在 PR 被 merge 时自动关闭）。
-
更重要的，我希望对于这种提前合入 RVCK 的补丁，我们在补丁的标题中加上一个形如 "[STAGED v16]" 的前缀。如下面这样：
[STAGED v16] drivers/perf: riscv-iommu: add risc-v iommu pmu driver community inclusion category: feature bugzilla: https://github.com/RVCK-Project/rvck/issues/395 ------------------------------------------------- ..... 省略。摘录自邮件列表的文字，最后一行加上提交者的签名加前缀的好处是：一方面可以更明确地知道这是一个提前 pick 了一个尚未进入主线的补丁，以便和通常意义上的 backport 主线补丁进行区分。另一方面也有助于以后长期的维护。考虑未来可能发现上游有新的版本（譬如 v17 ，也可能是一个最终进入主线的版本）发出来。我们希望摘录，一种办法是在现有代码基础上采用 delta 方式打补丁，另一种办法是将 原先合入的补丁（假设是 LKML 中的 v16）revert 掉再应用 v17。我们比较倾向于后一种方案。如果应用第二种方案，前缀的作用就可以区分新应用的 v17。举例说明如下：假设不加前缀，那么我们用
git log --oneline rvck-6.6时会看到：$ git log --oneline rvck-6.6 drivers/perf: riscv-iommu: add risc-v iommu pmu driver Revert: drivers/perf: riscv-iommu: add risc-v iommu pmu driver ...... drivers/perf: riscv-iommu: add risc-v iommu pmu driver ......不好的地方在于我们会看到两个相同名字的补丁，如果多次 revert 再 apply 新版本，我们会看到更多同名的 patch，这会对我们搜索匹配造成困难。
如果加上前缀，则会看到：
$ git log --oneline rvck-6.6 [STAGED v17] drivers/perf: riscv-iommu: add risc-v iommu pmu driver Revert: [STAGED v16] drivers/perf: riscv-iommu: add risc-v iommu pmu driver ...... [STAGED v16] drivers/perf: riscv-iommu: add risc-v iommu pmu driver ......这样就能区分开了。进一步，如果 v17 已经是进入主线的版本，我觉得对于最后一笔就不用加前缀了，因为这已经是一个正式的 backport 主线的补丁。如下所示：
$ git log --oneline rvck-6.6 drivers/perf: riscv-iommu: add risc-v iommu pmu driver Revert: [STAGED v16] drivers/perf: riscv-iommu: add risc-v iommu pmu driver ...... [STAGED v16] drivers/perf: riscv-iommu: add risc-v iommu pmu driver ......
RVCK github 主仓 https://github\.com/RVCK\-Project/rvck 支持 PR 提交后自动运行 CI（Continuous Integration）check。
如果检查成功则进入下一个流程，否则修改提交直至 CI check 成功。例外情况是有时候因为基础设施问题 CI check 可能会出错无法正常运行 (见上 “贡献流程图” 中的 “CI internal error”)，这个经提交者和 RVCK 管理员排查确认非代码本身错误情况下可以在 PR 上注明并继续 review 进程。
PR 提交后如果需要 review （包括 review 后被打回，rework 后需要重新 review 的），请在 PR 中 comment “请 review” 主动发起 review 邀请。这么做主要是希望提交者自己确保 review 条件已经就绪，代码不会继续更改。
管理员收到 review 请求后会帮助邀请并添加 reviewer。添加 reviewer 后 PR 页面右上角的 Reviewers 区域示例如下，黄色小圆圈表示正在 review 过程中，Review 期间提交者切记不可再更新提交代码（如必须修改请先联系管理员或者 reviewer 并征得其同意后方可进行）：
审核通过后 PR 会显示已经 approve，参考下图，绿色小勾表明审核通过。
审核通过后请提交者务必不要再更改和提交代码，如果的确有问题请及时联系管理员或者 reviewers。
如果审核不同过，PR 会被打回，此时 reviewers 的状态如下：
提交者根据 reviewers 的意见进行修改，建议对评审意见进行逐条回复，确保两边对问题达成一致。
重新 rework 和提交时注意将开发分支 rebase 到最新的 rvck-6.6，因为 rework 期间该分支随时会因为合入新的 PR 而升级。
Rework 和重新提交后，在 PR 中 comment “请 review” 主动发起 review 邀请。这么做是希望提交者自己确保 review 条件已经就绪，代码不会继续更改。
管理员会定期将审核通过的 PR 合并会 rvck-6.6 分支。如果补丁被合并，管理员需要在最底部回复以下关键字：
已经合并到 rvck-6.6 分支
关联的 Issue 会自动关闭。