tpc-governance-platform-user-guide.md · OpenHarmony-TPC/docs

# 背景介绍
为了构建OpenHarmony 北向应用三方库的可持续发展生态，持续发掘和孵化具备发展潜力的 TPC（Third Party Component以下简称TPC）项目及其团队，OpenHarmony社区打造TPC项目的孵化器和优选平台，为开发者项目发展和社区管理提供治理方案和工程方案的辅导和支撑，整体框架见图1。当前平台原型和部分特性逐步开放使用，该文档用于相关操作说明。

图1 TPC治理整体框架

# TPC治理流程与规则
TPC项目治理旨在帮助开发者和用户了解项目当前所处阶段、预期的发展方向和成熟度，促进社区参与，提高透明度，通过风险控制保障项目质量和生态发展。根据TPC在鸿蒙应用中的采用规模、开源项目的健康度，我们将TPC项目按成熟度分为三个级别：沙箱项目（Sandbox）、孵化项目（Incubating）、毕业项目（Graduated）。TPC治理对不同阶段项目针对性设计策略：
- **沙箱项目**处于技术验证阶段，还未被鸿蒙应用实际依赖，我们鼓励项目获得及时的技术验证和开发者的贡献反馈， 判断其成为OpenHarmoy TPC生态的可能性；
- **孵化项目**已经被部分鸿蒙应用实际依赖使用，并有稳定的贡献者群体，通过成为孵化项目及时得到市场反馈和贡献者的持续贡献，增加鸿蒙应用对其采用量、扩大社区规模、提高项目质量和稳定性；
- **毕业项目**被视为功能完整、性能稳定，广泛被鸿蒙应用实际依赖使用，并有稳定的、较多的贡献者群体。对毕业项目的持续治理也将帮助其保持技术领先地位， 持续增加用户和贡献者、确保项目的稳定性和可持续性，推动整个 TPC 生态系统的发展。
## TPC治理流程
TCP治理针对不同成熟度项目涉及主要角色相同，治理活动包含TPC SIG Leader、TPC TAG(Technical Advisory Group)、TPC 垂域 Commiter和TPC 项目 Commiter等角色，不同角色具备不同定义和职责：
- **TPC SIG Leader**： TPC SIG的治理团队，负责所有TPC项目的技术方向、成熟度级别审核和项目健康监督。
- **TPC TAG**：TAG（Technical Advisory Group）是指具有特定TPC知识领域的专家组成的小组，就TPC-SIG中具体的项目给出技术指导和咨询意见。
- **TPC 垂域Commiter**：某一技术垂域的Commiter，具有相关技术垂域项目的管理权限。
- **TPC 项目Commiter**：某一项目的Commiter，具有相关项目的管理权限。

不同角色在项目选型、沙箱、孵化、毕业等阶段承担申请、评审、建仓、开发等职责并享有对应的项目管理权限，TPC治理平台面向以上用户和场景提供工作流程支持。**关于OpenHarmony社区TPC治理的具体细则可查阅[《OpenHarmony TPC 治理 Charter》](./tpc-governance-charter.md)**。

## TPC治理指标字典
TPC项目治理目的在于确保TPC项目的合法性、合规性和质量，旨在降低项目风险并提升整体技术生态。围绕**基本信息**、**合法合规**、**技术生态**、**生命周期**和**网络安全**五个维度，通过检查许可证、兼容性、依赖源码获取性、社区活跃度、代码质量、版本生命周期、网络安全等方面，保证软件选择符合法律要求、避免潜在风险，并提高系统的可维护性和安全性，建立健康的软件生态，推动项目成功和持续发展。  
在TPC治理指标字典中，通常包含指标名称、维度、重要性、风险是否必须澄清、指标意义和评分规则等条目，其中***风险是否必须澄清***项需重点关注，其表示如项目在相应指标上出现风险告警（TPC治理平台项目报告会自动提示），是否要求申请人必须对告警项进行澄清并由相关责任人确认（通常为TPC SIG Leader和垂域Committer），澄清要求为是的项目须所有风险已澄清并确认才可进入下一阶段。***指标意义***中通常包含**规则**和**建议**两类要求并以方括号对两类内容进行区分，其中规则类为必须遵从，建议类为最佳实践建议遵从。

### 孵化项目指标字典
**孵化项目**阶段涉及检查项及评分规则见下表：
| **维度** | **指标名称** | **重要性** | **风险是否必须澄清** | **指标意义** | **检查/评分规则** |
|------|------|------|------|------|------|
| 基本信息 | 适配仓库命名 | 低 | N/A | 仓库名需满足社区要求以便统一管理 【规则】 1. 仓库命名统一为ohos_软件名称，其中软件名称和其官网保持一致； 2. 禁止以软件的子模块作为软件名； | 不设置评分，仅检查是否满足。 |
| 基本信息 | 官方网址 | 低 | N/A | 引入软件官方网址 【规则】 1. 提供引入软件官方网址，无正式官网则提供主流代码托管商（github、gitee等）对应项目托管地址； | 不设置评分，仅检查是否满足。 |
| 基本信息 | 源码地址 | 低 | N/A | 引入软件官方源码下载地址 【规则】 1.. 提供引入软件版本的官方源代码包下载地址，保证可溯源； | 不设置评分，仅检查是否满足。 |
| 网络安全 | 二进制制品 | 高 | 是 | 引入软件源码仓库是否包含二进制制品 【建议】 不建议二进制引入，应从源码构建。如必要引入须在TPC SIG决策，并提供构建指导； | 设置评分。满足10分，不满足0分。 |
| 生命周期 | 软件功能归一 | 高 | 是 | 同功能软件只在OpenHarmony及TPC中引入一款 【规则】 1. 主动选型开源软件与被动依赖开源软件同功能软件只在OpenHarmony及TPC中引入一款，避免重复引入； | 不设置评分，仅检查是否满足。 |
| 合法合规 | 许可证包含 | 高 | 是 | 引入软件许可证合规性检查 【规则】 1. 禁止选用无许可证、许可证不是开源促进会OSI批准的开源许可证的软件； 【建议】 1. 选择软件本身许可证（含项目级和文件级）及其依赖软件许可证均为宽松类型许可证的软件； 2. 项目的所有源码包含许可头与版权声明； | 设置评分。许可证是OSI批准的，且宽松型许可证10分，弱宽松型许可证8分，非宽松型许可证6分；无项目级许可证或许可证不是OSI批准的开源许可证0分； |
| 合法合规 | DCO | 中 | 否 | 引入软件代码提交者原创性声明签署检查 【建议】 1. 项目的提交者应签署DCO; | 设置评分。项目所有贡献者签署DCO 10分，部分签署8分，无人签署6分。 |
| 合法合规 | 许可证兼容性 | 高 | 是 | 引入软件许可证兼容性检查 【规则】 1. 禁止引入项目级、文件级License存在兼容性问题的软件及版本 | 设置评分。引入软件项目级、文件级许可证存在兼容性问题0分，无兼容性问题10分。 |
| 技术生态 | 依赖可获得 | 高 | 是 | 引入软件依赖源码可获得检查 【规则】 1. 项目依赖的库必须是开源软件，可公开获得。 | 设置评分。引入软件依赖的库是开源软件10分，依赖软件非开源软件0分。 |
| 技术生态 | 代码维护 | 高 | 否 | 社区活跃度及是否活跃维护检查 【规则】 1. 选用成熟期（代码更新活跃，定期发布）或成长期（代码更新活跃，频繁发布）的软件，禁止选用处于衰退期（代码无更新或无新版本发布）的软件； | 设置评分。采用OSS-Compass最近一年活跃度模型平均得分，得分范围0-10分。|
| 技术生态 | 适配方式 | 高 | 是 | OH TPC适配方式及引入成本评估。 【建议】 优先采用“JS/TS适配”、“C/C++库移植”方式引入TPC软件；不建议采用“仅作为实现参考”、“Java库重写”方式引入； | 设置评分。JS/TS适配 10分，C/C++库移植 10分，仅作为实现参考8分，Java库重写 6分。 |
| 技术生态 | 社区支撑 | 高 | 否 | 社区服务与支撑检查 【建议】 1. 社区无明确版本计划，有效bug、PR半年以上未响应不建议选用； | 设置评分。采用OSS-Compass最近一年社区服务与支撑模型平均得分，得分范围0-10分。 |
| 生命周期 | 版本生命周期 | 高 | 是 | 检查引入软件版本社区维护生命周期是否结束 【建议】 1. 优先选择2年以内发布的版本（以评审节点计算）； 2. 社区已经EOL的版本，不建议引入； | 设置评分。最近2年内有版本发布10分，版本发布超过2年6分，没有发布任何版本4分，仓库已归档0分。 | 
| 网络安全 | 安全漏洞 | 高 | 是 | 检查引入软件及依赖源码是否有公开未修复漏洞 【规则】 1. 禁止选用含非误报病毒告警的软件（含被动依赖软件）； 2. 禁止选用含已知未修复漏洞软件； | 设置评分。无公开未修复漏洞10分，有公开未修复漏洞0分； |
| 网络安全 | 漏洞响应机制 | 高 | 否 | 引入软件漏洞响应机制检查 【规则】 1. 选用开源软件必须有漏洞反馈与修复跟踪管理机制； | 设置评分。检查漏洞响应链接（默认使用Issue作为响应方式）是否可用，满足10分，不满足6分。 |
| 技术生态 | 采用度分析 | 中 | 否 | 引入软件采用度分析，优选在业界广泛应用软件 【建议】 1. 优选主流的供应商/社区或社区项目； 2. 优选在业界成熟应用或产品实际使用效果好的软件； | 设置评分。 评分细则待定 |
| 技术生态 | 软件质量 | 中 | 否 | 引入软件质量分析，包含代码规范，圈复杂度，代码复用度，测试用例覆盖度 【规则】 1. 不符合技术架构与技术演进淘汰的软件禁止引入； 【建议】 1. 技术架构优选更安全、灵活度高、支持组件化、插件化的软件； 2. 优选代码质量高的软件，如使用不安全函数数量/密度少、代码结构规范（圈复杂度低）、重复度低、代码调试功能可关闭、有自动化构建能力、自动化测试充分； | 设置评分。最终得分 = avg(代码重复率得分 + 测试覆盖率得分) 代码重复率评分: 0% - 2% => 10分 3% - 4% => 8分 5% - 9% => 6分 10% - 19% => 4分 20% - 99% => 2分 100% => 0分 测试覆盖率评分: 80% - 100% => 10分 70% - 79% => 8分 50% - 69% => 6分 30% - 49% => 4分 1% - 29% => 2分 0% => 0分 |
| 技术生态 | 专利风险 | 中 | 否 | 引入软件专利风险分析 【建议】 1. 优先选择全球专利保护社区OIN（Open Invention Network）认证软件，未认证软件需单独审视专利风险； | 设置评分。 评分细则待定 |
| |

### 毕业项目指标字典
**毕业项目**阶段涉及检查项及评分规则见下表：
| **维度** | **指标名称** | **重要性** | **指标意义** | **检查/评分规则** |
|------|------|------|------|------|
| 合法合规 | 许可头与版权声明 | 高 | 孵化软件源文件许可头与版权声明检查：项目的所有源码必须包含许可头与版权声明。 | 设置评分。满足10分，不满足0分 |
| 合法合规 | 片段引用 | 高 | 片段引用源代码应申明其原始License和Copyright，并禁止变更其原始License和Copyright声明；片段引用的源代码的License和项目的License须保证兼容性。 | 	设置评分，满足10分，不满足0分 |
| 合法合规 | DCO | 中 | 孵化项目代码提交者原创性声明签署检查：所有孵化期新增代码代码提交者都应签署DCO。	| 设置评分。项目孵化期所有贡献者签署DCO 10分，不满足0分 |
| 合法合规 | 许可证包含 | 高 | 孵化软件许可证合规性检查：仓库标准位置包含许可证且许可证为OSI批准的开源许可证。引用或适配的开源软件必须在其根目录提供README.OpenSource文件，在该文件中准确描述上游软件名、许可证、许可文件位置、版本、对应版本的上游社区地址、软件的维护Owner、功能描述。 | 设置评分。满足10分，不满足0分 |
| 合法合规 | 许可证兼容性 | 高 | 软件许可证兼容性检查：针对衍生作品代码，检查上游软件的许可证是否允许贡献者将本衍生作品代码进行开源贡献，以及上游软件的许可证允许贡献者采用何种许可证进行贡献。 | 设置评分。软件项目级、文件级许可证存在兼容性问题0分，无兼容性问题10分 |
| 合法合规 | 许可证与版权声明防篡改 | 高 | 软件涉及第三方开源软件的许可证和版权声明篡改检查: 通过上游软件衍生的作品应当完整保留原上游软件的License及Copyright信息，项目中不能篡改第三方开源软件的许可证和版权声明。 | 设置评分。满足10分，不满足0分 |
| 网络安全 | 二进制制品 | 高 | 孵化软件源码仓库是否包含二进制制品检查：源码仓库包含二进制增加用户风险，不允许。 | 设置评分。满足10分，不满足0分 |
| 网络安全 | 安全漏洞 | 高 | 孵化软件及依赖源码是否有公开未修复漏洞检查：项目被公开超过60天的中等或更高严重程度的漏洞必须被修复，所有致命漏洞必须完成修复。 | 设置评分，满足10分，不满足0分 |
| 网络安全 | 软件包签名 | 中 | 孵化项目软件包数据签名校验检查: 项目发布的版本需要进行数字签名，以校验下载包的完整可靠。 |	设置评分。软件包分发包含数字校验10分，不包含6分 |
| 技术生态 | README |	高 | 仓库须在特定位置包含README文档，且命名、内容符合规范（简明扼要地描述本项目的功能，显示项目的孵化状态）。| 设置评分。满足10分，不满足0分 |
| 技术生态 | 构建文档 | 高 | 仓库须在特定位置或README中提供构建文档。 |	设置评分。满足10分，不满足0分 |
| 技术生态 | 接口文档 | 高 | 仓库须在特定位置提供接口文档。 | 设置评分。满足10分，不满足0分 |
| 技术生态 | Committers文件 | 中 | 孵化项目Committers文件检查：维护一个具备决策权的贡献者的公开列表。 | 设置评分，满足10分，不满足0分 |
| 技术生态 | 问题管理机制 | 中 | 孵化软件问题管理、跟踪系统检查: 项目必须提供issue跟踪所有问题，并对登记的issue应进行合理的分类、分级	。 | 设置评分。项目提供issue跟踪所有问题6分，未实现0分，对登记的issue应进行合理的分类或分级8分，分类且分级10分（项目提供issue跟踪所有问题6分，未实现0分，分类10分） |
| 技术生态 | 问题响应比例 | 中 | 孵化软件问题响应检查: 项目需响应过去2~12个月的大多数Issues（>80%) | 设置评分。项目过去6个月的Issues响应比例80%以下6分，以上10分 |
| 技术生态 | 问题响应时长 | 中 | 孵化软件问题时长检查： 项目在过去6个月收到的本项目涉及的三方软件的任何漏洞报告的初始响应时间必须小于或等于14天。 | 设置评分。项目在过去6个月收到的本项目涉及的三方软件的任何漏洞报告的初始响应时间小于或等于14天10分，14天到30天8分，未响应0分，其他6分 |
| 技术生态 | 代码评审机制 | 中 | 孵化项目代码评审机制检查：项目代码合入前须经过评审。 |	设置评分。项目代码合入前审查比例超过80% 10分，60%-80% 6分，其他0分 |
| 技术生态 | 可构建 | 高 | 孵化项目可构建出可工作的系统检查：项目必须支持从源代码构建出可工作的系统，且应该仅使用业界可公开获得的构建工具。 | 设置评分，满足10分，不满足0分 |
| 技术生态 | CI集成 | 高 | 孵化项目CI集成检查： 项目支持与社区现有工具链集成并提供CI服务。 | 设置评分，满足10分，不满足0分 |
| 技术生态 | 测试覆盖度 | 高 | 代码质量检查，要求不使用不安全函数、代码结构规范（圈复杂度低）、重复度低、自动化测试充分。 |	设置评分。最终得分 = avg(代码重复率得分 + 测试覆盖率得分) 代码重复率评分: 0% - 2% => 10分 3% - 4% => 8分 5% - 9% => 6分 10% - 19% => 4分 20% - 99% => 2分 100% => 0分 测试覆盖率评分: 80% - 100% => 10分 70% - 79% => 8分 50% - 69% => 6分 30% - 49% => 4分 1% - 29% => 2分 0% => 0分
| 技术生态 | 回合上游 |	高 | 孵化软件适配、新增特性推荐回合上游社区，毕业前需检查是否实施回合动作（在上游社区建立Issue、PR讨论回合需求），受限于上游社区业务规划和开源策略，不要求特性代码最终合入上游分支，但需保留相关提案和讨论记录（上游社区Issue和PR即可）。 | 设置评分。在上游社区建立回合Issue和PR 6分，未完成0分，特性合入上游分支 10分。 |
| 生命周期 | 生命周期申明 | 高 | 发布软件版本须在版本发布文档中对生命周期进行申明或者提供社区统一生命周期管理策略。 | 	设置评分，满足10分，不满足0分 |
| 生命周期 | Release Notes | 中 | 孵化项目Release Notes检查: 项目版本发布需在特定位置包含Release Notes，提供清晰明了的版本变更说明。 | 设置评分，满足10分，不满足0分 |
| |

# TPC治理平台
平台原型当前基于开源项目[OSS-Compass](https://compass.gitee.com/)构建，OSS-Compass是为开源社区健康、生态分析提供的公共SaaS平台，收集多种平台大量开源项目数据，能够更好的帮助OpenHarmony TPC治理完成选型评估、开发监控、生命周期维护等任务。

TPC治理相关功能作为模块在OSS-Compass Saas平台对外提供服务，当前仅面向受邀请开发者/组织试用，用户可登陆平台后选择对应导航栏或者点击[链接](https://compass.gitee.com/oh)进入，见图2。

图2 OSS-Compass平台导航栏

用户登陆后导航栏无**OpenHarmony**条目，说明账户不在初始开放名单中，对于第一次登陆OSS-Compass平台的用户不可见该栏目也是如此，请通过邮件发送账户信息（昵称和邮箱，获取方式见[查看账户信息](#查看账户信息)章节）以及申请原因到 yinyuancao@163.com 或 lishengbao147@gmail.com，我们将尽快处理并反馈您结果。

# 平台使用指导
部分用户可能未接触过OSS-Compass平台，以及新增OpenHarmony治理模块，本章节将依次对相关操作进行说明，用户可按照个人需求跳转到对应小节，不会对整体内容理解产生影响。

## 平台注册
用户可通过访问[OSS-Compass主页](https://compass.gitee.com/)后选择**登陆**（ 见图3） ，或者直接访问[OSS-Compass登陆](https://compass.gitee.com/auth/signin)进入相关页面，当前平台用户注册仅支持直接以Github、Gitee账户登陆后自动完成注册（见图4），如您无以上平台账户请前往对应平台注册。

图3 OSS-Compass平台导航栏(含右侧)

图4 OSS-Compass登陆

选择对应平台登陆按钮后将跳转到相应平台完成鉴权，通过后将自动跳转回OSS-Compass用户界面。Github与Gitee鉴权/登陆界面见图5，图6，注意，当您选择通过登陆自动创建OSS-Compass账户是代表您同意OSS-Compass的《使用条款》和《隐私协议》，建立您在选择登陆平台和账户前在登陆界面点击相关文件仔细阅读内容中条款，无异议后再进行登陆动作。三方登陆鉴权时我们仅获取您第三方账户基本信息，相关数据我们将严格按照上述文件规定场景使用，不会用作其他用途。

图5 Github登陆/鉴权

图6 Gitee登陆/鉴权

## 查看账户信息
你可以直接通过登陆后导航栏中用户头像下**账户设置**或者[User Profile](https://compass.gitee.com/settings/profile)链接直接查看用户信息，见图7。

图7 OSS-Compass账户设置

## 沙箱（孵化准备）项目
## 孵化项目
### 孵化项目报告申请
当您需要申请将相关项目进入OpenHarmony TPC孵化项目时，您需要先完成项目报告申请，你可按照**TPC治理-孵化项目-报告申请**路径进入相关页面，见图8：

图8 孵化项目报告申请

相关字段带'*'星号为必填，字段解释如下：  
| **字段** | **描述** | **是否必选** |  
|-------|-------| ------ |
| 软件名称 | 待生成报告项目名称 | 是 |
| 所属领域 | 根据软件性质选择对应领域分类，可选UI、数据库、网络协议等 | 是 |
| 开发商 | 软件厂商或者作者信息，个人项目提供代码托管平台ID | 是 |
| 官网地址 | 软件官方网站，无单独介绍网站可填写源码地址 | 是 |
| 编程语言 | 软件主要编程语言，提供代码行数占比最高的编程语言 | 是 |
| 源码地址 | 软件源码地址，优选提供Github、Gitee等主流代码托管平台地址 | 是 |
| 引入方式 | 提供软件引入方式，可为Java库适配、JS/TS适配、C/C++库移植和参考 | 是 |
| 漏洞响应机制 | 提供软件对应漏洞反馈、响应服务链接 | 是 |

填写完相关字段后点击**提交**按钮将跳转到**申请列表界面**。

### 孵化项目报告查看
完成报告提交后可在**TPC治理-孵化项目-申请列表**查看申请报告和历史报告状态，见图9： **生成中**表示项目正在分析，**生成成功**表示报告已生成，可点击查看报告详情，见图10。

图9 孵化项目报告列表

图10 孵化项目报告详情

**注：** 当前平台提供**基础信息修改**能力，用户可在报告详情界面基础信息栏点击右上角修改按钮直接修正信息，当前仅支持软件名称、领域、开发商等基础信息修改，且要求相关修改人员具有报告管理权限（通常为报告提交人）。如您在基础信息栏目未见修改按钮，说明您不具备此报告的修改权限，可联系报告提交人操作。

### 孵化项目申请
完成孵化项目报告生成后，可进行孵化项目申请，可按照**TPC治理-孵化项目-选型申请**路径进入申请界面，见图11：

图11 孵化项目申请界面

点击选择软件选择对应报告：

图12 孵化项目申请报告选择界面

选择报告后完成提交需进一步补充孵化周期、需求来源、建仓等信息，相关内容均为必填：

图13 孵化项目申请信息填写

完成相关信息填写后提交申请将跳转至Gitee仓库**OpenHarmony-TPC/docs**创建Issue，Issue内容已根据社区所填内容自动生成，再次检查无误后可直接点击创建Issue按钮：

图14 孵化项目申请Issue创建

Issue完成创建后，TPC SIG Leader和申请项目对应垂域Committer将收到邮件通知。

OpenHarmony-TPC/docs
Closed

About

Releases

Contributors

Activities