贡献指南

本文说明如何为 learn-cpu/rv32emu 提交问题、补丁和文档改动。项目主体是 C 语言实现的 RISC-V 模拟器，因此贡献时最重要的是保持语义清晰、测试可复现，并让 构建配置与源码条件编译保持一致。

提交 Issue

如果是缺陷报告、功能请求、系统模式/JIT 相关改动，建议先提交 Issue 讨论。这样 可以先确认设计方向，避免实现完成后才发现与项目边界不一致。

以下轻量改动通常可以直接提交补丁：

• 拼写、注释、文档修正
• 小范围代码整理
• 不改变行为的构建脚本修复
• 测试数据或 README 的小更新

代码风格

项目使用现代 C 风格，核心要求如下：

• 使用 4 个空格缩进，不使用 tab。
• 使用 Unix 换行（LF）。
• 删除行尾空白。
• 文件必须以换行结束。
• 函数左花括号另起一行。
• if、while、for、switch 等关键字后保留一个空格。
• 二元运算符两侧保留空格。
• 长表达式应换行，并用括号明确优先级。
• 复杂算法、硬件语义和边界条件必须写注释说明原因。

推荐注释格式：

/*
 * 多行注释用于说明模块、算法和关键假设。
 */

/* 简短单行注释。 */

可搜索标记：

• WARNING：维护者必须注意的风险。
• NOTE：解释“为什么这样做”。
• TODO：尚未完成的工作。
• FIXME：已知问题或临时实现。

格式化工具

提交前运行：

make format

该目标会调用：

• clang-format-20：格式化 C/C++ 文件
• shfmt：格式化 shell 脚本
• black：格式化 Python 文件
• dtsfmt：格式化设备树文件

如果只修改单类文件，也可以直接运行对应工具。

构建和测试

基础验证：

make defconfig
make
make check

JIT 相关改动：

make jit_defconfig
make
make check

系统模式相关改动：

make system_defconfig
make

架构合规测试需要额外工具链和 RISCOF 环境：

make ci_defconfig
make arch-test

提交补丁

建议按逻辑拆分提交：

• 一个提交只解决一个问题或实现一个清晰功能。
• 行为改动应同时包含测试或说明无法测试的原因。
• 构建脚本改动应说明影响的目标，例如 native、JIT、system、WASM。
• 不要把格式化、重命名和行为修改混在同一个提交中。

提交信息应简洁、具体，说明“改了什么”和“为什么改”。避免只写 fix、update 这类无法追踪意图的标题。

文档要求

面向用户的 README、docs、Makefile 提示、Kconfig help 和源码关键注释应使用中文 描述。指令名、寄存器名、宏名、系统调用名、文件名、命令和外部链接保持原文，便于 检索和对照上游规范。