openEuler 社区补丁管理意见征集

#

## **范围:**

适用于openEuler 维护的src-openEuler 项目下开源软件仓库中的补丁。

## 用词约定：

规则：必须遵守的约定

建议：需要加以考虑的约定

# 1 目的

为了降低openEuler 社区开源软件补丁维护成本，根据开源社区对补丁应用惯例，制定如下规则。

# **2 补丁定义**

**从开源软件补丁来源，补丁可分为以下2类：**

| **补丁来源** | **定义**                                                     |
| ------------ | ------------------------------------------------------------ |
| **自研补丁** | 基于开源软件构筑差异化竞争力或修复开源软件社区未提供修复方案的缺陷，由openEuler社区自研开发且未被上游社区接纳的补丁。 |
| **社区补丁** | 开源软件社区提供用于特性增强/缺陷修复的补丁、对社区补丁进行适配的补丁、被社区接纳的openEuler社区自研补丁。 |

**从开源软件补丁用途，补丁可分为以下4类：**

| **补丁用途** | **定义**                       |
| ------------ | ------------------------------ |
| Bugfix补丁   | 解决开源软件缺陷的补丁         |
| Feature补丁  | 基于开源软件进行特性增强的补丁 |
| CVE补丁      | 解决开源软件安全漏洞的补丁     |

# **3 补丁划分**

## **3.1 【规则】禁止一个补丁解决多个问题/需求**

为了确保问题/需求对应的合入可追溯，禁止一个补丁解决多个问题/需求。

## **3.2 【建议】遵守“一个或多个补丁解决一个问题/需求”原则**

1、优先使用一个补丁解决一个问题；

# **4 补丁命名**

## **4.1 【规则】补丁文件名由前缀、名字主体和补丁后缀组成，补丁名中单词间通过”-”相连**

1、**补丁文件名前缀：**标识补丁来源，具体见下表。

| **补丁文件名前缀**   | **适用范围**            |
| -------------------- | ----------------------- |
| 无                   | 自研补丁。              |
| backport-            | 上游开源社区补丁。      |
| backport-[cve-name]- | 上游开源社区的CVE补丁。 |

2、**名字主体：**名字主体应能体现该补丁解决的问题或新增的需求，通常与第6章节描述信息中的主题保持一致。从上游社区backport的补丁，优先使用git-format-patch 命令生成，主体名称为git commit message 中标题内容。

3、**补丁后缀：**后缀固定为“.patch”。

样例：

| **示例类别** | **补丁文件名**                                               |
| ------------ | ------------------------------------------------------------ |
| 自研补丁     | net-hinic-Add-NIC-Layer.patch                                |
| 社区补丁     | backport-nvme-rdma-fix-timeout-handler.patch                 |
| CVE补丁      | backport-CVE-2017-17806-crypto-hmac-require-that-the-underlying-hash-algorit.patch |

# **5 补丁存放**

## **5.1 【规则】 补丁文件放置目录：对于spec管理的补丁，将补丁放置在源码压缩包的同级目录下**

1、对使用spec管理的补丁，所有补丁放置在源码压缩包所在目录中。

2、对于spec管理的补丁，在spec文件中通过序号指定补丁打入顺序。

# 6 补丁应用顺序

## **6.1 【规则】 补丁应用顺序按照先打上游社区补丁、再打openEuler 社区自研补丁**

根据经验，大部分软件包自研补丁数量远小于开源补丁，为了减少对开源源补丁适配工作量，建议先打开源补丁，再打自研补丁。

# **6 补丁辅助信息**

补丁辅助信息用于对补丁进行说明，主要包含：补丁描述信息、补丁标签、补丁修改记录等。

**1、补丁描述信息**

补丁描述信息是对代码的合入原因、方案及影响等进行有效描述，目的是让阅读者快速理解该补丁，主要包括以下几方面。

| **描述类别**     | **含义**                       |
| ---------------- | ------------------------------ |
| **主题**         | 补丁主题：一句话描述补丁功能   |
| **背景**         | 提交该补丁的原因               |
| **问题现象**     | 问题发生时的直观现象           |
| **复现条件**     | 问题复现需要执行的具体操作     |
| **根因分析**     | 导致问题的根本原因             |
| **实现方案**     | 解决问题或实现新特性的具体方案 |
| **补丁来源地址** | 该补丁的社区链接地址           |

**2、补丁标签**

补丁标签对不同贡献者进行标识，包括：补丁开发/合入者、补丁对应的问题发现者、补丁检视者、补丁验证者和补丁建议者，具体如下表所示。

| **标签**           | **含义**                                                     |
| ------------------ | ------------------------------------------------------------ |
| **Fixes:**         | 当前补丁所要修复的补丁信息  格式：Fixes: <commit-id>   (“commit-subject”) |
| **Signed-off-by:** | 开发者和committers签名                                       |
| **Reported-by:**   | 问题发现者签名：包括发现错误的人或者自动化扫描工具           |
| **Reviewed-by:**   | 检视人签名                                                   |
| **Tested-by:**     | 测试人签名                                                   |
| **Suggested-by:**  | 补丁建议者签名                                               |

**3、补丁修改记录**

补丁被检视后，需要对检视意见进行修改，补丁修改记录是对每次检视后所做修改的描述。

以上信息应尽量填写完整，以便其他人员只通过查看补丁信息就能了解整个补丁的情况，但不对所有信息做强制要求，以下针对每类补丁有具体的要求。

## **6.1 自研补丁**

对于自研补丁，只对补丁描述信息做明确要求，补丁标签和补丁修改记录可以通过代码提交系统承载。

### **6.1.1 【规则】自研补丁描述信息须包含两个信息：主题和背景。**

自研补丁的描述信息须包含主题和背景，其他描述信息可由Issue单承载。

## **6.2 开源社区补丁**

开源社区补丁一般通过邮件承载，信息承载较零散，应在补丁中把各种信息尽量描述清楚。

### **6.2.1 【建议】补丁描述信息：每一个补丁都要有描述信息，包括：主题、背景、问题现象、复现条件、根因分析、解决方法和补丁影响**

不同类别补丁的描述信息有不同的要求，以下列出不同类别应包含的描述信息：

| **补丁类别** | **应包含的描述信息**                                  |
| ------------ | ----------------------------------------------------- |
| Bugfix补丁   | 主题、问题现象、复现条件、根因分析、实现方案          |
| Feature补丁  | 主题、背景、实现方案                                  |
| CVE补丁      | 主题、CVE名字、问题现象、复现条件、根因分析、实现方案 |

### **6.2.2 【规则】补丁标签：开源社区补丁必须对不同贡献者通过不同标签进行区别**

为了保证补丁版权信息的完整性，补丁中需要增加所有贡献者的签名信息。

### **6.2.3 【建议】补丁修改记录：经过多次修改的补丁建议添加每一次修改所做出的变化**

补丁在修改后，建议添加此次补丁相比上次补丁所做的修改说明，最近一次修改说明放在最上方。添加修改说明的位置通常在签名等标签后，写明修改原因、作者、日期等信息。

###  **6.2.3 【规则】在补丁回合MR提交信息中，补齐补丁名称和commit链接地址（中间可以通过空格或者冒号隔开）**

MR 中描述解决的问题，并且填写补丁的commit 链接地址，方便代码检视

### **6.2.4 【建议】开源软件补丁头必须保持和上游社区一致，若补丁需要适配，不允许修改补丁头，且需要在补丁头Subject字段对适配情况做简要说明**

如果对上游backport 的补丁做了适配，建议在Subject 后面增加适配内容的简要描述。

## **6.3 【规则】软件版升级时需要重新审视已有补丁**

如果补丁解决的问题在高版本已经合入，补丁可以删除，否则需要判断是否继承。待继承的补丁需要找到补丁解决的原始问题然后重新适配。尤其要避免从上游新版本适配回来的补丁对低版本做了适配裁剪，升级高版本时补丁可以打上但是修改不全的问题。

## **6.4 【规则】自研补丁被社区接纳后，须使用被社区接纳的补丁替换**

openEuler自研补丁要尽量贡献到上游社区，推送到社区时，补丁辅助信息应遵从6.2章节，社区接纳后，须使用被社区接纳的补丁替换，包括补丁文件名和辅助信息等，以保持与社区一致。

# **7 相关文件&参考资料**

[1]   Linux文档：https://github.com/torvalds/linux/blob/master/Documentation/process/submitting-patches.rst

openEuler/community

内容风险标识

评论 (27)

openEuler/community .gitee-modal { width: 500px !important; }

内容风险标识