harmony 鸿蒙README.OpenSource Design Specification Document and Usage Guide

2025-06-12
浏览 (261)

README.OpenSource Design Specification Document and Usage Guide

Introduction

In order to better trace the original upstream information of third-party open-source software, the OpenHarmony community requires in the “Third-Party Open Source Software Introduction Guidelines”:

Newly introduced open-source software must provide a README.OpenSource file in its root directory. This file should accurately describe the following: software name, license type, location of the license file, software version, the upstream community address corresponding to this version, software maintainer (Owner), functional description, and dependencies.

However, when actually writing the README.OpenSource file, community developers often face issues due to insufficiently clear specifications and filling requirements. This is especially true when dealing with complex scenarios like multiple licenses and multiple open-source software. As a result, the file contents may not conform to standards. Therefore, this document aims to provide a clearer and more understandable set of design specifications and usage guidelines for the README.OpenSource file in the OpenHarmony project. While maintaining the original metadata field structure, we will address the issue where multiple licenses may share the same license file, to meet the needs of engineering parsing, while ensuring that the current README.OpenSource file remains unaffected.

Scope

This guide applies to all contributors in the OpenHarmony community, particularly when introducing third-party open-source software into the OpenHarmony project.

Overall Configuration Structure

The README.OpenSource file uses JSON format and contains an array where each element represents the metadata object of an open-source software entry. No fields are added or removed from the original structure.

Field Structure

[
    {
        "Name": "softwarename",               // Full name of the upstream open-source software
        "License": "SPDX-License-Identifier", // License information; multiple licenses are separated by semicolons
        "License File": "path/to/license",    // Path to the license file; multiple paths are separated by semicolons
        "Version Number": "1.0.0",            // Software version number
        "Owner": "zhangsan@xyz.com",          // Maintainer’s contact (email)
        "Upstream URL": "https://example.com",// Upstream software URL
        "Description": "Brief function description", // Software description
        // "Dependencies": ["dependency1", "dependency2"] // Optional; list if dependencies exist
    }
]

Field Definitions and Completion Guidelines

1. Name

Description: Full name of the upstream open-source software.
Requirement: Accurately enter the official software name as published by the upstream.

2. License

Description: Open-source software license information.
Requirements

Use standardized identifiers from SPDX License Identifier.
For multiple licenses, separate them with a semicolon (;).
```
";"
```
- Example: "MIT;BSD-3-Clause"
Order of licenses: Corresponds one-to-one with the license file paths in the License File field.

3. License File

Description: Path to the license file.
Requirements

Multiple license files: Separate paths with a semicolon (;), maintaining the same order as in the License field.
If multiple licenses refer to the same license file, repeat the path in the field.
- Example: "LICENSE;LICENSE"
For a single license requiring multiple files, separate the paths with a colon.
```
:
```
- Example: "COPYING:LICENSE"

4. Version Number

Description: Version number of the included open-source software.
Requirement: Enter the official release version from the upstream, ensuring it matches the actual version used.

5. Owner

Description: Maintainer and their email address within the OpenHarmony organization.
Requirement: Enter the email address of the person responsible for maintaining the software.

6. Upstream URL

Description: URL of the upstream source code repository or release page.
Requirement: Provide a valid link to the source code or release page of the upstream software.

7. Description

Description: Brief function description of the open-source software.
Requirement: Use concise language to describe the software’s main functionality and purpose.

8. Dependencies (Optional)

Description: List of other open-source software directly required by this software.
Requirements:
- Only include if the software has dependencies.
- List dependencies as an array, aligning each with the Name field of the dependent software.
- Example: "Dependencies": ["dependency1", "dependency2"]

Usage Guide

1. Introducing New Open-Source Software

Steps:
1. Create a separate code repository for the new software.
2. Create a README.OpenSource file in the root directory of the repository.
3. Complete the README.OpenSource file using the field definitions above.
4. If the software has dependencies, ensure all dependent software is introduced and has its own README.OpenSource file.

2. Handling Multiple License Situations

Multiple licenses pointing to a single license file:
- List all licenses in the License field, separated by semicolons.
- Repeat the license file path in the License File field to correspond with each license.
- Example:
```
"License": "MIT;BSD-3-Clause",
"License File": "LICENSE;LICENSE"
```
Single license pointing to multiple license files:
- Enter the license in the License field.
- Separate the multiple paths in License File with a colon (:).
- Example:
```
"License": "GPL-2.0+",
"License File": "COPYING:LICENSE"
```
Multiple licenses with multiple license files:
- Use a semicolon (;) to separate entries in both License and License File fields, maintaining one-to-one correspondence.
- Example:
```
"License": "MIT;Apache-2.0",
"License File": "LICENSE-MIT;LICENSE-APACHE"
```

3. Maintaining Dependency Relationships

Description: In the main software’s README.OpenSource file, list all directly dependent software under Dependencies.
Requirements:
- Only list direct dependencies, omitting indirect dependencies.
- Ensure that each listed dependency is included in OpenHarmony with a corresponding README.OpenSource file.

4. Updating Open-Source Software

Steps:
1. When updating the software version, update the Version Number field to reflect the new version.
2. Check for any changes in license information and update the License and License File fields if necessary.
3. Review and update the Dependencies field if dependencies have changed.

5. Handling Special Cases

Exceptional Cases Reporting: If managing multiple open-source software entries within a single README.OpenSource file, the project within OpenHarmony’s main branch must report to the Community Architecture SIG in advance.

Engineering Parsing Guide

Parser Logic:
1. Read the License and License File fields, splitting entries with the semicolon (;) delimiter.
2. Establish a one-to-one mapping between licenses and license files based on index order.
3. When a path in License File contains multiple files, separate them with a colon (:).
Parsing Example:

  "License": "MIT;BSD-3-Clause",
  "License File": "LICENSE;LICENSE"

Parsed output:
- License list: ["MIT", "BSD-3-Clause"]
- License file list: ["LICENSE", "LICENSE"]
- Mappings:
  - "MIT" maps to "LICENSE"
  - "BSD-3-Clause" maps to "LICENSE"

Examples

Example 1: Multiple Licenses Sharing a Single License File

[
    {
        "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": "An example library with multiple licenses corresponding to a single license file."
    }
]

Example 2: Single License with Multiple License Files

[
    {
        "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": "A complex library with a single license covering multiple license files."
    }
]

Example 3: Software with Dependencies

[
    {
        "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": "A tool for generating Rust FFI bindings to C/C++ libraries.",
        "Dependencies": ["shlex", "once_cell"]
    }
]
``

Example 4: Software with No Dependencies

[
    {
        "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": "A library providing basic functionality."
        // No need to fill in the Dependencies field
    }
]

Notes

Field Integrity:
- Retain the original field structure; do not add or remove fields.
- All fields are mandatory unless specifically indicated as optional.
- The Dependencies field is optional and should only be filled in if dependencies exist.
Correspondence between License and License File:
- The elements in the License and License File fields must have the same quantity and order.
- When multiple licenses correspond to a single license file, repeat the path of the license file.
- When a license file corresponds to multiple files, separate the paths with a colon ":".
Consistency of Parsing Rules:
- The parser should follow the agreed-upon delimiters and order to achieve accurate mapping of licenses to license files.
- Ensure that parsing logic aligns with entry guidelines to avoid misunderstandings.
Minimizing Impact on Existing Files:
- As the original field structure is maintained, existing README.OpenSource files are compatible with the new parsing rules and do not require modification.
Field Formatting Requirements:
- The order of licenses in the License field should match the order of license files in the License File field.
- Use standard SPDX license identifiers and avoid non-standard or abbreviated forms.
Compliance Checks:
- Ensure that all entries accurately reflect the actual status of the upstream open-source software.
- Regularly check license and version information to ensure timely updates.

Fulfillment of Open-Source Obligations

Based on Mapping: Ensure each license obligation is properly fulfilled.
Process Steps:
1. Parse the License and License File fields to establish the mapping between licenses and license files.
2. Collect and review each license file to understand its requirements.
3. Implement the required compliance measures based on each license, such as copyright notices, source code disclosures, etc.

Document Improvements and Revision Notes

This document is drafted and maintained by the OpenHarmony Compliance SIG. The latest version of this document is available here.
Any additions, modifications, or deletions to the rules in this document must be tracked. Please access the tracking system for updates.
Final rules are reviewed and approved by the PMC after thorough discussion within the community.