1# README.OpenSource Design Specification Document and Usage Guide
2
3## Introduction
4
5In 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”](introducing-open-source-software.md):
6
7> 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.
8
9However, 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.
10
11
12## Scope
13
14This guide applies to all contributors in the OpenHarmony community, particularly when introducing third-party open-source software into the OpenHarmony project.
15
16## Overall Configuration Structure
17
18The `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**.
19
20### Field Structure
21
22```
23[
24    {
25        "Name": "softwarename",               // Full name of the upstream open-source software
26        "License": "SPDX-License-Identifier", // License information; multiple licenses are separated by semicolons
27        "License File": "path/to/license",    // Path to the license file; multiple paths are separated by semicolons
28        "Version Number": "1.0.0",            // Software version number
29        "Owner": "zhangsan@xyz.com",          // Maintainer’s contact (email)
30        "Upstream URL": "https://example.com",// Upstream software URL
31        "Description": "Brief function description", // Software description
32        // "Dependencies": ["dependency1", "dependency2"] // Optional; list if dependencies exist
33    }
34]
35```
36
37## Field Definitions and Completion Guidelines
38
39### 1. Name
40
41- **Description**: Full name of the upstream open-source software.
42- **Requirement**: Accurately enter the official software name as published by the upstream.
43
44### 2. License
45
46- **Description**: Open-source software license information.
47
48- Requirements
49
50  :
51
52  - Use standardized identifiers from [SPDX License Identifier](https://spdx.org/licenses/).
53
54  - For multiple licenses, separate them with a semicolon (`;`).
55
56    ```
57    ";"
58    ```
59
60    - Example: `"MIT;BSD-3-Clause"`
61
62  - **Order of licenses**: Corresponds one-to-one with the license file paths in the `License File` field.
63
64### 3. License File
65
66- **Description**: Path to the license file.
67
68- Requirements
69
70  :
71
72  - **Multiple license files**: Separate paths with a semicolon (`;`), maintaining the same order as in the `License` field.
73
74  - If multiple licenses refer to the same license file, repeat the path in the field.
75
76    - Example: `"LICENSE;LICENSE"`
77
78  - For a single license requiring multiple files, separate the paths with a colon.
79
80    ```
81    :
82    ```
83
84    - Example: `"COPYING:LICENSE"`
85
86### 4. Version Number
87
88- **Description**: Version number of the included open-source software.
89- **Requirement**: Enter the official release version from the upstream, ensuring it matches the actual version used.
90
91### 5. Owner
92
93- **Description**: Maintainer and their email address within the OpenHarmony organization.
94- **Requirement**: Enter the email address of the person responsible for maintaining the software.
95
96### 6. Upstream URL
97
98- **Description**: URL of the upstream source code repository or release page.
99- **Requirement**: Provide a valid link to the source code or release page of the upstream software.
100
101### 7. Description
102
103- **Description**: Brief function description of the open-source software.
104- **Requirement**: Use concise language to describe the software’s main functionality and purpose.
105
106### 8. Dependencies (Optional)
107
108- **Description**: List of other open-source software directly required by this software.
109- Requirements:
110  - **Only include** if the software has dependencies.
111  - List dependencies as an array, aligning each with the `Name` field of the dependent software.
112  - Example: `"Dependencies": ["dependency1", "dependency2"]`
113
114## Usage Guide
115
116### 1. Introducing New Open-Source Software
117
118- Steps:
119  1. Create a separate code repository for the new software.
120  2. Create a `README.OpenSource` file in the root directory of the repository.
121  3. Complete the `README.OpenSource` file using the field definitions above.
122  4. If the software has dependencies, ensure all dependent software is introduced and has its own `README.OpenSource` file.
123
124### 2. Handling Multiple License Situations
125
126- **Multiple licenses pointing to a single license file**:
127
128  - List all licenses in the `License` field, separated by semicolons.
129
130  - Repeat the license file path in the `License File` field to correspond with each license.
131
132  - Example:
133
134    ```
135    "License": "MIT;BSD-3-Clause",
136    "License File": "LICENSE;LICENSE"
137    ```
138
139- **Single license pointing to multiple license files**:
140
141  - Enter the license in the `License` field.
142
143  - Separate the multiple paths in `License File` with a colon (`:`).
144
145  - Example:
146
147    ```
148    "License": "GPL-2.0+",
149    "License File": "COPYING:LICENSE"
150    ```
151
152- **Multiple licenses with multiple license files**:
153
154  - Use a semicolon (`;`) to separate entries in both `License` and `License File` fields, maintaining one-to-one correspondence.
155
156  - Example:
157
158    ```
159    "License": "MIT;Apache-2.0",
160    "License File": "LICENSE-MIT;LICENSE-APACHE"
161    ```
162
163### 3. Maintaining Dependency Relationships
164
165- **Description**: In the main software’s `README.OpenSource` file, list all directly dependent software under `Dependencies`.
166- Requirements:
167  - Only list direct dependencies, omitting indirect dependencies.
168  - Ensure that each listed dependency is included in OpenHarmony with a corresponding `README.OpenSource` file.
169
170### 4. Updating Open-Source Software
171
172- Steps:
173  1. When updating the software version, update the `Version Number` field to reflect the new version.
174  2. Check for any changes in license information and update the `License` and `License File` fields if necessary.
175  3. Review and update the `Dependencies` field if dependencies have changed.
176
177### 5. Handling Special Cases
178
179- **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.
180
181## Engineering Parsing Guide
182
183- **Parser Logic**:
184
185  1. Read the `License` and `License File` fields, splitting entries with the semicolon (`;`) delimiter.
186  2. Establish a one-to-one mapping between licenses and license files based on index order.
187  3. When a path in `License File` contains multiple files, separate them with a colon (`:`).
188
189- **Parsing Example**:
190
191  ```
192  "License": "MIT;BSD-3-Clause",
193  "License File": "LICENSE;LICENSE"
194  ```
195
196  - Parsed output:
197    - License list: `["MIT", "BSD-3-Clause"]`
198    - License file list: `["LICENSE", "LICENSE"]`
199    - Mappings:
200      - `"MIT"` maps to `"LICENSE"`
201      - `"BSD-3-Clause"` maps to `"LICENSE"`
202
203## Examples
204
205### Example 1: Multiple Licenses Sharing a Single License File
206
207```
208[
209    {
210        "Name": "examplelib",
211        "License": "MIT;BSD-3-Clause",
212        "License File": "LICENSE;LICENSE",
213        "Version Number": "1.2.3",
214        "Owner": "developer@openharmony.io",
215        "Upstream URL": "https://github.com/example/examplelib",
216        "Description": "An example library with multiple licenses corresponding to a single license file."
217    }
218]
219```
220
221### Example 2: Single License with Multiple License Files
222
223```
224[
225    {
226        "Name": "complexlib",
227        "License": "GPL-2.0+",
228        "License File": "COPYING:LICENSE",
229        "Version Number": "3.0.0",
230        "Owner": "maintainer@openharmony.io",
231        "Upstream URL": "https://github.com/example/complexlib",
232        "Description": "A complex library with a single license covering multiple license files."
233    }
234]
235```
236
237### Example 3: Software with Dependencies
238
239```
240[
241    {
242        "Name": "bindgen",
243        "License": "BSD-3-Clause",
244        "License File": "LICENSE",
245        "Version Number": "0.59.1",
246        "Owner": "lihua@openharmony.io",
247        "Upstream URL": "https://github.com/rust-lang/rust-bindgen",
248        "Description": "A tool for generating Rust FFI bindings to C/C++ libraries.",
249        "Dependencies": ["shlex", "once_cell"]
250    }
251]
252``
253```
254
255### Example 4: Software with No Dependencies
256
257```
258[
259    {
260        "Name": "simplelib",
261        "License": "Apache-2.0",
262        "License File": "LICENSE",
263        "Version Number": "0.1.0",
264        "Owner": "zhaoliu@openharmony.io",
265        "Upstream URL": "https://github.com/example/simplelib",
266        "Description": "A library providing basic functionality."
267        // No need to fill in the Dependencies field
268    }
269]
270```
271
272## Notes
273
2741. **Field Integrity**:
275   - Retain the original field structure; do not add or remove fields.
276   - All fields are mandatory unless specifically indicated as optional.
277   - The `Dependencies` field is optional and should only be filled in if dependencies exist.
2782. **Correspondence between License and License File**:
279   - The elements in the `License` and `License File` fields must have the same quantity and order.
280   - When multiple licenses correspond to a single license file, repeat the path of the license file.
281   - When a license file corresponds to multiple files, separate the paths with a colon `":"`.
2823. **Consistency of Parsing Rules**:
283   - The parser should follow the agreed-upon delimiters and order to achieve accurate mapping of licenses to license files.
284   - Ensure that parsing logic aligns with entry guidelines to avoid misunderstandings.
2854. **Minimizing Impact on Existing Files**:
286   - As the original field structure is maintained, existing `README.OpenSource` files are compatible with the new parsing rules and do not require modification.
2875. **Field Formatting Requirements**:
288   - The order of licenses in the `License` field should match the order of license files in the `License File` field.
289   - Use standard SPDX license identifiers and avoid non-standard or abbreviated forms.
2906. **Compliance Checks**:
291   - Ensure that all entries accurately reflect the actual status of the upstream open-source software.
292   - Regularly check license and version information to ensure timely updates.
293
294## Fulfillment of Open-Source Obligations
295
296- **Based on Mapping**: Ensure each license obligation is properly fulfilled.
297- Process Steps:
298  1. Parse the `License` and `License File` fields to establish the mapping between licenses and license files.
299  2. Collect and review each license file to understand its requirements.
300  3. Implement the required compliance measures based on each license, such as copyright notices, source code disclosures, etc.
301
302## Document Improvements and Revision Notes
303
3041. This document is drafted and maintained by the OpenHarmony Compliance SIG. The latest version of this document is available here.
3052. Any additions, modifications, or deletions to the rules in this document must be tracked. Please access the tracking system for updates.
3063. Final rules are reviewed and approved by the PMC after thorough discussion within the community.
307