1# README.OpenSource 设计规范文档和使用指南
2
3## 引言
4
5为了更好地追溯第三方开源软件的原始上游信息，OpenHarmony社区在 [《第三方开源软件引入指导》](第三方开源软件引入指导.md) 中要求：
6
7> 新引入的开源软件必须在其根目录中提供 `README.OpenSource` 文件，该文件应准确描述以下内容：软件名称、许可证类型、许可文件位置、软件版本、对应版本的上游社区地址、软件维护者（Owner）、功能描述及依赖关系。
8
9然而，在实际编写 `README.OpenSource` 文件时，社区开发者常常因规范定义和填写要求不够明确，尤其是在处理多许可证和多开源软件等复杂场景时，导致文件内容不规范。因此，本文档旨在为OpenHarmony项目中的 `README.OpenSource` 文件提供一套更清晰、更易理解的设计规范与使用指南。在**保持原有元数据字段结构**的基础上，我们将解决多个许可证可能共享同一许可证文件的问题，以满足工程化解析的需求，同时确保不影响现有 `README.OpenSource` 文件的使用。
10
11## 范围
12
13本指南适用于所有参与 OpenHarmony 社区的贡献者，特别是当引入第三方开源软件到 OpenHarmony 项目中时。
14
15
16## 配置文件总体结构
17
18`README.OpenSource` 文件采用 JSON 格式，包含一个数组，数组中的每个元素是一个开源软件的元数据对象。**保持原有字段逻辑，不增删字段**。
19
20### 字段结构
21
22```
23[
24    {
25        "Name": "softwarename",              // 上游开源软件名全称
26        "License": "SPDX-License-Identifier",// 许可证信息，可能包含多个，用分号分隔
27        "License File": "path/to/license",   // 许可证文件路径，可能包含多个，用分号分隔
28        "Version Number": "1.0.0",           // 软件版本号
29        "Owner": "zhangsan@xyz.com",         // 维护人及邮箱
30        "Upstream URL": "https://example.com", // 上游软件地址
31        "Description": "软件功能简介",         // 软件描述
32        // "Dependencies": ["dependency1", "dependency2"] // 可选，存在依赖时填写
33    }
34]
35```
36
37## 字段定义和填写指南
38
39### 1. Name
40
41- **说明**：上游开源软件的全称。
42- **要求**：准确填写软件的正式名称，与上游发布的名称一致。
43
44### 2. License
45
46- **说明**：开源软件的许可证信息。
47
48- 要求  ：
49  - 使用 [SPDX License Identifier](https://spdx.org/licenses/) 标准化填写。
50  - 多个许可证：用分号分隔。
51
52    ```
53    ";"
54    ```
55    - 示例：`"MIT;BSD-3-Clause"`
56
57  - **许可证顺序**：与 `License File` 字段中的许可证文件路径一一对应。
58
59### 3. License File
60
61- **说明**：许可证文件的路径。
62
63- 要求：
64
65  - **多个许可证文件**：用分号 `";"` 分隔，顺序与 `License` 字段中的许可证一致。
66
67  - 当多个许可证对应同一个许可证文件时： 在字段中重复该许可证文件路径。
68
69    ```
70    License File
71    ```
72
73    - 示例：`"LICENSE;LICENSE"`
74
75  - 单个许可证对应多个许可证文件：在对应的许可证文件路径中，用冒号
76
77    ```
78    ":"
79    ```
80
81     分隔多个文件。
82    - 示例：`"COPYING:LICENSE"`
83
84### 4. Version Number
85
86- **说明**：引入的开源软件版本号。
87- **要求**：填写上游发布的正式版本号，确保与实际使用的版本一致。
88
89### 5. Owner
90
91- **说明**：开源软件在 OpenHarmony 组织下的维护人及其邮箱。
92- **要求**：填写负责该软件维护的人员邮箱。
93
94### 6. Upstream URL
95
96- **说明**：上游开源软件的源代码仓库或发布页面链接。
97- **要求**：提供有效的上游软件源码或发行版链接。
98
99### 7. Description
100
101- **说明**：开源软件的功能简介。
102- **要求**：用简洁的语言描述软件的主要功能和用途。
103
104### 8. Dependencies（可选）
105
106- **说明**：该软件直接依赖的其他开源软件列表。
107
108- 要求：
109  - **仅当**软件存在被动依赖时，才需要填写此字段。
110  - 以数组形式列出依赖的软件名称，与依赖软件的 `Name` 字段一致。
111  - 示例：`"Dependencies": ["dependency1", "dependency2"]`
112
113## 使用指南
114
115### 1. 引入新开源软件
116
117- 步骤：
118  1. 为引入的软件创建独立的代码仓库。
119  2. 在仓库根目录下创建 `README.OpenSource` 文件。
120  3. 按照上述字段定义填写 `README.OpenSource` 文件。
121  4. 如果软件存在被动依赖，确保所有依赖的软件也已主动引入，并有对应的 `README.OpenSource` 文件。
122
123### 2. 处理多许可证情况
124
125- **多个许可证对应同一个许可证文件**：
126  - 在 `License` 字段中列出所有许可证，用分号 `";"` 分隔。
127  - 在 `License File` 字段中重复该许可证文件路径，与 `License` 字段中的许可证顺序对应。
128  - 示例：
129    ```
130    "License": "MIT;BSD-3-Clause",
131    "License File": "LICENSE;LICENSE"
132    ```
133
134- **单个许可证对应多个许可证文件**：
135  - 在 `License` 字段中填写对应的许可证。
136  - 在 `License File` 字段中，用冒号 `":"` 分隔多个许可证文件路径。
137  - 示例：
138    ```
139    "License": "GPL-2.0+",
140    "License File": "COPYING:LICENSE"
141    ```
142
143- **多个许可证对应多个许可证文件**：
144
145  - 在 `License` 字段和 `License File` 字段中，分别用分号 `";"` 分隔，顺序对应。
146  - 示例：
147    ```
148    "License": "MIT;Apache-2.0",
149    "License File": "LICENSE-MIT;LICENSE-APACHE"
150    ```
151
152### 3. 维护依赖关系
153
154- **说明**：在主软件的 `README.OpenSource` 文件中，通过 `Dependencies` 字段列出其所有直接依赖的软件。
155
156- 要求  ：
157  - **仅当**软件存在被动依赖时，才需要填写 `Dependencies` 字段。
158  - 仅列出直接依赖，不列出间接依赖，间接依赖通过直接依赖呈现。
159  - 确保依赖的软件已在 OpenHarmony 中主动引入，并有对应的 `README.OpenSource` 文件。
160
161### 4. 更新开源软件
162
163- 步骤  ：
164  1. 当需要更新开源软件版本时，修改 `Version Number` 字段，确保与实际使用的版本一致。
165  2. 检查许可证信息是否有变化，若有，更新 `License` 和 `License File` 字段。
166  3. 检查依赖关系是否有变化，更新 `Dependencies` 字段。
167
168### 5. 特殊情况处理
169
170- **异常场景报备**：如需在同一个 `README.OpenSource` 文件中管理多个开源软件，OpenHarmony主线组织下的项目必须提前向社区架构SIG报备申请。
171
172## 工程化解析指导
173
174- **解析器逻辑**：
175  1. 读取 `License` 和 `License File` 字段，使用分号 `";"` 分隔，得到许可证列表和许可证文件列表。
176  2. 通过索引对应，建立许可证与许可证文件的映射关系。
177  3. 当许可证文件路径中包含多个文件时，使用冒号 `":"` 分隔，再次拆分。
178
179- **解析示例**：
180  ```
181  "License": "MIT;BSD-3-Clause",
182  "License File": "LICENSE;LICENSE"
183  ```
184
185  - 解析结果：
186    - 许可证列表：`["MIT", "BSD-3-Clause"]`
187    - 许可证文件列表：`["LICENSE", "LICENSE"]`
188    - 映射关系：
189      - `"MIT"` 对应 `"LICENSE"`
190      - `"BSD-3-Clause"` 对应 `"LICENSE"`
191
192## 示例
193
194### 示例 1：多个许可证对应同一许可证文件
195
196```
197[
198    {
199        "Name": "examplelib",
200        "License": "MIT;BSD-3-Clause",
201        "License File": "LICENSE;LICENSE",
202        "Version Number": "1.2.3",
203        "Owner": "developer@openharmony.io",
204        "Upstream URL": "https://github.com/example/examplelib",
205        "Description": "一个示例库，具有多个许可证对应同一许可证文件。"
206    }
207]
208```
209
210### 示例 2：单个许可证对应多个许可证文件
211
212```
213[
214    {
215        "Name": "complexlib",
216        "License": "GPL-2.0+",
217        "License File": "COPYING:LICENSE",
218        "Version Number": "3.0.0",
219        "Owner": "maintainer@openharmony.io",
220        "Upstream URL": "https://github.com/example/complexlib",
221        "Description": "一个复杂库，单个许可证对应多个许可证文件。"
222    }
223]
224```
225
226### 示例 3：具有依赖关系的软件
227
228```
229[
230    {
231        "Name": "bindgen",
232        "License": "BSD-3-Clause",
233        "License File": "LICENSE",
234        "Version Number": "0.59.1",
235        "Owner": "lihua@openharmony.io",
236        "Upstream URL": "https://github.com/rust-lang/rust-bindgen",
237        "Description": "用于生成 Rust FFI 绑定到 C/C++ 库的工具。",
238        "Dependencies": ["shlex", "once_cell"]
239    }
240]
241```
242
243### 示例 4：无依赖的软件
244
245```
246[
247    {
248        "Name": "simplelib",
249        "License": "Apache-2.0",
250        "License File": "LICENSE",
251        "Version Number": "0.1.0",
252        "Owner": "zhaoliu@openharmony.io",
253        "Upstream URL": "https://github.com/example/simplelib",
254        "Description": "提供简单功能的库。"
255        // 无需填写 Dependencies 字段
256    }
257]
258```
259
260## 注意事项
261
2621. **字段完整性**：
263   - 保持原有字段结构，不增删字段。
264   - 除非明确说明可选，所有字段均为必填项。
265   - `Dependencies` 字段为可选，仅在存在依赖时填写。
2662. **许可证与许可证文件的对应关系**：
267   - `License` 和 `License File` 字段中的元素数量和顺序必须一致。
268   - 当多个许可证对应同一个许可证文件时，重复许可证文件路径。
269   - 当许可证文件对应多个文件时，使用冒号 `":"` 分隔。
2703. **解析规则一致性**：
271   - 解析器应按照约定的分隔符和顺序解析，实现许可证与许可证文件的正确映射。
272   - 确保解析逻辑与填写规范一致，避免误解。
2734. **避免对存量文件的影响**：
274   - 由于保持了原有字段结构，现有的 `README.OpenSource` 文件无需修改即可兼容新的解析规则。
2755. **字段格式要求**：
276   - `License` 字段中的许可证顺序应与 `License File` 中的许可证文件顺序一致。
277   - 使用标准的 SPDX 许可证标识符，避免使用非标准或简写形式。
2786. **合规性检查**：
279   - 确保填写的信息与上游开源软件的实际情况一致。
280   - 定期检查许可证和版本信息，确保及时更新。
281
282## 开源义务履行
283- **依据映射关系**，确保每个许可证的义务得到正确履行。
284- **处理流程**：
285  1. 解析 `License` 和 `License File` 字段，建立许可证与许可证文件的映射。
286  2. 收集并审阅每个许可证文件，理解其要求。
287  3. 根据每个许可证的要求，执行相应的合规措施，如版权声明、源代码披露等。
288
289## 本文的改进和修订说明
2901. 本文档由 OpenHarmony 合规 SIG 主导起草和维护。本文档的最新版本可在 [这里](第三方开源软件上游软件元数据READMEOpenSource文件设计规范和使用指南.md) 获取。
2912. 任何对于本文中涉及的规则的增加、修改、删除都必须被追踪，请进入该追踪系统。
2923. 最终规则经过社区充分的讨论后，由 PMC 评审定稿。
293