Contributing Guideline

感谢您关注 RISC-V 架构适配知识库，我们十分鼓励您参与到本知识库的建设工作中， 协助为更多开发者提供有关 RISC-V 架构的信息，为 RISC-V 开源生态贡献一份力量。

开始之前

在为本知识库作出贡献前，请先通过问题、电子邮件或任何其它方式与本知识库的维护团队取得联系， 讨论您想做的改变，再付诸实践。

同时，请注意阅读本贡献规范，并在修改本知识库的内容时始终遵守。

贡献流程

如果您希望对知识库已有内容提出意见或建议，请直接 提交 Issues。

如果您想对知识库已有的内容作出修改，或新增内容，请参考以下步骤：

1. 通过 Gitee 复刻（Fork）本项目的仓库
2. 阅读 README.md 和本文档以了解知识库的结构与贡献规范
3. 在 docs 目录中找到或创建对应的 Markdown 文档，编写相应内容
4. 如果您想本地预览修改后的知识库，请安装 Node.js 后于项目根目录执行 npm install 安装依赖， 随后执行 npm run docs:dev，即可看到本地预览地址
5. 使用 Git 工具创建 commit 并提交，注意在 commit message 中注明修改内容， 参考 Commit 规范
6. 向知识库主项目提交 Pull Request，等待知识库维护团队复审。
7. 若审核通过，您的修改将被署名并合入知识库，否则请您重新修改后再次提交。

Issue 规范

您可以在知识库的 Gitee 仓库下提交 Issue 以表明您的看法，或提出意见和建议。

Issue 提交地址：https://gitee.com/rvsmart-porting/knowledge-base/issues

我们已经准备了 Issue 模板，在新建 Issue 时您可以看到。 Issue 的标题请简短描述所属的知识库模块，例如：

知识库【rpmbuild 配置文件】部分问题反馈

请阅读 Issue 模板内容并按要求填写，注意按照问题类别添加对应的标签，确认无误后即可提交。

Commit 规范

在您复刻（Fork）本知识库后，您所作出的修改需要先通过 Git 版本管理工具提交 commit。 以下是一些有关 commit 的规范。

控制单个 commit 修改数量

由于 commit 包含与上一个版本的差异信息，我们建议您一次不要做过多的修改。

• 一次 commit 修改的页面（Markdown 文件）不要超过 5 个（除非是互相强关联的页面）
• 涉及大量页面内链的修改，请单独放置到一个 commit 中，并仔细检查有效性

编写简明扼要的提交信息

在进行 commit 时，会要求您填写提交信息（Commit Message）。

提交信息的第一行会显示在 Commit 历史记录中，请仅描述最主要修改的内容，例如：

修改【编译配置】中 GCC 相关的错误表述 增补【移位运算中的整形常量】部分内容

从提交信息的第二行起，我们希望您简明扼要地说明本次修改的内容，例如：

• 增补 5 个关于 RISC-V 架构浮点运算特性相关的编译参数及其描述
• 增补 2 组关于 X86 架构相关宏定义的实例分析

Pull Request 规范

在您将对知识库所做的更改提交 Pull Request 时，请阅读 Pull Request 页面提供的模板内容， 并填写相应内容。请务必清晰列举所有本次 Pull Request 中修改的章节，并简要说明修改内容。

Pull Request 内容经过知识库维护团队确认后，将会合并到主线版本中。

Markdown 格式

本知识库要求采用 MarkdownLint 进行 Markdown 格式检查， 检查配置详见项目根目录的 .markdownlint.json 文件。

目前有所调整的规则主要包括：

• MD013 (Line Length)：单行文字长度限制由默认的 80 个字符调整为 120 个字符
• MD025 (Multiple top-level headings in the same document)：该规则中的 Frontmatter 检查已禁用。
• MD033 (Inline HTML)：请查阅 .markdownlint.json 配置文件以了解目前该规则中允许使用的标签。

其它规则的详细信息，请参阅 MarkdownLint 检查规则。

外部链接占位符

若您编写的文档中，部分外部链接暂时无法提供，为保持 MarkdownLint 检查通过， 请统一使用 https://todo 作为占位链接。

例如：

[这是一个占位链接](https://todo)

示例编写规范

在知识库文档中需要以实际代码作为示例时， 请统一使用【四级标题】（在 Markdown 中表示为四个井号开头 ####）。

示例编写请参照以下模板：

#### 示例：【某软件名称】【简述源代码中的表现或行为】

* 项目名称：【软件项目名称】
* 项目版本：[版本号](版本号对应的项目源码根目录页面)
* 相关文件：
  * [`/path/to/file1`](该文件对应的URL地址)
  * [`/path/to/file2`](https://github.com/example/project/blob/<commit-sha>/path/to/file2)
* 简介：该文件属于该软件项目的【XXX 模块】，其主要作用是【XXXXXX】。该文件中【何处以何形式的代码涉及到当前说明的架构相关代码模式】。

此处详细描述该示例中的代码片段是如何与架构产生强相关性的，如有必要的话补充说明：
其它位置是如何使用该处代码的，以更好地解释该段代码与架构的相关性。

```cpp
代码片段 #1
``

此处解释第一段代码和第二段代码的关联。

```python
代码片段 #2
``

其中需要注意：

• 1. 项目版本需要足够具体并提供外链

  对于开源软件，请具体到对应的【开源代码托管平台】和【commit sha 值（可以是 7 位短值）】。 同时，版本号需要加上指向【该 commit 对应的源码树预览页面】的超链接。

  对于非开源软件或者没有提供公开可访问的、带版本控制的代码预览页面的开源软件，请填写最具体的版本号，以保证代码版本的唯一性。

• 2. 相关文件需要以相对路径的形式清晰列举

  若示例中仅涉及一个文件，请将该文件完整的【相对路径】列出， 并添加【指向该文件内容或预览页面】的超链接。

  若示例涉及多个相关文件，请以【无序列表】的方式将这些文件完整的【相对路径】列出， 并为每个文件添加【指向该文件内容或预览页面】的超链接。

• 3. 当前知识库已支持的代码块语言格式

  目前知识库采用 shiki 插件实现不同编程语言的代码高亮显示。 目前已经预先支持的语言定义在 /docs/.vuepress/config.js 文件的 plugins.shikiPlugin.langs 中， 同时已列举在下方，在使用代码块时请使用对应的语言提示符。

• 通用编程语言：c, cpp, shell, python, go, rust, java, makefile, markdown
• 自定义的 架构相关关键字 语言：arch-keywords
• RPM spec 配置文件语言：rpmspec

参考文献的列举

在 Markdown 中引用外部文献资料时，须使用 中括号数字上标锚点链接 的形式进行标注（如 ^[1]）， 并在文档末尾使用二级标题“参考文献”列举外部链接。

引用处在 Markdown 中的具体写法为：

这里使用了一篇参考文献 [<sup>[1]</sup>](#refer-1)。

这里使用了领一篇参考文献 [<sup>[2]</sup>](#refer-2)。

其中，<sup> 标签中的数字和锚点链接中的数字代表参考文献编号，须始终保持一致。

参考文献列举时，需通过 <a> 标签设置名称为 refer-N 的锚点，其中 N 为参考文献编号。 参考文献锚点与参考文献文字和链接之间须换行。

在 Markdown 中的具体写法为：

## 参考文献

* [1] <a id="refer-1"></a>
  [参考文献1](https://link-to-refer-1)
* [2] <a id="refer-2"></a>
  [参考文献2](https://link-to-refer-2)