!1084 3.1 Beta Release Notes

Merge pull request !1084 from NEEN/master

zh-cn/contribute/template/README-template.md

+# xxx子系统/组件
+
+- [简介](#简介)
+- [目录](#目录)
+- [约束](#约束)
+- [编译构建](#编译构建)
+- [说明](#说明)
+    - [接口说明](#接口说明)
+    - [使用说明](#使用说明)
+- [Changelog](#changelog)
+- [相关仓](#相关仓)
+
+【标题说明】根据当前Readme的类型，使用 **子系统**或者 **组件**。
+
+
+![子系统readme](figures/figure01.png)
+
+
+## 简介
+
+
+【写作要求】 必选**，简介中包含2部分内容： **内容介绍、架构图介绍。
+
+**内容介绍：**从以下几个方面介绍该子系统：出现背景（在整个OpenHarmony架构中的作用）、实现的功能、使用场景、支持的设备等。
+
+**架构图：**使用架构图说明该子系统【组件】架构，对架构中的主要组成部分进行必要的解释说明
+
+**如果本组件仓库只是子系统一部分，需要理解子系统相关概念，建议给出：**
+
+**更多XXX子系统相关概念，请参考：xxx。(给出到子系统readme的链接)**
+
+
+写作注意事项如下：
+
+
+| 要求项 | 内容要求 |
+| -------- | -------- |
+| **A.1** | **用语要求** |
+| A.1.1 | 行文风格：用语正式，避免口语化。 |
+| A.1.2 | 合规要求：不能使用第三方知识产权特有概念等存在合规和法务风险的词汇。 |
+| A.1.3 | 内容简洁：内容采用信息必备、最小化原则，旨在指导开发者在尽量短的时间完成操作。 |
+| A.1.4 | 内容正确：文档的代码、需要设置的参数等需要跟产品实际情况实时保持一致。 |
+| A.1.5 | 用语准确：应当确切，不能出现多义性的描述。 |
+| A.1.6 | 用语一致：同一叫法，全文保持一致，术语与术语库保持一致，正文中缩略语首次出现要给出全称。 |
+| A.1.7 | 用语具体：如表示数量或程度时，避免用笼统的“多”“少”“大”，建议用具体数字表示。 |
+| **A.2** | **格式要求** |
+| A.2.1 | 标点符号正确、句尾有符号结尾。 |
+| A.2.2 | 内容尽量用项目列表或分类的方式清晰呈现。不要有单个项目列表；不要有多余空行。 |
+| A.2.3 | 英文字母和中文字之间不要有空格。 |
+| A.2.4 | 链接必须有效，具体，可直接跳转或下载。Gitee内部建议使用相对链接，避免使用绝对链接。 |
+| A.2.5 | 如果是内容的辅助说明，请使用“说明”式样；如果提前申明事项，请使用“须知”式样，不用“注意”格式 |
+| **A.3** | **表格** |
+| A.3.1 | 表格有表注，表头风格一致，采用名词或名词词组形式。 |
+| A.3.2 | 表格有表头，至少为2行2列，避免出现单行或单列表。 |
+| A.3.3 | 表格无内容用“_”，不出现空白的单元格。 |
+| **A.4** | **图形** |
+| A.4.2 | 避免涉及宗教信仰类截图。 |
+| A.4.3 | 图文并茂，行文应力求简明，如有可能，配以适当的图，表。 |
+| A.4.4 | 图形有图注（不可直接粘贴图形），图注风格一致，采用名词或名词词组形式。 |
+| A.4.5 | 图形应清晰可辩识，信息表达完整，易于阅读。如流程图不可缺少“开始”和“结束”。 |
+| A.4.6 | 图形逻辑清晰，图文配合使用，切忌图文分离。 |
+| A.4.7 | 图片的高度建议在640px左右，宽度不超过820px，一般为.png格式，图片的大小建议不超过150k。 |
+| A.4.8 | 图形建议尽量不要用文字，中文图用中文，英文图用英文。 |
+
+
+架构图参考如下，注意需要绘图的 **颜色，格式有规范要求**，请参照：
+
+**图1** 子系统架构图
+![架构图](figures/figure02.png)
+
+
+
+## 目录
+
+【写作要求】 必选**，明确本项目仓的代码 **目录结构**以及对应目录的 **功能描述
+
+```undefined
+/foundation/ace
+├── frameworks         # 框架代码
+│   └── lite
+│       ├── examples  # 示例代码目录
+│       ├── include   # 对外暴露头文件存放目录
+│       ├── packages  # 框架JS实现存放目录
+│       ├── src       # 源代码存放目录
+│       ├── targets   # 各目标设备配置文件存放目录
+│       └── tools     # 工具代码存放目录
+├── interfaces         # 对外接口存放目录
+│   └── innerkits     # 对内部子系统暴露的头文件存放目录
+│       └── builtin   # JS应用框架对外暴露JS三方module API接口存放目录
+```
+
+
+
+## 约束
+
+【写作要求】  **可选**，明确项目运行的特定条件，如特定的编程语言或特定的操作系统的特定版本。
+
+| 要求项 | 内容要求 |
+| -------- | -------- |
+| D.1.1 | 明确功能限制或操作限制。 |
+| D.1.2 | 约束对指导任务开发有影响或体验有感知，否则不用体现。 |
+| D.1.3 | 容易出错的操作在步骤里描述，不在此体现。 |
+
+
+## 编译构建/使用方法
+
+【写作要求】 可选，子系统Readme不需要提供，对于组件仓的Readme，根据实际情况，提供编译构建的说明。
+
+
+## 说明
+
+
+### 接口说明
+
+【写作要求】 **可选**，描述本开发指导相关的接口有哪些，旨在要开发者在开发前有大体了解，提升开发效率。 **子系统readme无需提供**，仓库的readme根据需要判断是否提供，如果已经有API接口参考无需提供；写作要求见下：
+
+| 要求项 | 内容要求 |
+| -------- | -------- |
+| J.1.1 | 不在本开发任务的接口无需提供。 |
+| J.1.2 | 如果接口太多，可以提供主要的接口 |
+
+
+### 使用说明
+
+【写作要求】  **可选**， *子系统Readme中偏向于概念介绍；仓Readme偏向于具体功能介绍*；如果已经提供开发指南可直接链接到对应指南，无需再写使用说明。
+
+写作要求见下，完成写作后，请逐项自检。
+
+| 要求项 | 内容要求 |
+| -------- | -------- |
+| **F.1** | **如何写好步骤** |
+| F.1.1 | 步骤完整：提供必须的步骤，顺利指导完成操作，无缺失。 |
+| F.1.2 | 脉络清楚：文档逻辑清晰、合理。文档前面的概述、准备、操作围绕一条线描述，不能章节断裂或前后矛盾的现象。 |
+| F.1.3 | 任务句式：标题或句子尽量使用“动词+名词”的句式表述动作。 |
+| F.1.4 | 预防提前：操作过程中的限制、易错的、有潜在风险的，要提前描述。 |
+| F.1.5 | 步骤清晰-1：无论步骤简单或复杂，都需要写步骤目的，即为什么做。 |
+| F.1.6 | 步骤清晰-2：明确在什么环境下，使用什么工具，做什么操作，怎么做该操作。 |
+| F.1.7 | 步骤具体：如果操作可选，要明确可选条件。 |
+| F.1.8 | 在开发步骤执行完成后，及时明确操作正确的标准。 |
+| **F.2** | **如何写好代码段** |
+| F.2.1 | 代码涉及开发者拷贝的命令，必须用可编辑的报文呈现，避免截图，使用代码片段包裹样式 |
+| F.2.2 | 代码中关键段，关键步骤要有注释说明。 |
+| F.2.3 | 代码显示符合代码缩进要求。 |
+| F.2.4 | 步骤涉及接口调用，清晰给出接口及其使用说明或示例代码，代码来源于具体实例。 |
+
+
+## Changelog
+
+【写作要求】  **可选**，当此readme所在的仓，在做版本升级或其他调整时，需要在changelog中维护变化信息【本次开源中，如果涉及升级更新的，需要提供】
+
+
+## 相关仓
+
+【写作要求】  **必选**。列出当前仓所在子系统的所有相关仓的链接，并加粗标识当前的仓
+
+[xxx子系统](https://gitee.com/openharmony)
+
+[组件1](https://gitee.com/openharmony)
+
+**[组件2](https://gitee.com/openharmony)**
+
+[组件3](https://gitee.com/openharmony)
\ No newline at end of file

zh-cn/contribute/template/xxboard-template.md

+# XXX开发板名称
+*本模板定位：OpenHarmony生态引入第三方开发板时，第三方开发板厂商需提供开发板介绍，便于开发者快速了解此开发板。*
+
+## 介绍
+
+【写作说明】
+
+*文字描述开发板的功能，面向场景，主要支持的特性能力。*
+
+*提供开发板外观图片。*
+
+*底板图片。*
+
+*功能框图及介绍。*
+
+**图片名称以开发板名称命名。*
+
+*参考文档：https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/quick-start/oem_minitinier_des_3861.md*
+
+********
+## 开发板规格
+
+*【写作说明】提供开发板模组规格清单，硬件规格列表。*
+
+## 约束和限制（可选）
+
+*【写作说明】如果开发板在某些功能、特性、规格等使用上，有一定的约束和建议，需要明确说明。*
+
+********
+
+
+## 关键特性
+*【写作说明】支持的OpenHarmony关键特性列表。*
+
+## 引脚定义
+*【写作说明】介绍单板的管脚定义等，描述单板I/O引脚，PIN，以及如何配置PIN、如何使用PIN连接外部组件。*  
+
+## 搭建开发环境
+
+### 系统要求
+
+*【写作说明】描述开发板对OpenHarmony系统依赖、软、硬件环境系统依赖。*
+
+### 工具要求
+
+*【写作说明】提供从哪里下载开发板编译调试工具链。*
+
+### 搭建过程
+
+*【写作说明】Step by Step介绍环境搭建详细步骤。*
+
+## 编译调试
+
+### 编译
+
+*【写作说明】如何在此开发板上使用OpenHarmony，以及如何在此单板上刷新OpenHarmony二进制文件及设备。*
+
+### 烧录
+
+*【写作说明】Step by Step介绍如何烧录参考步骤。*
+
+### 运行
+
+*【写作说明】如何判断开发板正常点亮、运行、输出正常。*
+
+
+### 调试
+
+*【写作说明】如何调试开发板常见报错等。*
+
+## 首个示例
+
+*【写作说明】基于此开发板给出一个快速上手的示例，运行效果，或者给出demo示例源码链接。*
+
+## 参考资源
+
+*【写作说明】给出更多详细参考文档、sample示例、FAQ、官网等内容链接。*
+
+## 感谢（可选）
+
+*【写作说明】致谢做出突出贡献的三方开发者。*
+

zh-cn/release-notes/Readme.md

 # OpenHarmony Release Notes
 ## OpenHarmony 3.x Releases
+[OpenHarmony v3.1 Beta(2021-12-31)](OpenHarmony-v3.1-beta.md)
+
 [OpenHarmony v3.0 LTS (2021-09-30)](OpenHarmony-v3.0-LTS.md)
 
 ## OpenHarmony 2.x Releases

zh-cn/release-notes/api-change/v3.1-beta/changelog-v3.1-beta.md

+# ChangeLog
+##### 关键的接口/组件变更
+## 进程间通信子系统
+#### cl.rpc.1 sendRequest返回值类型变更
+
+##### 变更影响
+
+js的RemoteProxy和RemoteObject的sendRequest变更为异步接口，返回Promise，兑现值是SendRequestResult的实例。原有应用需要适配。
+
+##### 关键的接口/组件变更
+
+```
+模块：ohos.rpc.IRemoteObject, ohos.rpc.RemoteProxy和ohos.rpc.RemoteObject
+接口：sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): boolean
+
+变更后接口：
+sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): Promise<SendRequestResult>
+```
+
+**适配指导**
+
+```
+import rpc from "@ohos.rpc"
+
+let option = new rpc.MessageOption()
+let data = rpc.MessageParcel.create()
+let reply = rpc.MessageParcel.create()
+proxy.sendRequest(1, data, reply, option)
+	.then(function(result) {  
+		console.info("send request done")
+		if (result.errCode === 0) {
+			// read result from result.reply
+		}
+	})
+	.catch(function(e) {
+		console.error("send request failed: " + e)
+	})
+	.finally(() => {
+		data.reclaim()
+		reply.reclaim()
+	})
+```
+

zh-cn/release-notes/api-change/v3.1-beta/native-apidiff-v3.1-beta.md

+# Native API 差异报告
+
+OpenHarmony 3.1 Beta相较于OpenHarmony 3.0 LTS版本的API变更如下:
+
+## 标准系统接口变更
+
+| 模块名称           | 接口名称                                                     | 变更类型 | 变更类型                                          |
+| ------------------ | ------------------------------------------------------------ | -------- | ------------------------------------------------- |
+| bundle             | napi_value ClearBundleCache(napi_env env, napi_callback_info info) | 新增     | 新增清理应用缓存接口                              |
+| bundle             | napi_value SetApplicationEnabled(napi_env env, napi_callback_info info) | 新增     | 新增设置应用使能接口                              |
+| bundle             | napi_value SetAbilityEnabled(napi_env env, napi_callback_info info) | 新增     | 新增设置ability使能接口                           |
+| innerbundlemanager | napi_value JSGetLauncherAbilityInfos(napi_env env, napi_callback_info info) | 新增     | 新增通过包名获取应用LauncherAbility接口           |
+| innerbundlemanager | napi_value JSLauncherServiceOn(napi_env env, napi_callback_info info) | 新增     | 新增注册监听包状态变化接口                        |
+| innerbundlemanager | napi_value JSLauncherServiceOff(napi_env env, napi_callback_info info) | 新增     | 新增注销监听包状态变化接口                        |
+| innerbundlemanager | napi_value JSGetAllLauncherAbilityInfos(napi_env env, napi_callback_info info) | 新增     | 新增通过userId获取所有launcher上应用的ability接口 |
+| innerbundlemanager | napi_value JSGetShortcutInfos(napi_env env, napi_callback_info info) | 新增     | 新增通过bundleName获取应用的shortcutInfo接口      |
\ No newline at end of file