鸿蒙三方库适配README.OpenSource文件解读

读懂README.OpenSource开源合规里这张「身份证」写了什么欢迎大家加入开源鸿蒙跨平台开发者社区前言在 OpenHarmony / 鸿蒙生态做C/C 三方库适配时仓库里常会看到一个名叫README.OpenSource的文件。它看起来是一段JSON不像普通 README 那样长篇大论却是开源治理与合规里很常用的一种写法用结构化数据把「这个组件是谁的、什么协议、从哪来、当前版本是什么」说清楚。本文以本仓库thirdparty/AES/README.OpenSource为例逐字段说明含义并解释为什么同一份文件里会出现两条记录。读完你可以对照自己项目检查是否缺项、是否与HPKBUILD/ 上游仓库一致。这个文件整体长什么样README.OpenSource的根结构是一个JSON 数组[]数组里每一项是一个对象{}代表一个需要声明开源信息的组件。本仓库里放了两个对象原因很实际第一条描述上游源码tiny-AES-c——算法实现本身从哪来、用什么协议。第二条描述本仓库里的适配与打包部分HPKBUILD、脚本、文档等——和上游是两套版权/协议分开写更清楚也避免误以为「整仓都是同一种协议」。下面分条解读每个字段在合规与协作里通常代表什么、本仓库填的是什么。第一条上游库 tiny-AES-c对应文件中的第一个{ ... }。字段名英文通俗含义本仓库示例值说明Name组件 / 软件的名称tiny-AES-c一般与上游项目常用名一致便于在清单、报表里检索。License开源许可证的SPDX 或社区通用简称Unlicense表示上游采用Unlicense一种非常宽松、接近「公有领域」的声明。实际条款以License File指向的文本为准。License File许可证全文或官方链接GitHub 上unlicense.txt的链接方便审核人员一键打开原文也可填本仓库内相对路径若你拷贝了许可证文件。Version Number上游版本号1.0.0应对应本次适配所基于的release / tag本库与HPKBUILD里pkgver一致。Owner上游维护主体组织或个人kokke通常填GitHub/Gitee 上的组织或用户名表示「谁维护上游」。Upstream URL上游官方源码主页https://github.com/kokke/tiny-AES-c溯源用从哪拉代码、issue/发布从哪看。Description简短功能 适配要点说明英文一段用一两句话说明库做什么可顺带写OpenHarmony 侧产物如静态库名、测试方式方便读文件的人不用翻HPKBUILD。一句话记住第一条回答的是——「我们用的那套 AES 源码法律上是谁的、什么协议、哪个版本、从哪下载。」第二条本仓库的 HPK 打包与适配部分对应文件中的第二个{ ... }。字段名英文通俗含义本仓库示例值说明Name这一「层」组件的名称AES OpenHarmony HPK packaging这里不是上游库名而是适配层的名称表示「lycium HPK 相关脚本与文档」这一包。License这一层采用的协议MITMIT很常见保留版权声明即可再分发、修改具体以LICENSE文件为准。License File许可证在哪里LICENSE本仓库根目录下的LICENSE文件与MIT对应。Version Number适配层版本1.0.0常与pkgver/ 发布节奏对齐若只改脚本不改上游也可单独递增。Owner适配仓库维护方oh-tpc与托管地址oh-tpc/aes一致表示谁在维护这份适配。Upstream URL这一层代码的托管地址https://gitcode.com/oh-tpc/aes这里填的是适配仓库本身方便别人 clone、提 PR。Description说明哪些文件归 MIT、与上游关系英文一段明确写清HPKBUILD、补丁、README、hnp.json 等用 MITtiny-AES-c 上游仍是 Unlicense避免混淆。一句话记住第二条回答的是——「除了上游源码外我们写的脚本和文档谁维护、什么协议、放在哪个仓库。」常见疑问帮助理解Q为什么不能只写一条记录A可以只写一条但本仓库上游 Unlicense与适配 MIT不同。合成一条容易让人以为「整个仓库只有一种协议」。拆成两条合规和审计时更清晰。QName和pkgnameAES为什么不一样Apkgname是 lycium 目录名 / 构建名README.OpenSource第一条 Name通常跟上游项目名一致tiny-AES-c。第二条才描述适配包本身。各司其职。Q字段名必须和表里一模一样吗A在 OpenHarmony 社区 / tpc 常见模板里字段名会与README.OpenSource规范对齐如Name、License、Version Number等。换平台时建议不要改键名只改值。总结README.OpenSource用JSON 数组列出组件的开源信息是溯源 许可证声明的精简载体。每个对象里的字段Name是谁、License什么协议、License File去哪看全文、Version Number哪一版、Owner谁维护、Upstream URL从哪来、Description一句话说明可含适配说明。本仓库两条记录一条给上游 tiny-AES-cUnlicense一条给OpenHarmony HPK 适配与打包MIT这样协议边界清楚也便于后续写材料或审计时直接使用。若你扩展了补丁、新增依赖或更换上游版本记得同步改Version Number、License File链接、Description并与HPKBUILD/README_zh.md保持一致。实战案例如何维护 README.OpenSource案例一更换上游版本当上游发布新版本时[{Name:tiny-AES-c,License:Unlicense,License File:https://github.com/kokke/tiny-AES-c/blob/master/unlicense.txt,Version Number:1.1.0,// 更新版本号Owner:kokke,Upstream URL:https://github.com/kokke/tiny-AES-c,Description:Small portable AES128/192/256 in C (updated to v1.1.0)}]同步修改HPKBUILD中的pkgverhnp.json中的versionSHA512SUM文件相关文档中的版本引用案例二添加新依赖如果适配包新增了依赖[{Name:AES OpenHarmony HPK packaging,License:MIT,License File:LICENSE,Version Number:1.0.0,Owner:oh-tpc,Upstream URL:https://gitcode.com/oh-tpc/aes,Description:HPK packaging scripts for tiny-AES-c. Depends on zlib for compression support.}]案例三许可证变更如果上游更改了许可证[{Name:tiny-AES-c,License:MIT,// 从 Unlicense 改为 MITLicense File:https://github.com/kokke/tiny-AES-c/blob/master/LICENSE,Version Number:2.0.0,Owner:kokke,Upstream URL:https://github.com/kokke/tiny-AES-c,Description:Small portable AES128/192/256 in C. License changed to MIT in v2.0.0}]开源合规检查清单必查项目许可证文件存在确认License File指向的文件可访问许可证兼容性确认上游许可证与适配许可证兼容版权声明完整源码中包含正确的版权声明版本号一致所有文件中的版本号保持一致上游链接有效Upstream URL可正常访问许可证兼容性矩阵上游许可证可用的适配许可证说明UnlicenseMIT, Apache-2.0, BSDUnlicense 最宽松MITMIT, Apache-2.0, BSDMIT 兼容性好Apache-2.0Apache-2.0需保留 NOTICEGPL-3.0GPL-3.0必须使用 GPL-3.0LGPL-2.1LGPL-2.1, GPL-3.0动态链接可保持 LGPL常见问题与解决方案Q1: 如何处理多个许可证A:如果上游使用双许可证{Name:library-name,License:MIT OR Apache-2.0,License File:[LICENSE-MIT,LICENSE-APACHE],Description:Dual-licensed under MIT or Apache-2.0}Q2: 如何处理许可证冲突A:常见情况GPL 闭源不可行必须开源Apache-2.0 GPL-2.0不兼容MIT 任意通常兼容解决方法咨询法务部门选择兼容的许可证组合必要时联系上游协商Q3: 如何验证许可证文件A:使用工具验证# 使用 SPDX 工具spdx-validate LICENSE# 使用 license-checkerlicense-checker--jsonlicenses.json# 手动比对diffLICENSE /path/to/upstream/LICENSE自动化检查CI/CD 集成# .github/workflows/license-check.ymlname:License Checkon:[push,pull_request]jobs:check:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv2-name:Check README.OpenSourcerun:|# 验证 JSON 格式 python -m json.tool README.OpenSource# 检查必需字段python scripts/check_opensource.py-name:Check License Filesrun:|# 检查许可证文件存在 test -f LICENSE-name:Check Version Consistencyrun:|# 检查版本号一致性 python scripts/check_versions.py检查脚本示例#!/usr/bin/env python3importjsonimportsysdefcheck_readme_opensource():withopen(README.OpenSource,r)asf:datajson.load(f)required_fields[Name,License,Version Number,Owner,Upstream URL]foritemindata:forfieldinrequired_fields:iffieldnotinitem:print(fERROR: Missing field {field} in{item.get(Name,unknown)})returnFalseprint(OK: All required fields present)returnTrueif__name____main__:sys.exit(0ifcheck_readme_opensource()else1)与其他文件的同步版本号同步检查#!/bin/bash# check_versions.sh# 从各文件提取版本号pkgver$(grep^pkgverHPKBUILD|cut-d-f2)hnp_ver$(jq-r.version hnp.json)opensource_ver$(jq-r.[0][Version Number]README.OpenSource)echoHPKBUILD:$pkgverechohnp.json:$hnp_verechoOpenSource:$opensource_ver# 检查一致性if[$pkgver$hnp_ver][$hnp_ver$opensource_ver];thenecho✓ All versions consistentexit0elseecho✗ Version mismatch detectedexit1fi许可证文件同步#!/bin/bash# sync_license.sh# 从 README.OpenSource 获取许可证文件 URLlicense_url$(jq-r.[0][License File]README.OpenSource)# 下载并比对curl-sL$license_url-o/tmp/upstream_licenseifdiff-qLICENSE /tmp/upstream_license/dev/null;thenecho✓ License file matches upstreamelseecho✗ License file differs from upstreamechoConsider updating LICENSE from upstreamfi最佳实践总结1. 及时更新上游发布新版本时立即更新许可证变更时重新评估兼容性定期检查链接有效性2. 完整记录记录所有依赖的开源组件保留许可证原文记录许可证选择的原因3. 自动化验证CI/CD 中集成许可证检查定期运行合规扫描生成 SBOM (Software Bill of Materials)4. 文档化在 README 中说明许可证信息记录许可证兼容性分析保留合规审查记录扩展阅读SPDX 标识符SPDX (Software Package Data Exchange) 是开源许可证的标准标识符MITMIT LicenseApache-2.0Apache License 2.0GPL-3.0GNU General Public License v3.0UnlicenseThe Unlicense完整列表https://spdx.org/licenses/合规工具FOSSA开源合规管理平台Black Duck开源风险分析Snyk开源安全与合规license-checkernpm 许可证检查若你扩展了补丁、新增依赖或更换上游版本记得同步改Version Number、License File链接、Description并与HPKBUILD/README_zh.md保持一致。