CONTRIBUTING.md · 中科院软件所软件工程技术研究开发中心/RISC-V Porting Wiki

---
title: 贡献规范
lang: zh-CN
---

# Contributing Guideline

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

## 开始之前

::: tip
本知识库由 [TCSE-ISCAS](https://gitee.com/iscastcse) 的 RISC-V 软件适配知识库团队发起并维护，在
[木兰开放作品许可协议 署名-相同方式共享 第1版](http://license.coscl.org.cn/MulanOWLBYSAv1)
下为广大开发者提供服务。您对本知识库所做的任何贡献也将遵循同样的许可协议，请悉知。
:::

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

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

## 贡献流程

如果您希望对知识库已有内容**提出意见或建议**，请直接 [提交 Issues](#issue-规范)。

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

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

## Issue 规范

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

Issue 提交地址：[https://gitee.com/iscastcse/riscv-porting-wiki/issues](https://gitee.com/iscastcse/riscv-porting-wiki/issues)

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

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

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

![Issue 提交演示](./docs/res/contributing_issue_template.png)

## 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](https://github.com/DavidAnson/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 检查规则](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)。

### 外部链接占位符

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

例如：

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

### 示例编写规范

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

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

```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. 项目版本需要足够具体并提供外链**

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

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

::: tip 合法的版本号和链接示例

* **lafarga-subversion**：\[github-808013e\]
 \([https://github.com/guifi/lafarga-subversion/tree/808013eb543ca993e44803e3b3f98034b7dc853f/](https://github.com/guifi/lafarga-subversion/tree/808013eb543ca993e44803e3b3f98034b7dc853f/)\) 
* **Firefox**：\[78.15.0esr\]
 \([https://archive.mozilla.org/pub/firefox/releases/78.15.0esr/](https://archive.mozilla.org/pub/firefox/releases/78.15.0esr/)\)
:::

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

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

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

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

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

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

::: warning 谨慎使用此处未列出的语言提示符
若使用了未预先定义在 `/docs/.vuepress/config.js` 配置文件中的语言提示符，可能会导致运行或构建错误。
请先查询 [shiki 已支持的语言](https://github.com/shikijs/shiki/blob/main/docs/languages.md#all-languages)，
或将语言对应的 tmLanguage 文件及其 JSON 格式版本放置在知识库的 `/res/tmLanguages` 目录中，
并在上述配置文件中添加以注册语言。
:::

### 参考文献的列举

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

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

```md
这里使用了一篇参考文献 [[1]](#refer-1)。

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

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

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

在 Markdown 中的具体写法为：

```md
## 参考文献

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

中科院软件所软件工程技术研究开发中心/RISC-V Porting Wiki

简介

发行版

贡献者

近期动态

中科院软件所软件工程技术研究开发中心/RISC-V Porting Wiki .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

中科院软件所软件工程技术研究开发中心/RISC-V Porting Wiki