!294 api治理章程更新

Merge pull request !294 from zhangyongzhi/master

zh-cn/design/OpenHarmony-API-governance.md

@@ -14,19 +14,20 @@
 
 ![](figures/API-Scope-And-Definition.png)
 
-OpenHarmony API按使用方分类包括：
-
-- PublicApi：公开发布，提供给三方应用开发使用的API。
-- SystemApi：非公开发布，仅授权系统应用可使用的API。
--  TestApi：受限发布，仅适用于xTS或应用调试阶段可使用的API。
+OpenHarmony API按可授权使用方分类包括：
+- Public API：公开发布，提供给三方应用开发使用的API。
+- System API：非公开发布，仅授权系统应用（被额外授予某些特定系统权限能力）可使用的API。
+-  Test API：受限发布，仅适用于xTS或应用调试阶段可使用的API。
+如无特别说明，本章程定义的条款同时适用于Public API、System API或Test API等三种OpenHarmony API。针对System API和Test API的额外要求或例外说明，通过特别说明方式加以补充说明。
 
 OpenHarmony API按编程语言分类包括：
-
 - Java API：面向应用开放的Java编程语言接口。
 - JS API：面向应用开放的JavaScript编程语言接口。
 - Native API：面向应用开放的C/C++编程语言接口。
+如无特别说明，本章程定义的条款同时适用于Java API、JS API和Native API等三种编程语言OpenHarmony API。
 
 ## API治理
+
 ### 角色与职责
 
 |**涉及角色**|**API治理中的职责**|
@@ -43,7 +44,6 @@ API评审流程如下：
 ![](figures/API-Review-Process.png)
 
 主要过程说明：
-
 1. API评审申请、代码提交（Owner：Contributor），除代码提交外，如果涉及API新增或变更需同步提交相应的API设计文档，详细说明API的需求来源、场景与使用方法、权限设计、隐私保护澄清等，详见后面的API评审申请要素。为避免后续的返工，Contributor可以在正式的API评审申请、代码提交之前，先通过邮件方式将API设计文档提交Committer、领域SIG、API SIG等相关人员预审。
 1. 代码评审（Owner：Committer），代码评审和API预审，涉及API提交CodeReview通过后，还需要进一步领域SIG评审。如果单次提交同时涉及多个领域的API新增或变更，相应的API评审申请和代码需要同时提交给相关领域的Committer评审，只有所有对应领域的Committer都完成CodeReview后才能进入下一评审环节。
 1. API评审（Owner：领域SIG），新增API相关的代码提交评审，领域SIG评审通过即可代码合入；变更API相关的代码提交，领域SIG评审通过后，还需要进一步提交API SIG。如果单次提交同时涉及多个领域的API新增，相应的API评审申请和代码需要同时提交给相关领域的SIG评审，只需一个领域SIG评审通过即可代码合入。如果单次提交同时涉及多个领域的API变更，相应的API评审申请和代码需要同时提交给相关领域的SIG评审，只有所有对应领域的SIG都要评审通过才能进入下一评审环节。
@@ -51,17 +51,22 @@ API评审流程如下：
 1. 评审完成。
 
 ### API评审申请要素
-如果涉及API新增或变更需同步提交相应的API设计文档，建议包含如下要素：
+如果涉及API新增或变更需同步提交相应的API设计文档。
 
+针对新增API，需要包含如下要素：
 1. 需求来源与使用场景（必须）。
 1. API现状与差距分析，说明API新增或变更的必要性（必须）。
 1. API原型设计与使用方法说明（必须）；必要时，可以进一步包含相应的使用样例（可选）。
 1. API权限设计（必须）。
 1. API隐私保护方案与要求满足情况澄清（必须）；
 1. 提交代码的同时提交相应的API参考（必须）；必要时，可同步提交相应的开发者指南文档（可选）。
-1. 针对老接口的处理方式（废弃、隐藏或彻底删除）、替代接口和相应的应用兼容措施（可选，如果涉及API变更，则必须包含）。
 1. 兼容性/性能/功耗/可靠性/测试等相关情况说明（可选，如不满足本章程 “4 API设计要求”，则必须包含相关说明）。
 
+针对变更API，需要额外包含如下要素：
+1. 针对老接口的处理方式（废弃、隐藏或彻底删除）以及对使用老SDK开发应用的兼容措施（必须）；
+2. 变更影响、替代接口和相应的应用适配方案（必须）。
+3. 刷新ChangeLog（必须） 和 API-diff文档（涉及JS/Native API变更，必须；Java API的差异报告可工具化生成，不需要人工提交）。
+
 ## API设计要求
 ### 一致性要求
 1. 概念一致性：基于场景的业务模型抽象，形成OpenHarmony的连贯、一致、自恰的用户程序模型和业务概念。
@@ -73,7 +78,6 @@ API评审流程如下：
 
 ### 易用性要求
 以“能力使用者”视角，而不是“能力提供者”视角设计API：
-
 1. 可理解：API命名和功能特性必须容易理解。
 1. 易使用：提供简单易用的API，减少API之间不必要的耦合，避免多个无之间关联关系API之间调用顺序的依赖，尽可能使调用者优雅，尽量避免使用单一功能时必须同时组合调用多个包/模块或类中的多方法才能实现。
 1. 避免误导：提供使用者期望的能力，避免误导，减少误用。
@@ -87,14 +91,11 @@ API评审流程如下：
 1. 不用或少用缩写，业界通用术语遵从行业习惯允许使用缩写。
 1. 包名/模块名/命名空间前缀约定：
    1. Java API 统一包名： package ohos.\*。
-   2. JS API 统一模块名：@system.\*。
+   2. JS API 统一模块名：@ohos.\*。
    3. Native API 统一命名空间：namespace OHOS.\*。
-   4. 引用外部开源代码的，可以保留原包名/模块名/命名空间，也可以按照上述规则统一进行替换。
-
-7. 包名/模块名/命名空间最短不少于2段，最长不超过4段；每一段建议使用一个单词，最长不超过2个单词。
-8. 类名、方法名/函数名、成员变量、变量名最多不超过4个单词。
-
-
+   4. 引用外部开源代码的，可以保留原包名/模块名/命名空间，也可以按照上述规则对包名统一进行替换。
+1. 包名/模块名/命名空间最短不少于2段，最长不超过4段；每一段建议使用一个单词，最长不超过2个单词。
+1. 类名、方法名/函数名、成员变量、变量名最多不超过4个单词。
 
 ### 权限控制要求
 1. 完备性原则：一切穿透应用沙箱的行为都需考虑使用权限来管控。
@@ -119,34 +120,37 @@ API评审流程如下：
 1. 如果执行过程中可能抛出异常，则API参数必须包含相关的异常描述。
 1. 必须包含API的起始版本号（使用@since注释标记）。
 1. 可选包括本模块或类自己的版本号（使用@version注释标记）。
+1. 涉及API变更(不兼容)，必须同步交付API-Diff和ChangeLog文档。
 
 ### 兼容性要求
 1. 按严格程度从高到低，API兼容要求包括：契约兼容 > 二进制兼容 > 源码兼容。
    1. 源码兼容：指版本演进后，开发者已有的源代码可正常编译通过。
    1. 二进制兼容：指版本演进后，开发者已有程序不用重新编译可正常链接、运行。
    1. 契约兼容：也称语义兼容，指版本演进后，开发者原有程序行为不发生变化。
-   
-1. OpenHarmony API后向兼容必须满足二进制兼容要求，常见破坏二进制兼容的API变更包括：
+1. OpenHarmony API后向兼容必须满足二进制兼容要求，例外情况需要通过API SIG评审并经过PMC批准。常见破坏二进制兼容的API变更包括：
    1. 任何API元素删除；
    1. 降低方法的可见性，例如protected修改为了private，或者public修改为protected。
    1. 类类型发生变化，例如抽象类变更为非抽象类，或者接口类(“Interface”)变更为非接口类。
    1. 方法原型发生变化，例如返回值类型修改，或入参顺序或入参类型发生变化。
    1. 成员final/static等属性发生变化，例如非final成员变成final，或者非static的成员变成static。
-   
-1. OpenHarmony API在特定目的下，如Bugfix，允许不遵守契约兼容要求。
-
 1. 禁止“原型相同、功能不兼容”的API修改，可受限使用“废弃old-api、新增new-api”的方式进行修改。
-
 1. 根据发布类型不同，API的生命周期和兼容性要求：
 
 ![](figures/API-Lifecycle.png)
 
-   1. Canary版本：相同API Version的多个Canary版本之间要求保持API兼容，Canary阶段新增的API允许在后续的Canary版本中标记为废弃或隐藏。Canary阶段新增的API允许在后续第一个Beta版本中彻底删除。
-   2. Beta版本：相同API Version的多个Beta版本之间要求保持API兼容，Beta阶段新增的API允许在后续的Beta版本中标记为废弃或隐藏，API Stable版本发布之后API即冻结，之后再发布的Beta版不允许任何形式的API新增或变更。Beta阶段新增的且在API Stable版本中标记为废弃或隐藏的API允许在后续第一个Release版本中彻底删除。
-   3. Release版本：通过Release版本对外发布的API，需要遵守对外部开发者的“契约承诺”，原则上不允许对已经Release发布的API进行不兼容修改，受限允许对已发布的API进行废弃。已经Release发布的API废弃基本要求包括：
-      1. 废弃接口标记。
-      2. 提供可替代接口。
-      3. 废弃API至少保留5个API Version版本（对废弃5个API Version的API可以彻底删除，不再支持）。
+   1. Canary版本：早期发布的预览版本，不承诺API稳定。
+       1. 对上一Release发布版本保持API兼容。
+       1. 相同API Version的多个Canary版本之间无API兼容性要求。
+   1. Beta版本：公开发布的Beta测试版本，不承诺API稳定。
+       1. 对上一Release发布版本保持API兼容。
+       1. 对同一API Version的早期发布的Canary版本不兼容。
+       1. 相同API Version的多个Beta版本之间无API兼容性要求。
+       1. API Stable版本发布之后API即冻结，之后再发布的Beta版不允许任何形式的API新增或变更。
+   1. Release版本：正式发布版本。
+       通过Release版本对外发布的API，需要遵守对外部开发者的“契约承诺”，原则上不允许对已经Release发布的API进行不兼容修改，受限允许对已发布的API进行废弃。已经Release发布的API废弃基本要求包括：
+       1. 废弃接口标记。
+       1. 提供可替代接口。
+       1. 废弃API至少保留5个API Version版本（对废弃5个API Version的API可以彻底删除，不再支持）。
 
 ### 性能/功耗/可靠性要求
 1. 应及时响应，避免调用者等待；如果API调用执行时间过长应设计为异步方式。