diff --git a/_sidebar.md b/_sidebar.md index fec99f9e7726e71a957874674e0757830bda2f15..c4b5fb63225fa9534266a9080258454e64d171ab 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -2,41 +2,36 @@ - 入门基础 - - [简介](zh-cn/README.md) - - [RN 基础](zh-cn/base.md) - - [RN 三方库](zh-cn/third-party.md) + - [简介](/zh-cn/README.md) + - [RN 基础](/zh-cn/base.md) + - [RN 三方库](/zh-cn/third-party.md) - 环境搭建 - - [搭建开发环境](zh-cn/environment.md) + - [搭建开发环境](/zh-cn/environment.md) - 新架构迁移指南 - - [新架构介绍](zh-cn/new-architecture.md) - - [TurboModules](zh-cn/turbomodule.md) - - [Fabric 组件](zh-cn/fabric.md) - - [迁移三方库到新架构](zh-cn/migration.md) + - [新架构介绍](/zh-cn/new-architecture.md) + - [TurboModules](/zh-cn/turbomodule.md) + - [Fabric 组件](/zh-cn/fabric.md) + - [迁移三方库到新架构](/zh-cn/migration.md) -- 鸿蒙原生侧代码 +- 开源管理 - - [C++ NAPI 层](zh-cn/cpp.md) - - [原生层](zh-cn/native.md) - -- 发布 - - - [三方库文件结构整改（补丁形式）](zh-cn/patch.md) - - [代码格式检查](zh-cn/codelint.md) - - [开源管理](zh-cn/open-source.md) - - [本地打包三方库](zh-cn/tgz.md) - - [发布三方库到 Github Packages](zh-cn/github-package.md) - - [发布三方库到 NPM 官方仓](zh-cn/npm.md) + - [版本控制](/zh-cn/version-control.md) + - [HarmonyOS RN三方库规范](/zh-cn/specification.md) + - [代码格式检查](/zh-cn/codelint.md) + - [本地打包三方库](/zh-cn/tgz.md) + - [发布三方库到 Github Packages](/zh-cn/github-package.md) + - [发布三方库到 NPM 官方仓](/zh-cn/npm.md) - checklist - - [发布 release checklist](zh-cn/repositories-release-checklist.md) - - [usage-docs checklist](zh-cn/usage-docs-checklist.md) + - [发布 release checklist](/zh-cn/repositories-release-checklist.md) + - [usage-docs checklist](/zh-cn/usage-docs-checklist.md) - 其他 - - [常见问题 Q&A](zh-cn/qa.md) - - [AutoLink](zh-cn/autolink.md) + - [常见问题 Q&A](/zh-cn/qa.md) + - [AutoLink](/zh-cn/autolink.md) diff --git a/img/branch_rules1.png b/img/branch_rules1.png new file mode 100644 index 0000000000000000000000000000000000000000..41d0c0f470c67f04552a1a2dce5a5b87aa982f68 Binary files /dev/null and b/img/branch_rules1.png differ diff --git a/img/branch_rules2.png b/img/branch_rules2.png new file mode 100644 index 0000000000000000000000000000000000000000..472d966724f5179a04f7b1b12ed6450cd2362100 Binary files /dev/null and b/img/branch_rules2.png differ diff --git a/img/grn.png b/img/grn.png new file mode 100644 index 0000000000000000000000000000000000000000..63d4f491c5f607ba397ca56fe83e5e4a0207fe08 Binary files /dev/null and b/img/grn.png differ diff --git a/zh-cn/patch.md b/zh-cn/specification.md similarity index 42% rename from zh-cn/patch.md rename to zh-cn/specification.md index e5ee450d265785f776d1a19370a1dc5fbd59832f..579cbd8f72e55f3741a445bd141573f83a66483a 100644 --- a/zh-cn/patch.md +++ b/zh-cn/specification.md @@ -1,34 +1,142 @@ > [!WARNING] 本文档为非公开文档，仅用于三方库使用和开发指导，不涉及任何 React Native OpenHarmony 框架的信息，且会随着 React Native OpenHarmony 框架持续迭代更新，当前版本不代表最终展示版本。 -# 三方库文件结构整改（补丁形式） +# HarmonyOS RN 三方库规范 ## 背景 -1130 前鸿蒙化后的 React-Native 三方库将 HarmonyOS 平台的修改和 Android、iOS 等平台的代码放在一起，然后覆盖原库安装。 +HarmonyOS React-Native 三方库（以下简称 RNOH 三方库）是 React-Native 社区三方库的 HarmonyOS 平台的延伸。目前不具备回合社区的条件，所以作为补丁包的形式存在。运行时需要同时依赖 react-native 和 react-native-harmony（react-native 的 HarmonyOS 补丁包），还有社区上的原三方库。 -这样做会面临三个问题： +目前所有的 RNOH 三方库的源码统一放在 Github 的 [react-native-oh-library](https://github.com/react-native-oh-library) 组织管理，请相关开发者先申请加入。 -1. Android 和 iOS 等其他平台需要依靠社区维护，有些库只支持老架构或只支持某个版本以下较老的 React-Native，而 HarmonyOS 只支持新架构和较新的 React-Native。如果放在一起无法保证一个库下，各个支持平台的一致性； +## 建仓规范 -2. 外部厂商希望 Android、iOS 和 HarmonyOS 能在同一 React-Native 工程项目内，不需要另外新建针对 HarmonyOS 平台的 React-Native 工程。而大部分外部厂商在 Android、iOS 平台用的还是老架构版本的三方库，对于一些我们适配了 HarmonyOS 平台的老架构三方库，我们既无法保证 Android、iOS 等其他平台能正常在新架构运行，也无法保证在老架构还能运行； +> [!tip] 如果没有建仓权限，请联系组织管理员帮忙操作。 -3. 在开源之后需要在 Gitee 建仓，很难跟进 Github 的社区版本更新，无法直接 fork 也无法提 PR，将其他平台的代码包含进来对回合社区无任何意义。 +首先确认需要移植的 React-Native 三方库的原始仓库地址，然后 fork 原库的默认分支（一般是 `master` 或 `main`）到 react-native-oh-library 组织。Description 的内容改为这个三方库在 NPM 上的包名。 -## 变更项及原理 +![create repo](../img/create_repo.png) -基于上述原因，经过各方面的考虑，1130 之后会对已适 HarmonyOS 平台的 React-Native 三方库进行文件结构整改，将覆盖原库的方式变更为打补丁的方式。 +点击 "View all branches" 修改分支名称为 `sig`，作为仓库的默认分支。开发时，请另外新建开发分支或 fork 该仓库。 -也就是说，将 HarmonyOS 平台的代码解耦出来，变成一个独立的 npm 包，和原来的 npm 包是依赖关系。当使用 metro 服务打包时，会根据平台和别名判断，需要去 node_modules 下哪个文件夹里取代码。 +![branch](../img/branch.png) -以 react-native-linear-gradient 为例，官方的 npm 包名是 react-native-linear-gradient，HarmonyOS 平台补丁的 npm 包名命名为 @react-native-oh-tpl/react-native-linear-gradient。 +将 sig 设置为保护分支，只能通过 Pull Request 的形式合入修改。PR 需写清楚合入的修改，后续会自动生成 Release 信息。 -#### Android/iOS +![branch_rules1](../img/branch_rules1.png) + +![branch_rules2](../img/branch_rules2.png) + +## 发布规范 + +发布步骤： + +1. 确保已通过自检测试，并完成代码格式检查； +2. 确保已将变更合入 `sig` 分支； +3. 发布新的 Tag 和 Release（github 上操作）； + +### 代码格式检查 + +请查看 [代码格式检查](zh-cn/codelint.md) 章节 + +### Tags and Releases + +按以下步骤操作： + +1. Tag 名称、Release 名称一致: + +> x.x.x-y.y.y + +具体的版本命名方式请阅读[版本控制](/zh-cn/version-control.md)章节。 + +2. Target 分支 选择默认分支 sig（请确保变更已通过测试、代码检查和合入了默认分支） + +3. Release 使用自动生成功能（生成内容如蓝框所示），然后手动额外添加版本信息（绿框内的内容）： + +```md +## Version Info + +- react-native-harmony: 0.72.x +- DevEco Studio: x.x.x +- HarmonyOS SDK: x.x.x +- ROM: xxx +``` + +4. 需要上传本地打包的 tgz 文件 + +![grn](../img/grn.png) + +> [!TIP] Generate release notes 功能会自动根据两个 Tag 之间的异同生成 Release 信息，历史 PR 信息会生成到 What's Changed 下。 + +### Package 的命名规则： + +**情况 1.** 如果原库在 NPM 上的包带有组织前缀，如 "@react-native-community/slider", "@react-native-async-storage/async-storage"等； + +去掉组织名取后半段： + +> "@react-native-oh-library/原包名后半段" // 私仓 + +> "@react-native-oh-tpl/原包名后半段" // 公仓 + +example： + +```md +// 私仓 +"@react-native-community/slider" → "@react-native-oh-library/slider" + +// 公仓 +"@shopify/flash-list" → "@react-native-oh-tpl/flash-list" +``` + +**情况 2.** 如果原库在 NPM 上的包没有组织前缀，如 "react-native-pager-view" 等； + +直接添加新的组织名： + +> "@react-native-oh-library/原包名" // 私仓 + +> "@react-native-oh-tpl/原包名" // 公仓 + +example： + +```md +// 私仓 +"react-native-translucent-modal" → "@react-native-oh-library/react-native-translucent-modal" + +// 公仓 +"react-native-pager-view" → "@react-native-oh-tpl/react-native-pager-view" +``` + +如果有重名等其他特殊情况，请联系组织管理员协商。 + +## 补丁形式说明 + +RNOH 三方库的文件结构和原库保持一致，遵循能不修改原库内容就不修改的原则，在此基础上进行鸿蒙化适配。 + +RNOH 三方库以原库补丁的形式发布（若原库需要鸿蒙化适配，部分库可以直接使用原库），开发者安装使用时需要安装原库和 HarmonyOS 补丁库，但开发时还是从同一个库名里导入模块。 + +也就是说，将 HarmonyOS 平台的代码解耦出来，变成一个独立的 npm 包，和原来的 npm 包是依赖关系。当使用 metro 服务打包时，会根据平台和别名判断，是去 node_modules 下哪个文件夹里读取模块。 + +以 react-native-linear-gradient 为例，官方的 npm 包名是 `react-native-linear-gradient`，HarmonyOS 平台补丁的 npm 包名命名为 `@react-native-oh-tpl/react-native-linear-gradient`。 + +**Android/iOS:** 当在 React-Native 项目内运行 Android 或 iOS 平台时，与正常引入该三方库没有区别，JS 端的代码和原生代码都会从 `node_modules/react-native-linear-gradient` 里查询。 -#### HarmonyOS +**HarmonyOS:** + +需要添加别名 + +在 `package.json` 里添加 "harmony" 字段： -@react-native-oh-tpl/react-native-linear-gradient 的 `package.json` 需要添加一个 `"harmony": {"alias"}` 字段，这个别名就是原库的名字，用于给 metro 识别打包 +```json +// 暂不配置 +{ + "harmony": { + "alias": {原NPM包名} + }, +} +``` + +例：@react-native-oh-tpl/react-native-linear-gradient 的 `package.json` 需要添加一个 `"harmony": {"alias"}` 字段，这个别名就是原库的名字，用于给 metro 识别打包 ```json ... @@ -47,7 +155,7 @@ import LinearGradient from "react-native-linear-gradient"; 这就实现了 HarmonyOS 平台和其他平台的解耦。HarmonyOS 平台因目前还不支持 Autolink，所以原生代码自行指定路径即可。 -## 示例 +### 示例 > [!tip] 补丁包的文件结构并没有太大变化，只是将 Android 和 ios 的原生部分、部分 JS 代码和一些无关项（example 工程等）剔除了，主要由两个部分组成：HarmonyOS 原生代码和修改后的 JS 代码。 @@ -55,47 +163,33 @@ import LinearGradient from "react-native-linear-gradient"; **对于 JS 代码：**仅保留有改动的部分，其余直接从原库里 import。 -首先需要在 github 仓库上新增 sig 分支（若不存在），作为补丁版本的分支。sig 分支的具体建立规则请参考 [开源管理](zh-cn/open-source.md) 章节 +首先需要在 github 仓库上新增 sig 分支（若不存在），作为补丁版本的分支。sig 分支的具体建立规则请参考 **建仓规范** -> [!WARNING] 目录结构还是需要和原库保持一致！ - -![sig branch](../img/sig_branch.png ":size=40%") +> [!WARNING] 目录结构需要和原库保持一致！ 我们要尽量遵循能少改就少改的原则，对于新架构的三方库，剔除了其他平台后，如果 JS 代码无改动，理论上只需要重新在 index 中重新导出即可。若有 harmony 平台的改动，则需要保留。 -> [!WARNING] 某些库的 `babel.config.json` 删除后会导致 bob build 报错，所以谨慎删除 - -如 react-native-linear-gradient - -改动前： - -![LG before](../img/LGbefore.png ":size=40%") - -改动后： - -![LG after](../img/LGafter.png ":size=40%") - 平台间的解耦不意味着 npm 包的解耦，实际上 JS 侧还需要依赖原库的代码。 所以还需要在 `package.json` 的 "dependencies" 字段添加对原库的依赖，版本填基于原库的版本。 ```json "dependencies": { - "react-native-linear-gradient": "3.0.0-alpha.1" + "react-native-linear-gradient": "x.x.x" }, ``` -其余的 `package.json` 配置不变，尽量和 `harmony` 分支保持一致。 - -> [!WARNING] 整改后需要在 `tester` 工程验证 +**可供参考的库：** -## 已整改完成可参考的库 - -| 原库名 | 源码地址 | +| 原库名 | 仓库地址 | | ------------------------------------- | --------------------------------------------------------------------------------------------------- | | react-native-linear-gradient | [OpenHarmony SIG](https://github.com/react-native-oh-library/react-native-linear-gradient/tree/sig) | | @react-native-community/slider | [OpenHarmony SIG](https://github.com/react-native-oh-library/react-native-slider/tree/sig) | | @react-native-picker/picker | [OpenHarmony SIG](https://github.com/react-native-oh-library/picker/tree/sig) | -| react-native-gesture-handler | [OpenHarmony SIG](https://github.com/react-native-oh-library/react-native-gesture-handler/tree/sig) | +| react-native-pager-view | [OpenHarmony SIG](https://github.com/react-native-oh-library/react-native-pager-view/tree/sig) | | @react-native-masked-view/masked-view | [OpenHarmony SIG](https://github.com/react-native-oh-library/masked-view/tree/sig) | | react-native-fast-image | [OpenHarmony SIG](https://github.com/react-native-oh-library/react-native-fast-image/tree/sig) | + +## 版本管理规范 + +请阅读[版本控制](/zh-cn/version-control.md)章节。 diff --git a/zh-cn/version-control.md b/zh-cn/version-control.md new file mode 100644 index 0000000000000000000000000000000000000000..db54dd6b1166cddcb47d898ad51f3980d35fc6c3 --- /dev/null +++ b/zh-cn/version-control.md @@ -0,0 +1,25 @@ +> [!WARNING] 本文档为非公开文档，仅用于三方库使用和开发指导，不涉及任何 React Native OpenHarmony 框架的信息，且会随着 React Native OpenHarmony 框架持续迭代更新，当前版本不代表最终展示版本。 + +# 版本控制 + +## 语义化版本控制规范（SemVer） + +版本号需要严格按照 SemVer 规范，请先阅读 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/) + +## HarmonyOS React-Native 三方库版本控制规范 + +> 语义化版本控制规范第9条：先行版本号可以（MAY）被标注在修订版之后，先加上一个连接号再加上一连串以句点分隔的标识符来修饰。标识符必须（MUST）由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止（MUST NOT）留白。数字型的标识符禁止（MUST NOT）在前方补零。先行版的优先级低于相关联的标准版本。被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。范例：1.0.0-alpha、1.0.0-alpha.1、1.0.0-0.3.7、1.0.0-x.7.z.92。 + +我们采用 **x.x.x-y.y.y** 的形式： + +其中 x.x.x 为原库基版本，即基于原库哪一个版本；y.y.y 为 HamronyOS 版本自身管控的版本号。 + +版本格式：主版本号.次版本号.修订号，版本号递增规则如下： + +- 主版本号：当你做了不兼容的 API 修改， +- 次版本号：当你做了向下兼容的功能性新增， +- 修订号：当你做了向下兼容的问题修正。 +- 先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸。 + +> [!TIP] 一般来说，原库基版本号不做变更，除非同步了原库默认分支的更新并且原库升级了新版本号 +