贡献指南¶
欢迎参与 A20OS 开源项目的开发与贡献!无论是修复缺陷、完善文档、适配驱动还是扩展架构支持,我们都非常欢迎你的 Pull Request。
系统技术规范与发布规划详见 1.0 计划,质量与功能验收要求详见 验收规范。
本仓库的代码贡献与补丁流程遵循标准的 Git 协作模式。
1. fork 与分支¶
不要直接在 main 分支上提交。
2. 本地构建¶
先按 首次运行指南 准备单架构依赖,确认能编译并运行。已有普通 clone 先执行 git submodule update --init --recursive。
python3 tools/check_quickstart.py
tools/a20 run qemu-riscv64 -- -j4
# 自动验证 shell、外部命令与正常关机:
make -j4 smoke-quickstart
3. 通过测试门禁¶
纯文档修改建议直接运行 make check-docs(或逐项执行 python3 tools/docs/format_markdown.py --check、python3 tools/docs/check_doc_citations.py 与 python3 tools/docs/check_doc_nav.py)检查排版换行、代码行号引用、导航全量覆盖与死链/锚点;无需为措辞修改重跑完整 OS。代码修改按影响范围运行以下门禁及子系统用例,发布候选执行完整适用矩阵,详细说明见 docs/testing-gates.md:
# 构建矩阵
make check-build-matrix
# 基础 bring-up smoke;必须正常关机,timeout 失败,不验证 syscall
make smoke-riscv64
# 广泛聚合门禁;包含构建和 QEMU runtime,可能耗时较长
make check-doc-test-gates
需要验证 Linux 系统调用时运行 make smoke-abi-linux;smoke-riscv64 只是 BRINGUP=1 启动检查。check-doc-test-gates 也不是快速的纯文档检查,请为其传递依赖中的构建和 QEMU smoke 预留时间。
如果修改了具体子系统,再运行对应门禁:
make check-mm-lock-model # 内存管理
make check-vfs-abstraction # 文件系统
make check-abi-boundary # ABI 边界
make check-native-abi-coverage # 新增 A20_NATIVE_SYSCALL 时(登记表/编号表/文档要对齐)
make check-abi-config-guard # 改动 CONFIG_ABI_* 守卫写法时
make check-driver-core-model # 驱动
make check-io-progress-model # I/O 进展
make check-concurrency-foundation # 并发
3.1 文档里的行号引用¶
如果你在 docs/ 或任何 .md 里写了形如「file.c 第 123 行」的行号引用,那么改动那个文件之后引用就可能不再指向所说的东西。运行 tools/docs/check_doc_citations.py 对每条能解析到本仓库的引用检查行号是否还在文件范围内:
python3 tools/docs/format_markdown.py --check # 格式与排版换行检查
python3 tools/docs/check_doc_citations.py --verbose # 引用检查,并列出被跳过的条目
它**故意**只做能精确判定的那一半:范围是否有效。它不判断"第 123 行是否还在说那句话"——那需要读者而不是正则;假装能判定,只会得到一个天天喊狼来了、最后被人加 --no-verify 关掉的门禁。三类条目会被跳过并计数,不会让门禁失败:指向仓库外的上游源码(mesa、virgl、wlroots 等)、形如 [foo.c:122] 某条日志 的**引用的程序输出**(那是证据不是引用),以及 basename 在树内不唯一的引用(裸写的trap.c 无法区分 kernel/core/trap.c 和八个 arch 的 trap.c,猜错会让门禁误报)。
tools/docs/check_doc_citations.py 顶部的 KNOWN_MOVING 列出暂时无法校验的文档,每条都写明原因(当前是 feat/mm-complete 正在重写 kernel/mm/,其中所有行号都会再动一次)。该分支合并后请从列表中删除对应条目——那一刻这些行号才稳定下来。
4. 代码与注释规范¶
4.1 语言¶
- 文档以
docs/zh/的中文内容为源版本,英文译文放在docs/en/的相同相对路径,根目录简介保留README.md与README.en.md。日常修改中文源文档,由增量翻译工作流生成英文更新 PR;不要把未审核的译文标记为已同步。翻译配置、审核与本地命令见 文档国际化。 - 代码注释一律英文。代码注释的既有事实也是英文(内核源码里约 98% 的注释为英文),新增注释跟随既有语言,不要引入新的混合。
- 提交信息标题用英文祈使句(见第 5 节),这与代码注释的语言选择一致。
4.2 格式¶
.clang-format 记录了本仓库的 C 风格:4 空格缩进(不使用 tab)、K&R 花括号、指针写作 type *name、80 列上限。它作为编辑器与格式化工具的配置存在,不再有仓库级格式门禁;提交前请在自己的编辑器中按该配置格式化改动过的文件。
.editorconfig 补充了编辑器层面的换行与缩进约定,并对 *.s/*.S 和 vendored 目录关闭自动改写(汇编的列对齐与预处理指令不能被重新排版)。
4.3 什么值得写注释¶
内核代码的注释密度本身不是目标。判断标准是:注释是否提供了从代码本身读不出来的信息。值得写的:
- 为什么这样设计,而不是这样:权衡、被否决的方案、硬件或 ABI 约束。
- 不变量与前置条件:锁序、锁的前置/后置条件、内存序要求、调用方必须持有或不得持有的东西。
- 代码形状藏起来的值:魔数的推导、容量/尺寸常量、寄存器位域的含义、线格式字节偏移。
- 踩过的坑:真实 bug 的根因、寄存器读回值异常时的排查线索。
- 契约块:跨文件、跨子系统的不变量用
NAME_CONTRACT:命名块集中写清(COW_FAULT_TLB_CONTRACT、LWIP_NO_THREAD_PROGRESS_CONTRACT、SCHEDULER_CONCURRENCY_PREREQS等)。门禁会 grep 这些 token,不要随手改名或删除。
不值得写的(应当删除):
- 复述标识符或紧邻代码行:
// 分配一个物理帧写在frame_alloc()上方。 - 逐行叙述代码在做什么。
- 指向已经搬走的函数的节标题注释(函数拆分后遗留的孤儿注释是最常见的缺陷类型)。
- 纯装饰:
====分隔线、ASCII art、每文件重复的许可横幅。
4.4 文件头¶
每个自研 .c / .h 文件以简短文件头开始,说明这个文件负责什么以及为什么与相邻文件分开,而不是罗列函数。当前内核有约 79% 的文件缺少文件头,这是最值得补齐的一项。
4.5 锁序注释¶
全局锁层级定义在 kernel/include/core/lock.h,完整顺序见 drivers/guide/lock-order.md。驱动的锁序注释用 LOCK_ORDER: 前缀标注,写的时候**只写相对顺序或被保护的不变量**:
/* LOCK_ORDER: rx_lock is released before acquiring proc_lock in the Ctrl-C
* path. The dump/signal helpers acquire proc_lock on their own. */
不要写只重复下一行 spin_lock_irqsave() 的形式(/* LOCK_ORDER: acquire rx_lock to push a character. */)。这种模板化注释已经在一次清理中从 53 处减到 18 处,剩下的都是承载真实约束的;新增时不要复制被删掉的那种写法。
4.6 ABI 与寄存器¶
- ABI 层(
kernel/abi/)手工解码的结构体必须给出**字节偏移表**并注明参考的 uapi 头文件。参考对象是调用方 userspace 里的结构体:对 Linux 兼容层来说是 musl/glibc 的shmid_ds、semid_ds、msqid_ds等,**不是**内核内部的shmid64_ds。 - 手写解码的 MMIO 寄存器位域必须注明每一位选中了什么,以及写错会导致什么可观察的后果。位域常常是**编码**而非字面值(STM32 的
PLLMUL就是bits + 2且 14 是特例)。
5. 提交信息风格¶
标题统一使用 type(scope): description,以英文祈使句说明这个提交改变了什么。描述首词小写,保留 QEMU、VMA、RISC-V、函数名和路径的原有拼写;不加句号。标题以 72 字符内为宜,最长 100 字符。scope 使用小写子系统名,例如 mm、net、hyp、build 或 history。
| type | 用途 |
|---|---|
feat |
增加可用行为或接口 |
fix |
修正已有行为、错误或回归 |
refactor |
调整实现结构,保持外部行为 |
perf |
改善性能或资源开销 |
docs |
修改文档 |
test |
增补或修正测试、门禁及基准工具 |
build |
修改编译、依赖或打包流程 |
ci |
修改持续集成流程 |
chore |
其他仓库维护 |
revert |
撤销已有改动 |
merge |
描述多父提交集成的功能或修复 |
类型取决于主要改动,不因补了测试就把修复写成 test,也不因同时改了 Makefile 就把功能写成 build。scope 使用子系统名称,不把 fix、feat 等类型再混入 scope。
正文与标题空一行。需要正文时,解释修改原因、行为变化和重要限制;验证部分只写实际执行的命令及结果。测试未执行时如实说明原因。完整日志、诊断过程和长期设计记录放在文档中,提交信息概括结论并给出路径。一个提交围绕一个可独立审阅的目的;避免 update、fix bugs、WIP 或阶段编号充当全部说明。
Co-authored-by 只用于实际参与该补丁的共同作者,不自动添加模型或工具名称。已有真实作者的署名应保留,不把工具使用记录冒充共同作者。
示例:
fix(mm): flush stale COW translations on RISC-V
Invalidate the previous writable translation before exposing the
read-only COW mapping to another hart.
Validation:
- make smoke-mm-stress
- make host-tests
示例中的验证命令仅说明写法,应替换为该提交实际执行的检查。
6. Pull Request¶
- 将分支推送到你的 fork。
- 在仓库页面创建 Pull Request。
- PR 描述中写明:
- 修改了什么
- 为什么需要改
- 运行了哪些门禁
- 是否关联 issue
CI 通过后,维护者会进行代码审查。请根据评论修改,并确保门禁持续通过。
7. 提问¶
有问题请先查看 docs/testing-gates.md 和 docs/zh/dev/build.md。若仍未解决,请创建 GitHub Issue,标签选 question,并附上相关命令和日志。
注意¶
- 不要直接修改
docs/zh/testing-gates.md或docs/zh/dev/external-dependencies.md中的契约字符串,除非你的改动确实触及这些契约。 - 不要把
ALLOW_UNVERIFIED_SMP=1作为默认门禁参数。只有 RISC-V64、AArch64、LoongArch64 和 x86_64 的同名 QEMU virt 板在Makefile的 SMP 白名单中;其他平台仅可在专门处理 SMP bring-up 的变更中使用该开关。 - 提交前请执行
make clean再运行一次关键门禁,避免旧产物造成误判。