提交 a6009566 编写于 作者: O openharmony_ci 提交者: Gitee

!265 API治理章程刷新

Merge pull request !265 from zhangyongzhi/master
......@@ -8,7 +8,7 @@
为了引导OpenHarmony应用生态健康、有序发展演进,本章程对OpenHarmony API的新增、变更、废弃、删除等生命周期与治理流程进行约束,同时定义了基本的API设计要求。
本章程由PMC批准发布,本对章程的修订必须经由PMC评审与批准发布。
本章程由API SIG制定,经PMC批准发布;本对章程的修订必须经由API SIG评审后,由PMC批准发布。
## API范围与定义
应用程序接口(API)位于应用层和框架层之间,是由操作系统预定义的、由框架层和系统应用提供给应用(包括系统应用和三方应用)开发使用的类、方法等用户程序编程接口;不包括OEM扩展接口。
......@@ -23,7 +23,7 @@ OpenHarmony API按使用方分类包括:
OpenHarmony API按编程语言分类包括:
- Java API:面向应用开放的Java编程语言接口。
- JS API:面向应用开放的JavaScript编程语言接口。
- JS API:面向应用开放的JavaScript编程语言接口。
- Native API:面向应用开放的C/C++编程语言接口。
## API治理
......@@ -32,10 +32,10 @@ OpenHarmony API按编程语言分类包括:
|**涉及角色**|**API治理中的职责**|
| - | - |
|Contributor|API的设计和交付主体,负责API相关的代码与设计文档提交。|
|Committer|API相关的代码提交预审,Review+1。|
|Maintainer|<p>新增API相关的代码提交评审,Review+2。</p><p>变更API相关的代码提交预审,Review+1</p>|
|SIG|变更API相关的代码提交评审,Review+2。|
|PMC|API Version计划发布、API治理章程修订等。|
|Committer|API相关的代码评审,涉及API提交预审。|
|领域SIG|<p>新增API相关的代码提交评审,领域SIG评审通过即可合入。</p><p>变更API相关的代码提交预审</p>|
|API SIG|变更API相关的代码提交评审。|
|PMC|API Version计划发布、API治理章程修订评审发布等。|
### API评审流程
API评审流程如下:
......@@ -44,21 +44,22 @@ API评审流程如下:
主要过程说明:
1. API评审申请、代码提交(Owner:Contributor),除代码提交外,如果涉及API新增或变更需同步提交相应的API设计文档,详细说明API的需求来源、场景与使用方法、权限设计、隐私保护澄清等,详见后面的API评审申请要素。为避免后续的返工,Contributor可以在正式的API评审申请、代码提交之前,先通过邮件方式将API设计文档提交Committer、Maintainer等相关人员预审。
1. 代码评审(Owner:Committer),涉及API提交的预审,预审通过Review+1。如果一次提交同时涉及多个领域的API新增或变更,相应的API评审申请和代码需要同时提交给相关领域的Commiter评审,只有所有对应领域的Committer都要Review+1才能进入下一评审环节。
1. API评审(Owner:Maintainer),新增API相关的代码提交评审,评审通过Review+2;变更API相关的代码提交预审,预审通过Review+1。如果一次提交同时涉及多个领域的API新增,相应的API评审申请和代码需要同时提交给相关领域的Maintainer评审,只需一个领域Maintainer评审Review+2即可代码合入。如果一次提交同时涉及多个领域的API变更,相应的API评审申请和代码需要同时提交给相关领域的Maintainer评审,只有所有对应领域的Maintainer都要Review+1才能进入下一评审环节。
1. API变更评审(Owner:SIG),变更API相关的代码提交评审,评审通过Review+2。如果一次提交同时涉及多个领域的API变更,建议在主要修改涉及领域的SIG进行评审
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都要评审通过才能进入下一评审环节。
1. API变更评审(Owner:SIG),变更API相关的代码提交评审,评审通过即可代码
1. 评审完成。
### API评审申请要素
如果涉及API新增或变更需同步提交相应的API设计文档,建议包含如下要素:
1. 需求来源与使用场景(必须)
1. API现状与差距分析,说明API新增或变更的必要性(必须)
1. API原型设计与使用方法说明(必须);必要时,可以进一步包含相应的使用样例(可选)
1. API权限设计(必须)
1. 需求来源与使用场景(必须)
1. API现状与差距分析,说明API新增或变更的必要性(必须)
1. API原型设计与使用方法说明(必须);必要时,可以进一步包含相应的使用样例(可选)
1. API权限设计(必须)
1. API隐私保护方案与要求满足情况澄清(必须);
1. 针对老接口的处理方式和相应的应用兼容措施(可选,如果涉及API变更,则必须包含);
1. 提交代码的同时提交相应的API参考(必须);必要时,可同步提交相应的开发者指南文档(可选)。
1. 针对老接口的处理方式(废弃、隐藏或彻底删除)、替代接口和相应的应用兼容措施(可选,如果涉及API变更,则必须包含)。
1. 兼容性/性能/功耗/可靠性/测试等相关情况说明(可选,如不满足本章程 “4 API设计要求”,则必须包含相关说明)。
## API设计要求
......@@ -84,6 +85,16 @@ API评审流程如下:
1. 词义清晰明了,避免使用info,data,object等一般意义的词。
1. 作用域越大,命名应越精确。
1. 不用或少用缩写,业界通用术语遵从行业习惯允许使用缩写。
1. 包名/模块名/命名空间前缀约定:
1. Java API 统一包名: package ohos.\*
2. JS API 统一模块名:@system.\*
3. Native API 统一命名空间:namespace OHOS.\*
4. 引用外部开源代码的,可以保留原包名/模块名/命名空间,也可以按照上述规则统一进行替换。
7. 包名/模块名/命名空间最短不少于2段,最长不超过4段;每一段建议使用一个单词,最长不超过2个单词。
8. 类名、方法名/函数名、成员变量、变量名最多不超过4个单词。
### 权限控制要求
1. 完备性原则:一切穿透应用沙箱的行为都需考虑使用权限来管控。
......@@ -114,18 +125,28 @@ API评审流程如下:
1. 源码兼容:指版本演进后,开发者已有的源代码可正常编译通过。
1. 二进制兼容:指版本演进后,开发者已有程序不用重新编译可正常链接、运行。
1. 契约兼容:也称语义兼容,指版本演进后,开发者原有程序行为不发生变化。
1. OpenHarmony API后向兼容必须满足二进制兼容要求,常见破坏二进制兼容的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,需要遵守对外部开发者的“契约承诺”,原则上不允许对已经发布的API进行不兼容修改,受限允许对已发布的API进行废弃。已发布API废弃基本要求包括:
1. 废弃接口标记。
1. 提供可替代接口。
1. 废弃API至少保留5个API Version版本(对废弃5个API Version的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. 应及时响应,避免调用者等待;如果API调用执行时间过长应设计为异步方式。
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册