diff --git a/zh-cn/contribute/template/README-template.md b/zh-cn/contribute/template/README-template.md new file mode 100644 index 0000000000000000000000000000000000000000..8579a44e52e156f0d32e40bdfe9a712df5bf1f83 --- /dev/null +++ b/zh-cn/contribute/template/README-template.md @@ -0,0 +1,162 @@ +# 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 diff --git a/zh-cn/contribute/template/figures/figure01.png b/zh-cn/contribute/template/figures/figure01.png new file mode 100644 index 0000000000000000000000000000000000000000..62e5ec7c6248ed9219503c85b076dc9a22da6c78 Binary files /dev/null and b/zh-cn/contribute/template/figures/figure01.png differ diff --git a/zh-cn/contribute/template/figures/figure02.png b/zh-cn/contribute/template/figures/figure02.png new file mode 100644 index 0000000000000000000000000000000000000000..37b1f5215e362c156ca5de27145c3711cc14083b Binary files /dev/null and b/zh-cn/contribute/template/figures/figure02.png differ diff --git a/zh-cn/contribute/template/xxboard-template.md b/zh-cn/contribute/template/xxboard-template.md new file mode 100644 index 0000000000000000000000000000000000000000..24021f3f4c0ace12660d789450ae45a34e690ec0 --- /dev/null +++ b/zh-cn/contribute/template/xxboard-template.md @@ -0,0 +1,82 @@ +# 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、官网等内容链接。* + +## 感谢(可选) + +*【写作说明】致谢做出突出贡献的三方开发者。* + diff --git a/zh-cn/release-notes/OpenHarmony-v3.1-beta1.md b/zh-cn/release-notes/OpenHarmony-v3.1-beta1.md new file mode 100644 index 0000000000000000000000000000000000000000..609e53616439332edcf282ae7d3753e944c70d07 --- /dev/null +++ b/zh-cn/release-notes/OpenHarmony-v3.1-beta1.md @@ -0,0 +1,167 @@ +# OpenHarmony 3.1 Beta1 (Working draft) + +- [版本概述](#版本概述) +- [配套关系](#配套关系) +- [源码获取](#源码获取) +- [更新说明](#更新说明) + - [特性变更](#特性变更) + - [API变更](#api变更) + - [芯片及开发板适配](#芯片及开发板适配) + - [Samples & Codelabs](#Samples & Codelabs) +- [修复缺陷列表](#修复缺陷列表) +- [遗留缺陷列表](#遗留缺陷列表) + +## 版本概述 + +当前版本在OpenHarmony 3.0 LTS的基础上,更新了部分特性。 + + +## 配套关系 + +**表1** 版本软件和工具配套关系 + +| 软件 | 版本 | 备注 | +| -------- | -------- | -------- | +| OpenHarmony | 3.1 Beta1 | NA | +| SDK | | | +| HUAWEI DevEco Studio(可选) | 3.0 Beta2 | OpenHarmony应用开发推荐使用。 | +| HUAWEI DevEco Device Tool(可选) | 3.0 Beta2 | OpenHarmony智能设备集成开发环境推荐使用。 | + + +## 源码获取 + + +### 通过repo获取 + +**方式** **一(推荐)** + +通过repo + ssh 下载(需注册公钥,请参考[码云帮助中心](https://gitee.com/help/articles/4191))。 + +``` + +``` + +**方式二** + +通过repo + https 下载。 + +``` + +``` + +### 从镜像站点获取 + +**表2** 获取源码路径 + +| 版本源码** | **版本信息** | **下载站点** | **SHA256校验码** | +| -------- | -------- | -------- | -------- | +| | | | | +| | | | | + +## 兼容性说明 + +| 要求项 | 要求内容 | 是否满足 | +| ------ | -------- | -------- | +| | | | +| | | | + +## 更新说明 + +本版本在OpenHarmony 3.0 LTS的基础上有如下变更。 + + +### 特性变更 + +**表3** 版本新增特性表 + +| 子系统名称 | 标准系统 | 轻量、小型系统 | +| -------- | -------- | -------- | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | +| | | | + + +### API变更 + +API变更请参考:[JS API 差异报告]() + + +### 芯片及开发板适配 + +芯片及开发板适配状态请参考[SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig-devboard/sig_devboard_cn.md)信息。 + +### Samples & Codelabs + +#### Samples + + + +#### Codelabs + + + + +## 修复缺陷列表 + +**表4** 轻量和小型系统解决的缺陷ISSUE列表 + +| ISSUE单号 | 问题描述 | +| -------- | -------- | +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | + +**表5** 标准系统解决的缺陷ISSUE列表 + +| ISSUE单号 | 问题描述 | +| -------- | -------- | +| | | +| | | +| | | +| | | +| | | +| | | +| | | + + +## 遗留缺陷列表 + +**表6** 遗留缺陷列表 + +| ISSUE | 问题描述 | 影响 | 计划解决日期 | +| -------- | -------- | -------- | -------- | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | 日 | diff --git a/zh-cn/release-notes/api-change/v3.1-beta1/changelog-v3.1-beta1.md b/zh-cn/release-notes/api-change/v3.1-beta1/changelog-v3.1-beta1.md new file mode 100644 index 0000000000000000000000000000000000000000..9c2c4762cfb22e8f568848b983789e1267503adc --- /dev/null +++ b/zh-cn/release-notes/api-change/v3.1-beta1/changelog-v3.1-beta1.md @@ -0,0 +1,30 @@ +# ChangeLog (Working draft) +## xxx子系统(该段落为示例,请不要修改或删除) +已经release的版本发生了影响契约兼容性(契约兼容:也称语义兼容,指版本演进后,开发者原有程序行为不发生变化)的变更(包括不限于接口名、参数、返回值、所需要的权限、调用顺序、枚举值、配置参数、路径等),则需要在ChangeLog中对变更进行阐述。 +### cl.subsystemname.x xxx功能变更, 例:DeviceType属性变更、相机权限变更(尽量概括,不要超过15个字) +每个变更标题前需要附加编号:cl.subsystemname.x。cl为ChangeLog首字母缩写,subsystemname请填写子系统英文标准名称,x表示变更序号(从低到高逐位增加)。 +以功能维度对变更点进行概括描述。例如:xxx功能的xxx、xxx等发生了xxx变化,开发者需要根据以下说明对应用进行适配。 +如果有此变更有对应的需求或设计文档,可以在描述中附上对应的设计文档编号。 + +**变更影响** + +是否影响已release的接口或者接口行为发生变更等;影响的是JS接口、Java接口还是Native接口。 + +**关键的接口/组件变更** + +列举此功能变更涉及的接口/组件变更。 + +**适配指导(可选,不涉及则可以删除)** + +(前面空一行)提供指导,帮助开发者针对相关变更进行适配,使应用可以与新版本兼容。例: +在xxx文件中将xxx参数修改为xxx。 +``` +sample code +``` +### cl.subsystemname.x xxx功能变更 +每个功能变更点在自己的子系统章节内新增一个功能变更章节。 + +## xxx子系统 +每个子系统有且只能有一个子系统章节。 + + diff --git a/zh-cn/release-notes/api-change/v3.1-beta1/js-apidiff-v3.1-beta1.md b/zh-cn/release-notes/api-change/v3.1-beta1/js-apidiff-v3.1-beta1.md new file mode 100644 index 0000000000000000000000000000000000000000..0c17a1a5f90baf8c2595d8a51e3808b73cfd59c8 --- /dev/null +++ b/zh-cn/release-notes/api-change/v3.1-beta1/js-apidiff-v3.1-beta1.md @@ -0,0 +1,18 @@ +# JS API 差异报告 (Working draft) + +OpenHarmony 3.1 Beta1相较于OpenHarmony 3.0 LTS版本的API变更如下: + +## 标准系统接口变更 + +## 组件 + +| 组件类型 | 组件名称 | 变更类型 | 变更类型 | +| -------- | -------- | -------- | -------- | +| 描述组件的类型,例如:容器组件、基础组件、媒体组件等 | 描述组件名称,例如:div、button等 | 描述变更的类型,包含新增、删除、废弃、修改 | 如果为废弃,则需要描述替换的组件;如果为修改,则需要描述变化点,例如:新增xxx参数、xxx参数的默认值由xxx变更为xxx;其他情况可以使用 - 符号 | + +## 接口变更 + +| 模块名称 | 接口名称 | 变更类型 | 变更说明 | +| -------- | -------- | -------- | -------- | +| 描述接口所属的模块,例如:数据存储、文件存储等 | 描述接口名称,例如:storage.get(OBJECT)。如果整个模块新增,则可以使用 - 符号 | 描述变更的类型,包含新增、删除、废弃、修改 | 如果为废弃,则需要描述替换的接口;如果为修改,则需要描述变化点,例如:新增xxx参数、xxx参数的默认值由xxx变更为xxx;其他情况可以使用 - 符号 | + diff --git a/zh-cn/release-notes/api-change/v3.1-beta1/native-apidiff-v3.1-beta1.md b/zh-cn/release-notes/api-change/v3.1-beta1/native-apidiff-v3.1-beta1.md new file mode 100644 index 0000000000000000000000000000000000000000..5327f29d143a217de5cc8ed6c46da4be4bfa0c79 --- /dev/null +++ b/zh-cn/release-notes/api-change/v3.1-beta1/native-apidiff-v3.1-beta1.md @@ -0,0 +1,7 @@ +# Native API 差异报告 (Working draft) + +OpenHarmony 3.1 Beta1相较于OpenHarmony 3.0 LTS版本的API变更如下: + +| 模块名称 | 接口名称 | 变更类型 | 变更类型 | +| -------- | -------- | -------- | -------- | +| 描述模块的名称,例如:Native_layer、Image、Media等 | 描述变更元素的名称,包含结构体、类型定义、枚举、函数等,例如:结构体NativeLayerBuffer、类型定义NativeLayer、函数GetNativeLayer (JNIEnv *env, jobject surface)等。如果整个模块新增,则可以使用 - 符号 | 描述变更的类型,包含新增、删除、废弃、修改 | 如果为废弃,则需要描述替换的组件;如果为修改,则需要描述变化点,例如:新增xxx参数、xxx参数的默认值由xxx变更为xxx;其他情况可以使用 - 符号 | \ No newline at end of file