Change for API Rules

Signed-off-by: Nqiangbo <qiangbo@hotmail.com>

.gitignore

+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk

zh-cn/design/API-Review-Template.md

+# OpenHarmony xxx子系统 xxx API评审申请
+
+## 背景
+
+* API类型：[Public API | Test API| HDI]
+* API需求来源：
+* API使用场景：
+* API所属子系统：
+* API预计发布版本：
+* Contributor：
+* 本次评审涉及的API数量：
+
+| 类型 | 数量 | 编程语言 |
+|---|---|---|
+| 新增 |  |  |
+| 行为变更 | |
+| 废弃 | | |
+| 删除 | | |
+
+## API说明
+
+### 必要性说明
+
+> 现状与差距分析。API的使用场景和价值是什么？
+
+### 总体特性说明
+
+> 相关API完成了哪些功能特性。
+
+## 评审结论
+
+### Committer评审结论
+
+### 领域SIG评审结论
+
+## 自查表
+
+| 自查项 | 自查结果 |
+|---|---|
+| 是否已完成拼写检查？ |  |
+| 是否遵循了编码规范？ | |
+| 词性使用是否正确（名词，形容词，副词）？ | |
+| 命名是否完整表述了API所做的全部逻辑？| |
+|API的参数数量是否合理？（通常少于7个）| |
+|是否合理使用了缩写？（缩写是大家周知的）| |
+|void类型API是否真的考虑过调用者不需要返回值？| |
+|是否考虑过继承体系是合适的？父类的每一个方法都适用于子类| |
+|已定义的错误状态是否完备？| |
+| 命名是否正确使用了对仗词：<br/> add/remove, create/destroy, insert/delete, start/stop, begin/end,  <br/> send/receive, up/down, show/hide, open/close, source/target, <br/>source/destination,  increase/decrease, first/last, next/previous | |
+|新增API与同模块既存API表述和语义层次是否一致？| |
+| 同步API是否需要提供异步版本？ | |
+| 是否每一个public API都真的是开发者需要的？| |
+
+## API接口及说明
+
+> 请填写代码的提交地址。
+
+* 代码地址：
+
+## API权限设计
+
+> 使用该接口是否需要申请相应的权限。
+
+## API隐私保护设计
+
+> 涉及用户隐私，需要考虑隐私保护。
+
+## 开发者指南
+
+> 可选。
+
+## API代码示例
+
+> 二选一即可。
+
+* 代码地址：
+* 代码片段：
+
+## API变更说明
+
+> 新增接口不需要填写此章节。
+
+### 行为变更
+
+> API行为变更是指API的接口没有发生变化，仅仅是行为发生变化。
+> API行为变更需要在新的API版本上进行，不允许破坏旧版本API行为（除非是缺陷修复）。
+
+#### 相关接口
+
+#### 变更原因
+
+### 废弃接口
+
+> 废弃接口的API说明中，需要添加`@deprecated`注解进行（包括：JS/TS/C/C++接口）标记。
+
+#### 相关接口
+
+> 需描述从哪个版本开始标记为废弃。
+
+#### 废弃原因
+
+#### 替代接口
+
+> 如果有则提供，如果无则说明原因。
+
+### 删除接口
+
+> 接口不允许直接删除，需要在标记废弃之后经过5个API版本才允许删除。
+
+#### 相关接口
+
+#### 删除原因
+
+#### 替代接口
+
+> 如果有则提供，如果无则说明原因。
+
+## DFX
+
+### 兼容性
+
+### 性能
+
+### 功耗
+
+### 可靠性
+
+### 可测试性
+
+> API必须同步交付API自动化测试用例，用例100%覆盖API接口。
+
+## 评审结论
+
+* 评审时间：
+* 与会人：
+* 评审结论：[通过|不通过]
+* 评审会议纪要：
\ No newline at end of file

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

 # OpenHarmony API治理章程
 
+## 总览
 
+为了引导OpenHarmony生态健康、有序发展和演进，本章程对OpenHarmony API的新增、变更、废弃、删除等生命周期与治理流程进行约束，同时定义了基本的API设计要求。
 
-## 总览
+本章程由[API SIG](https://www.openharmony.cn/SIG/api/)制定，经[PMC](https://www.openharmony.cn/community/pmc/)批准发布；本对章程的修订必须经由API SIG评审后，由PMC批准发布。
+
+## 概述
+
+### 范围与定义
+
+OpenHarmony软件栈中包含了多个角色，因此API也分作多种类型。
 
+<img src="figures/API-Category.png" width="800" />
 
+不同的API类型其兼容性要求也不一样，具体如下表所述：
 
-为了引导OpenHarmony应用生态健康、有序发展演进，本章程对OpenHarmony API的新增、变更、废弃、删除等生命周期与治理流程进行约束，同时定义了基本的API设计要求。
+| 类型 | 提供者 | 使用者 | 兼容性要求 | 看护手段|
+|---|---|---|---|---|
+| Public API | 系统与框架 | 所有应用开发者 | 5个API版本| XTS|
+| Test API | 测试框架  | 所有应用开发者| 3个API版本| 待构建 |
+| System API |  系统与框架 |系统应用开发者 |不承诺| 待构建 |
+| HDI | HDF| 系统服务 | 4个API版本| XTS |
+| Driver API | HDF | 驱动开发者 | 不承诺 | 无 |
+| Inner API | 系统部件 | 系统部件 | 不承诺 | 无 |
 
-本章程由API SIG制定，经PMC批准发布；本对章程的修订必须经由API SIG评审后，由PMC批准发布。 
-## API范围与定义
-应用程序接口(API)位于应用层和框架层之间，是由操作系统预定义的、由框架层和系统应用提供给应用(包括系统应用和三方应用)开发使用的类、方法等用户程序编程接口；不包括OEM扩展接口。
+各类型API说明如下：
 
-![](figures/API-Scope-And-Definition.png)
+* Public API：OpenHarmony对所有应用开发者公开的API。
+* Test API：测试专用的API，供开发者使用。
+* System API：提供给系统特权应用使用的API，普通应用无法使用。
+* HDI：描述硬件能力的接口。
+* Driver API：提供给驱动开发者使用的接口。
+* Inner API：系统服务和框架实现彼此调用的API，仅供系统内部使用，不承诺兼容性。
 
-OpenHarmony API按可授权使用方分类包括：
-- Public API：公开发布，提供给三方应用开发使用的API。
-- System API：非公开发布，仅授权平台签名应用（signature）、预置特权应用（privileged）使用的API。
-- Test API：受限发布，仅适用于xTS或应用调试阶段可使用的API。
-<p>如无特别说明，本章程定义的条款同时适用于Public API、System API或Test API等三种OpenHarmony API。针对System API和Test API的额外要求或例外说明，通过特别说明方式加以补充说明。</p>
+### API与编程语言
 
-OpenHarmony API按编程语言分类包括：
-- JS API：面向应用开放的JavaScript编程语言接口。
-- Native API：面向应用开放的C/C++编程语言接口。
-<p>如无特别说明，本章程定义的条款同时适用于JS API和Native API。</p>
+OpenHarmony的目标是构建面向万物互联时代的新一代操作系统，其实现涵盖但不限于以下编程语言：
+
+* C/C++
+* JavaScript
+* TypeScript
+
+本章程所描述的内容与编程语言无关。即：在不违反编程语言要求的情况下，API不分编程语言都要遵守章程的要求。
 
 ## API治理
 
@@ -33,24 +52,26 @@ OpenHarmony API按编程语言分类包括：
 | - | - |
 |Contributor|API的设计和交付主体，负责API相关的代码与设计文档提交。|
 |Committer|API相关的代码评审，涉及API提交预审。|
-|领域SIG|<p>新增API相关的代码提交评审，领域SIG评审通过即可合入。</p><p>变更API相关的代码提交预审。</p>|
+|领域SIG| 新增API相关的代码提交评审，领域SIG评审通过即可合入。<br/>变更API相关的代码提交预审。|
 |API SIG|变更API相关的代码提交评审。|
 |PMC|API Version计划发布、API治理章程修订评审发布等。|
 
 ### API评审流程
 API评审流程如下：
 
-![](figures/API-Review-Process.png)
+<img src="figures/API-Workflow.png" width="800" />
 
 主要过程说明：
-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：Contributor），所有涉及API新增或变更需同步提交相应的API评审文档，详细说明API的需求来源、场景与使用方法、权限设计、隐私保护澄清等，详见后面的API评审申请要素。为避免后续的返工，Contributor可以在正式的API评审申请、代码提交之前，先通过邮件方式将API设计文档提交Committer、领域SIG、API SIG等相关人员预审。
+1. 代码评审（Owner：Committer），代码评审和API预审，涉及API提交Code Review通过后，还需要进一步领域SIG评审。如果单次提交同时涉及多个领域的API新增或变更，相应的API评审申请和代码需要同时提交给相关领域的Committer评审，只有所有对应领域的Committer都完成CodeReview后才能进入下一评审环节。
 1. API评审（Owner：领域SIG），新增API相关的代码提交评审，领域SIG评审通过即可代码合入；变更API相关的代码提交，领域SIG评审通过后，还需要进一步提交API SIG。如果单次提交同时涉及多个领域的API新增，相应的API评审申请和代码需要同时提交给相关领域的SIG评审，只需一个领域SIG评审通过即可代码合入。如果单次提交同时涉及多个领域的API变更，相应的API评审申请和代码需要同时提交给相关领域的SIG评审，只有所有对应领域的SIG都要评审通过才能进入下一评审环节。
 1. API变更评审（Owner：API SIG），变更API相关的代码提交评审，评审通过即可代码。
 1. 评审完成。
 
 ### API评审申请要素
-如果涉及API新增或变更需同步提交相应的API设计文档。
+
+如果涉及API新增或变更需同步提交相应的API评审文档。API评审文档使用[《OpenHarmony API 评审模板》](API-Review-Template.md)描述。
 
 针对新增API，需要包含如下要素：
 1. 需求来源与使用场景（必须）。
@@ -67,6 +88,8 @@ API评审流程如下：
 3. 刷新ChangeLog（必须） 和 API-diff文档（涉及JS/Native API变更，必须）。
 
 ## API设计要求
+
+
 ### 一致性要求
 1. 概念一致性：基于场景的业务模型抽象，形成OpenHarmony的连贯、一致、自恰的用户程序模型和业务概念。
 1. 术语一致性：相应的业务术语必须采用统一名词，不允许使用多个语意接近的名词表示同一个业务对象；同样地，为了避免产生混淆，也不允许针对不同的业务对象使用相同的名词或语言接近的名词。
@@ -150,14 +173,33 @@ API评审流程如下：
        1. 提供可替代接口。
        1. 废弃API至少保留5个API Version版本（对废弃5个API Version的API可以彻底删除，不再支持）。
 
-### 性能/功耗/可靠性要求
+### 性能要求
 1. 应及时响应，避免调用者等待；如果API调用执行时间过长应设计为异步方式。
-1. 应关注API调用时机、调用频次对RAM占用的影响。
-1. 应关注API调用时机、调用频次对功耗的影响。
-1. API内部创建对象的生命周期要闭合，避免对象资源泄漏。
-1. 满足幂等性要求，相同业务含义的请求API调用一次或多次重试总能获得相同的效果（API调用依赖外部资源的变化除外）。针对可重入的API调用实现内部应尽量避免引入时变因素，如系统tick、静态变量、没有互斥保护的全局变量等；针对同一客户端的多次重复调用，可以使用contextID、clientToken、squenceNo等作为调用入参。
+2. 应关注API调用时机、调用频次对RAM占用的影响。
+3. 应关注API调用时机、调用频次对功耗的影响。
+4. 对使用资源的API调用需要能及时释放资源，异常场景具备容错机制，保障资源及时释放。
+
+### 功耗要求
+
+1. 针对API调用时机、调用频次对功耗的影响做评估，有影响进行相关设计。
+2. 版本演进过程中，功耗不劣化。
+
+### 可靠性要求
+
+1. API不能因为外部输入（输入参数、系统状态、外部数据等）或者内部状态、数据异常而崩溃，应该返回确定的错误码或者抛出预定义的异常。
+2. API应明确调用是同步还是异步调用，若是同步调用，应明确超时上限或者允许调用者设置超时时间，避免调用卡死导致业务无响应。
+3. API务必支持多线程重入。
+4. 满足幂等性要求，相同业务含义的请求API调用一次或多次重试总能获得相同的效果（API调用依赖外部资源的变化除外）。针对可重入的API调用实现内部应尽量避免引入时变因素，如系统tick、静态变量、没有互斥保护的全局变量等；针对同一客户端的多次重复调用，可以使用contextID、clientToken、squenceNo等作为调用入参。
+5. API内部创建对象的生命周期要闭合，避免对象资源泄漏。
+6. API要明确客户端调用失败后，能够发起重试的最大次数。
 
 ### 测试要求
 1. 新增API必须同步交付API自动化测试用例，用例100%覆盖API接口。
-1. 用例场景单一，单条用例覆盖接口单个功能场景，简化单条用例代码逻辑。
-1. 用例执行高效，每条用例执行时间控制在毫秒级。
+2. 用例场景单一，单条用例覆盖接口单个功能场景，简化单条用例代码逻辑。
+3. 用例执行高效，每条用例执行时间控制在毫秒级。
\ No newline at end of file
+4. 用例执行全自动化：接口用例需要达成100%自动化。
+5. 用例有效性：用户要求必须存在断言，且不能仅是检查是否抛出异常，需要有功能逻辑的断言。
+
+### 编程语言要求
+
+API根据其编程语言类型，需要遵守相应的OpenHarmony编程语言规范。