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 字段
    }
]

注意事项

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

开源义务履行

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

本文的改进和修订说明

1. 本文档由 OpenHarmony 合规 SIG 主导起草和维护。本文档的最新版本可在 这里 获取。
2. 任何对于本文中涉及的规则的增加、修改、删除都必须被追踪，请进入该追踪系统。
3. 最终规则经过社区充分的讨论后，由 PMC 评审定稿。