harmony 鸿蒙README.OpenSource 设计规范文档和使用指南

2025-06-16
浏览 (10)

README.OpenSource 设计规范文档和使用指南

引言

为了更好地追溯第三方开源软件的原始上游信息，OpenHarmony社区在《第三方开源软件引入指导》中要求：

新引入的开源软件必须在其根目录中提供 README.OpenSource 文件，该文件应准确描述以下内容：软件名称、许可证类型、许可文件位置、软件版本、对应版本的上游社区地址、软件维护者（Owner）、功能描述及依赖关系。

然而，在实际编写 README.OpenSource 文件时，社区开发者常常因规范定义和填写要求不够明确，尤其是在处理多许可证和多开源软件等复杂场景时，导致文件内容不规范。因此，本文档旨在为OpenHarmony项目中的 README.OpenSource 文件提供一套更清晰、更易理解的设计规范与使用指南。在保持原有元数据字段结构的基础上，我们将解决多个许可证可能共享同一许可证文件的问题，以满足工程化解析的需求，同时确保不影响现有 README.OpenSource 文件的使用。

范围

本指南适用于所有参与 OpenHarmony 社区的贡献者，特别是当引入第三方开源软件到 OpenHarmony 项目中时。

配置文件总体结构

README.OpenSource 文件采用 JSON 格式，包含一个数组，数组中的每个元素是一个开源软件的元数据对象。保持原有字段逻辑，不增删字段。

字段结构

[
    {
        "Name": "softwarename",              // 上游开源软件名全称
        "License": "SPDX-License-Identifier",// 许可证信息，可能包含多个，用分号分隔
        "License File": "path/to/license",   // 许可证文件路径，可能包含多个，用分号分隔
        "Version Number": "1.0.0",           // 软件版本号
        "Owner": "zhangsan@xyz.com",         // 维护人及邮箱
        "Upstream URL": "https://example.com", // 上游软件地址
        "Description": "软件功能简介",         // 软件描述
        // "Dependencies": ["dependency1", "dependency2"] // 可选，存在依赖时填写
    }
]

字段定义和填写指南

1. Name

说明：上游开源软件的全称。
要求：准确填写软件的正式名称，与上游发布的名称一致。

2. License

说明：开源软件的许可证信息。
要求：
- 使用 SPDX License Identifier 标准化填写。
- 多个许可证：用分号分隔。
```
";"
```
- 示例："MIT;BSD-3-Clause"
- 许可证顺序：与 License File 字段中的许可证文件路径一一对应。

3. License File

说明：许可证文件的路径。
要求：
- 多个许可证文件：用分号 ";" 分隔，顺序与 License 字段中的许可证一致。
- 当多个许可证对应同一个许可证文件时：在字段中重复该许可证文件路径。
```
License File
```
- 示例："LICENSE;LICENSE"
- 单个许可证对应多个许可证文件：在对应的许可证文件路径中，用冒号
```
":"
```
分隔多个文件。 - 示例："COPYING:LICENSE"

4. Version Number

说明：引入的开源软件版本号。
要求：填写上游发布的正式版本号，确保与实际使用的版本一致。

5. Owner

说明：开源软件在 OpenHarmony 组织下的维护人及其邮箱。
要求：填写负责该软件维护的人员邮箱。

6. Upstream URL

说明：上游开源软件的源代码仓库或发布页面链接。
要求：提供有效的上游软件源码或发行版链接。

7. Description

说明：开源软件的功能简介。
要求：用简洁的语言描述软件的主要功能和用途。

8. Dependencies（可选）

说明：该软件直接依赖的其他开源软件列表。
要求：
- 仅当软件存在被动依赖时，才需要填写此字段。
- 以数组形式列出依赖的软件名称，与依赖软件的 Name 字段一致。
- 示例："Dependencies": ["dependency1", "dependency2"]

使用指南

1. 引入新开源软件

步骤：
1. 为引入的软件创建独立的代码仓库。
2. 在仓库根目录下创建 README.OpenSource 文件。
3. 按照上述字段定义填写 README.OpenSource 文件。
4. 如果软件存在被动依赖，确保所有依赖的软件也已主动引入，并有对应的 README.OpenSource 文件。

2. 处理多许可证情况

多个许可证对应同一个许可证文件：
- 在 License 字段中列出所有许可证，用分号 ";" 分隔。
- 在 License File 字段中重复该许可证文件路径，与 License 字段中的许可证顺序对应。
- 示例： "License": "MIT;BSD-3-Clause", "License File": "LICENSE;LICENSE"
单个许可证对应多个许可证文件：
- 在 License 字段中填写对应的许可证。
- 在 License File 字段中，用冒号 ":" 分隔多个许可证文件路径。
- 示例： "License": "GPL-2.0+", "License File": "COPYING:LICENSE"
多个许可证对应多个许可证文件：
- 在 License 字段和 License File 字段中，分别用分号 ";" 分隔，顺序对应。
- 示例： "License": "MIT;Apache-2.0", "License File": "LICENSE-MIT;LICENSE-APACHE"

3. 维护依赖关系

说明：在主软件的 README.OpenSource 文件中，通过 Dependencies 字段列出其所有直接依赖的软件。
要求：
- 仅当软件存在被动依赖时，才需要填写 Dependencies 字段。
- 仅列出直接依赖，不列出间接依赖，间接依赖通过直接依赖呈现。
- 确保依赖的软件已在 OpenHarmony 中主动引入，并有对应的 README.OpenSource 文件。

4. 更新开源软件

步骤：
1. 当需要更新开源软件版本时，修改 Version Number 字段，确保与实际使用的版本一致。
2. 检查许可证信息是否有变化，若有，更新 License 和 License File 字段。
3. 检查依赖关系是否有变化，更新 Dependencies 字段。

5. 特殊情况处理

异常场景报备：如需在同一个 README.OpenSource 文件中管理多个开源软件，OpenHarmony主线组织下的项目必须提前向社区架构SIG报备申请。

工程化解析指导

解析器逻辑：
1. 读取 License 和 License File 字段，使用分号 ";" 分隔，得到许可证列表和许可证文件列表。
2. 通过索引对应，建立许可证与许可证文件的映射关系。
3. 当许可证文件路径中包含多个文件时，使用冒号 ":" 分隔，再次拆分。
解析示例：
```
"License": "MIT;BSD-3-Clause",
"License File": "LICENSE;LICENSE"
```
- 解析结果：
- 许可证列表：["MIT", "BSD-3-Clause"]
- 许可证文件列表：["LICENSE", "LICENSE"]
- 映射关系：
  - "MIT" 对应 "LICENSE"
  - "BSD-3-Clause" 对应 "LICENSE"

示例

示例 1：多个许可证对应同一许可证文件

[
    {
        "Name": "examplelib",
        "License": "MIT;BSD-3-Clause",
        "License File": "LICENSE;LICENSE",
        "Version Number": "1.2.3",
        "Owner": "developer@openharmony.io",
        "Upstream URL": "https://github.com/example/examplelib",
        "Description": "一个示例库，具有多个许可证对应同一许可证文件。"
    }
]

示例 2：单个许可证对应多个许可证文件

[
    {
        "Name": "complexlib",
        "License": "GPL-2.0+",
        "License File": "COPYING:LICENSE",
        "Version Number": "3.0.0",
        "Owner": "maintainer@openharmony.io",
        "Upstream URL": "https://github.com/example/complexlib",
        "Description": "一个复杂库，单个许可证对应多个许可证文件。"
    }
]

示例 3：具有依赖关系的软件

[
    {
        "Name": "bindgen",
        "License": "BSD-3-Clause",
        "License File": "LICENSE",
        "Version Number": "0.59.1",
        "Owner": "lihua@openharmony.io",
        "Upstream URL": "https://github.com/rust-lang/rust-bindgen",
        "Description": "用于生成 Rust FFI 绑定到 C/C++ 库的工具。",
        "Dependencies": ["shlex", "once_cell"]
    }
]

示例 4：无依赖的软件

[
    {
        "Name": "simplelib",
        "License": "Apache-2.0",
        "License File": "LICENSE",
        "Version Number": "0.1.0",
        "Owner": "zhaoliu@openharmony.io",
        "Upstream URL": "https://github.com/example/simplelib",
        "Description": "提供简单功能的库。"
        // 无需填写 Dependencies 字段
    }
]

注意事项

字段完整性：
- 保持原有字段结构，不增删字段。
- 除非明确说明可选，所有字段均为必填项。
- Dependencies 字段为可选，仅在存在依赖时填写。
许可证与许可证文件的对应关系：
- License 和 License File 字段中的元素数量和顺序必须一致。
- 当多个许可证对应同一个许可证文件时，重复许可证文件路径。
- 当许可证文件对应多个文件时，使用冒号 ":" 分隔。
解析规则一致性：
- 解析器应按照约定的分隔符和顺序解析，实现许可证与许可证文件的正确映射。
- 确保解析逻辑与填写规范一致，避免误解。
避免对存量文件的影响：
- 由于保持了原有字段结构，现有的 README.OpenSource 文件无需修改即可兼容新的解析规则。
字段格式要求：
- License 字段中的许可证顺序应与 License File 中的许可证文件顺序一致。
- 使用标准的 SPDX 许可证标识符，避免使用非标准或简写形式。
合规性检查：
- 确保填写的信息与上游开源软件的实际情况一致。
- 定期检查许可证和版本信息，确保及时更新。

开源义务履行

依据映射关系，确保每个许可证的义务得到正确履行。
处理流程：
1. 解析 License 和 License File 字段，建立许可证与许可证文件的映射。
2. 收集并审阅每个许可证文件，理解其要求。
3. 根据每个许可证的要求，执行相应的合规措施，如版权声明、源代码披露等。