0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
Ggyangedocs(Docs): optimize the docs structure
eec718bb创建于 4月22日历史提交

开发者代码提交操作指南

本指南基于社区《社区 Changelog 规范》《社区 Commit 和 PR 规范》《仓库分支管理规范》编写，旨在规范开发者代码提交全流程，确保提交内容合规、可追溯、易协作，降低社区维护成本，同时实现 Commit、PR 与 Changelog 的联动统一。适用于所有参与社区项目开发、提交代码的开发者。

main分支为版本持续演进分支，会根据 React Native 版本的演进，持续更新 RNOH 框架的适配版本。历史版本的适配在特性分支上进行。可参考RNOH版本演进规划和分支策略。 。

一、开发环境搭建与启动

在参与 RNOH 框架开发前，需先完成开发环境的搭建。

1. 前置条件

序号 条件 说明
1 HarmonyOS NEXT 模拟器或真机 本项目需要在 HarmonyOS NEXT 上进行测试
2 华为开发者账号 运行应用程序时需要华为开发者账号对应用进行签名
3 DevEco Studio 从官网下载并安装最新版本
4 Node.js v22.11+ 参考官网指导安装 Node.js v22.11+ 或更高版本

2. 框架开发启动

快速启动命令（连接测试机或模拟器后执行，可直接从第 8 步开始）：

git clone https://gitcode.com/openharmony-sig/ohos_react_native.git && cd ohos_react_native && git switch main && npm install -g pnpm@latest-10 && pnpm init-ws && pnpm dev

3. 详细步骤说明

步骤 操作 命令/说明
1 拉取项目代码 git clone https://gitcode.com/OpenHarmony-RN/ohos_react_native.git
2 进入项目目录 cd ohos_react_native
3 切换分支 git switch main（React Native 演进版本的适配在特性分支上进行）
4 安装 pnpm npm install -g pnpm@latest-10
5 项目初始化 pnpm init-ws（拉取 submodule 和安装 npm 依赖，耗时较长）
6 连接设备 连接设备并开启 USB 调试，或启动模拟器
7 启动测试工具 pnpm dev（启动 metro 和测试工具）
8 打开 DevEco Studio 打开 packages/tester/harmony 项目，等待后台同步完成
9 完成签名 File > Project Structure > Signing Configs，登录并完成签名
10 选择配置 右上角项目配置下拉中选中 entry
11 运行项目 点击右上角绿色三角箭头【Run 'entry'】按钮

说明：tester 项目主要用于开发过程中的自测试。如运行 tester 用例时遇到问题，请提 issue 咨询。

二、代码提交前置准备（必做）

提交代码前，需完成以下配置，避免提交失败或格式不合规：

1. 仓库配置同步

确保本地仓库已同步最新的远程仓库配置，包括 .gitcode/ 下的 PR/Issue 模板、commitlint.config.js、.husky/commit-msg 等文件，执行以下命令同步：

git pull origin main

2. Commit 模板配置

仓库根目录已提供 .gitmessage 模板，先确认该文件存在，再执行命令：

git config commit.template .gitcode/.gitmessage

或全局生效

git config --global commit.template .gitcode/.gitmessage

后续提交时将自动弹出模板，按要求填写即可。

3. 钩子与依赖配置（Node.js 项目）

项目已将 husky、commitlint 等依赖集成到 pnpm install 流程中，安装依赖后会自动初始化 Git 钩子：

pnpm install

执行后自动完成以下配置：

  • 安装 husky、commitlint、standard-version 等依赖
  • 创建 .husky/ 目录及 commit-msg、pre-push 钩子
  • 配置 Git hooks 路径

Mac/Linux 用户如遇钩子无法执行，可手动添加执行权限：

chmod +x .husky/commit-msg .husky/pre-push

4. 分支规范确认

根据《仓库分支管理规范》，基于远程分支创建个人开发分支：

分支类型 命名规范 示例
特性分支 ${version}-feature/<name> 0.82-feature/new-arch
修复分支 ${version}-hotfix/<issue> 0.82-hotfix/123

创建分支示例：

# 从远程演进主干创建特性分支
git checkout 0.82-main
git pull origin 0.82-main
git checkout -b 0.82-feature/new-arch

# 或从远程演进主干创建修复分支
git checkout 0.82-main
git pull origin 0.82-main
git checkout -b 0.82-hotfix/123-crash-fix

重要：避免直接在主分支（main、*-main、*-stable）提交代码。

5. DCO 签署配置（必做）

在 GitCode 等开源平台上提交代码时，签署开发者原创声明（DCO，Developer Certificate of Origin）是必不可少的环节。它是一个具有法律效力的声明，确认你有权贡献所提交的代码，主要用于帮助项目避免潜在的知识产权纠纷。

✍️ 第一步：在线签署 DCO 协议

这通常是一次性的操作。你可以参考以下流程：

  1. 访问签署页面：点击项目文档或门禁机器人提供的 DCO 签署链接，进入协议签署页。签署地址是：https://dco.openharmony.cn/sign
  2. 填写并提交信息：在页面下方输入你的真实姓名和邮箱（和 gitcode 账户邮箱保持一致），并填写验证码，然后点击"我同意签署"按钮
  3. 查询签署状态：签署后，可在同一网站找到"查询签署状态"功能，输入你的邮箱来确认协议是否已生效
  4. 牢记绑定邮箱：请务必牢记签署 DCO 协议时所使用的邮箱，后续步骤需要与此邮箱保持一致

💻 第二步：在 Git Commit 中添加签名

在线签署协议后，你需要在提交代码时附上签名，以将每一次的贡献与你的 DCO 协议关联起来。

命令格式：在提交时，使用 -s (或 --signoff) 参数。Git 会自动将"Signed-off-by: 你的名字 <你的邮箱>"这一行添加到你的提交信息中。

git commit -s -m "你的提交说明"

签名信息格式：确保签名行中的姓名和邮箱与你在线签署 DCO 时使用的信息完全一致。格式如下：

Signed-off-by: 张三 <zhangsan@example.com>

补签技巧：如果提交时忘了加 -s，可以使用 git commit --amend --signoff 命令为最近一次的提交补充签名。

⚠️ 第三步：处理常见的 DCO 校验失败

当你提交 Pull Request (PR) 时，平台机器人会自动进行 DCO 校验。校验失败通常由以下原因导致，可以这样解决：

失败原因 解决方案
未签署 DCO 协议 点击机器人提供的链接，在线签署协议。然后，在 PR 评论区输入 check dco 并发表评论，让系统重新检查
Commit 中缺少 Signed-off-by 信息 使用 git commit --amend --signoff 为提交补充签名，然后强制推送更新 PR。完成后，同样在 PR 评论区输入 check dco 触发重新校验

💎 关键点与提示

  1. DCO 不等于 PGP 签名：DCO 签署是法律声明，不同于用 PGP 或 S/MIME 进行的 Git commit 加密签名
  2. 所有提交均需签名：PR 中涉及的每一个 commit 都必须包含 Signed-off-by 信息
  3. DCO 与 CLA 的区别：DCO 是一种轻量级的贡献者协议，旨在降低贡献门槛；而 CLA (Contributor License Agreement) 通常条款更复杂，常用于企业主导的项目以明确授权

三、代码开发规范（前置要求）

提交代码前，需确保代码符合以下要求，避免 PR 审核驳回：

  • 新增文件必须添加 License 和 Copyright 头：所有新增的源代码文件头部必须包含 MIT License 和 Copyright 声明。开发者可根据自己的信息修改 Copyright 内容。

    示例（根据文件类型选择对应格式）：

    TypeScript/JavaScript 文件：

    /**
 * Copyright (c) [年份] [开发者名称/公司名称]
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

    C/C++ 文件：

    /**
 * Copyright (c) [年份] [开发者名称/公司名称]
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

  • 代码符合项目编码规范（如命名规则、缩进、注释要求），无语法错误、无冗余代码

  • 新增/修改功能后，必须补充对应的测试用例（单元测试/集成测试），确保测试覆盖

  • 若涉及功能、API 变更，需同步更新相关文档（如 API 文档、使用教程）

  • 无敏感信息泄露（如密钥、手机号、测试账号等），不提交二进制文件、临时文件（如 .idea/、node_modules/ 等，需通过 .gitignore 过滤）

四、Commit 提交操作（核心步骤）

Commit 是代码变更的最小单元，每一次提交需对应一个明确的变更，严格遵循 Conventional Commits 规范。

1. 暂存本地变更

开发完成后，查看本地变更，将需要提交的文件暂存，命令如下：

# 查看本地变更
git status
# 暂存指定文件（推荐，避免暂存无关文件）
git add 文件名1 文件名2
# 暂存所有变更（谨慎使用，确保无临时文件）
git add .

2. 执行 Commit 提交

执行 git commit 命令，弹出模板后，按以下要求填写：

Commit 格式规范

<type>(<scope>): <subject>

<body>

<footer>

type（类型，必选）

type 值 对应 Changelog 类型 说明
feat Added 新增功能、特性、模块、API
fix Fixed 修复 Bug、异常、兼容性问题
docs Documentation 文档变更（新增教程、补全 API 文档、勘误等）
style - 代码格式调整（不影响功能逻辑，如缩进、分号、空格等）
refactor Changed 代码重构（既不新增功能也不修复 Bug，但改变现有逻辑）
perf Performance 性能优化（不改变功能逻辑）
test - 测试相关变更（新增 / 修改测试用例）
chore - 构建流程、工具链、依赖管理相关变更（不影响用户使用）

scope（作用域，可选）

说明变更影响的模块 / 组件，如 auth、user-list、api-v2，无明确作用域可省略

subject（主题，必选）

  • 使用动词原型、现在时（如 add 而非 added/adds）
  • 首字母小写，结尾不加句号
  • 聚焦 "做了什么"，而非 "为什么做"
  • 长度 ≤ 72 字符

主体内容（可选）

  • 说明变更的动机（为什么做这个变更）
  • 对比变更前后的行为差异
  • 避免技术实现细节，保持对用户 / 贡献者友好

页脚（可选）

  • 关联 Issue/PR：格式为 Closes #123、Fixes #456、Related to #789
  • 破坏性变更（强制标注）：若存在破坏性变更，必须以 BREAKING CHANGE: 开头，详细说明变更内容、影响范围、适配方案

3. Commit 示例

（1）普通功能新增

feat(user): add batch role permission management

新增用户角色权限批量分配功能，支持通过 CSV 导入或多选用户进行批量操作，降低管理员配置成本。

Closes #234

（2）Bug 修复

fix(upload): resolve image upload failure on iOS 18

修复 iOS 18 系统下因 WebKit 表单数据解析规则变更导致的图片上传失败问题，兼容 iOS 16+ 全版本。

Fixes #189

（3）破坏性变更

refactor(auth): upgrade signature algorithm from MD5 to SHA256

重构用户认证接口签名算法，提升接口安全性，旧版 MD5 签名方式不再兼容。

BREAKING CHANGE:
- 变更内容：认证接口签名算法由 MD5 升级为 SHA256
- 影响范围：所有调用 `/v1/auth/*` 接口的下游应用
- 适配方案：参考文档《认证接口签名算法升级指南》替换签名逻辑，测试通过后再升级

Closes #456

4. 提交失败处理

若 Commit 被钩子校验拒绝（如格式错误、type 不正确），无需重新暂存，执行以下命令修改后重新提交：

# 编辑上次 Commit 信息
git commit --amend
# 修改完成后保存退出，自动重新触发校验

五、PR 提交操作（协作核心）

当个人开发分支完成开发、自测通过后，需提交 PR（Pull Request）到远程目标分支。

1. 同步远程分支（避免冲突）

提交 PR 前，需先同步远程目标分支的最新代码，解决本地冲突：

# 切换到目标分支（如 0.82-main）
git checkout 0.82-main
# 同步远程最新代码
git pull origin 0.82-main
# 切换回个人开发分支
git checkout 0.82-feature/new-arch
# 合并目标分支代码到个人分支，解决冲突
git merge 0.82-main

冲突解决：打开冲突文件，找到 <<<<<<< HEAD（本地代码）、=======（远程代码）、>>>>>>> 0.82-main 标记，修改为正确代码后，执行 git add . 和 git commit -m "resolve merge conflicts" 提交冲突解决结果。

2. 推送本地分支到远程

将本地开发分支推送到远程仓库，命令如下：

git push origin 0.82-feature/new-arch:0.82-feature/new-arch

3. 创建 PR（GitCode 操作）

  1. 打开项目远程仓库页面，点击「New pull request」
  2. 选择「源分支」（个人开发分支）和「目标分支」（如 0.82-main），确保分支选择正确
  3. PR 标题：直接使用最终合并的 Commit 标题（Squash Merge 场景），格式与 Commit 标题一致，如 feat(auth): add sms two-factor verification
  4. PR 描述：按照仓库预设的 PULL_REQUEST_TEMPLATE.md 模板填写，核心内容包括：
    • 勾选变更类型（仅选一项）
    • 详细描述变更内容、解决的问题，破坏性变更需补充影响范围和适配方案
    • 关联对应的 Issue（如 Closes #123）
    • 勾选测试情况和检查项，确保自测通过、文档同步
  5. 创建 PR 后，设置为「Draft」状态（若未完成自测），完成自测后改为「Ready for Review」，并指派至少 1 名核心维护者进行 Review

4. PR 描述模板

## 变更类型
请在对应类型前打 `√`，**仅可选择一项**：
- [ ] feat（新增功能，对应 Changelog Added）
- [ ] fix（修复 Bug，对应 Changelog Fixed）
- [ ] docs（文档变更，对应 Changelog Documentation）
- [ ] refactor（代码重构，对应 Changelog Changed）
- [ ] perf（性能优化，对应 Changelog Performance）
- [ ] test（测试相关，不进入 Changelog）
- [ ] chore（构建/工具链/依赖，不进入 Changelog）

## 变更内容
- 简要描述本次变更的具体内容、解决的问题；
- 若为**破坏性变更**，请详细说明：
  - 影响范围（哪些 API/配置/功能被修改）；
  - 用户适配方案（旧版→新版的替换步骤）

## 测试步骤
<!-- 
如何测试这条PR。例如：
1. 打开Tester工程.
2. 执行npm run start命令.
...
-->
## 测试情况
- [ ] 已通过本地完整测试（单元测试/集成测试）
- [ ] 已通过 CI 自动构建与测试
- [ ] 已补充/更新对应的测试用例
- [ ] 已在目标环境（如手机/折叠机/平板）验证功能
- [ ] 已在最低兼容环境（如 API12）验证功能

## 合入前自检
<!--
请在合入前根据以下条例进行自检
自检完成后在[ ]内填入"x", 例如：
- [x] 不涉及非兼容性变更；若涉及，已通过相应评审。
-->
- [ ] 不涉及非兼容性变更；若涉及，已通过相应评审。
- [ ] 不涉及性能或已进行性能测试且无性能劣化。
- [ ] 符合对应的编码规范。
- [ ] 无敏感信息泄露，如密码、密钥等。
- [ ] 不涉及文档更新，或已更新了文档。
- [ ] 针对可测试性要求，已增加必要的自测用例、合理的日志记录或Trace信息。
- [ ] 不存在不合规的文件引入，包括未经授权的图片和代码等

5. PR 审核与修改

  • 维护者 Review 后，会提出修改意见，开发者需根据意见修改代码，修改后重新提交到个人分支（无需重新创建 PR，PR 会自动同步）
  • 修改完成后，在 PR 评论区回复「已修改，请重新 Review」，通知维护者再次审核
  • 需确保 PR 通过 CI 自动构建与测试，若 CI 失败，需排查问题并修复后重新提交

6. PR 合并规则

PR 需满足以下条件方可合并：

  • 至少 1 名核心维护者 Review 通过（大型变更需 2 名及以上）
  • CI 构建与测试全部通过
  • 无代码冲突，与目标分支同步最新代码
  • PR 描述完整，关联 Issue、测试情况勾选齐全

合并方式：

  • 小型变更（单 Commit）：使用「Squash Merge」，合并后 Commit 标题与 PR 标题一致
  • 大型变更（多 Commit 且逻辑清晰）：使用「Rebase Merge」，保留 Commit 历史

六、Changelog 同步操作

Changelog 需与 Commit、PR 联动，确保变更可追溯，操作要求如下：

1. 随 PR 同步更新

提交 PR 时，若变更属于「用户可见变更」（feat/fix/docs/refactor/perf），需同步更新仓库根目录的 CHANGELOG.md 中「[Unreleased]」区块，添加对应的变更条目，格式与 Changelog 规范一致。

2. Changelog 格式规范

Changelog 核心结构

# Changelog

本文件记录了 {项目名称} 所有值得关注的变更内容。

本日志格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范编写，
项目版本遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/) 标准。

## [Unreleased]

### Added
- 新增 XX 功能模块，支持 XX 能力

### Fixed
- 修复 XX 场景下的崩溃问题

## [1.2.0] - 2026-03-15

### Added
- 新增用户二次验证功能，支持短信/邮箱验证码双渠道

### Fixed
- 修复了分页查询时页码超出范围返回异常的问题

[Unreleased]: https://gitcode.com/{用户名}/{仓库名}/compare/v1.2.0...HEAD
[1.2.0]: https://gitcode.com/{用户名}/{仓库名}/compare/v1.1.0...v1.2.0

变更类型分类

类型（英文 / 中文） 适用场景
Added / 新增 新增功能、特性、模块、API、配置项、文档、依赖等
Changed / 变更 现有功能的逻辑、行为、UI、API 入参 / 出参、依赖版本、默认配置的修改
Deprecated / 弃用 计划在未来版本中移除的功能、API、配置项
Removed / 移除 本版本中正式移除的、已在之前版本标记为弃用的功能、API、配置项、依赖
Fixed / 修复 各类 Bug、异常、兼容性问题的修复
Security / 安全 安全漏洞、隐私合规相关的修复与优化

3. 自动化生成

版本发布时，维护者会执行 pnpm run release，基于 Commit 历史自动生成/更新 Changelog、升级版本号、打标签，开发者无需手动操作。

4. 破坏性变更同步

若 Commit/PR 包含破坏性变更，需在 Changelog 的对应版本区块中，单独添加「【Breaking Changes】」，详细说明影响范围和适配方案。

七、分支操作规范

根据《仓库分支管理规范》，开发者需遵循以下分支操作规范：

1. 分支类型与用途

分支类型 命名规范 用途
主干 main 下一代探索开发（0.84）
版本演进主干 ${version}-main 对应版本的日常开发、功能迭代
商业发布分支 ${version}-stable 商业版本交付，仅关键修复
特性分支 ${version}-feature/<name> 大型特性隔离开发
修复分支 ${version}-hotfix/<issue> 紧急修复，合并至演进主干及发布分支

2. 分支合并流程

特性分支 → 演进主干

  • 前置条件：通过 CI 检查、至少 1 位 Maintainer 审批、代码审查通过
  • 合并方式：优先使用 squash merge，或使用 --no-ff 保留历史
  • 合并后操作：删除特性分支

修复分支 → 发布分支

  • 前置条件：修复已在演进主干验证、通过 CI 检查、至少 2 位 Maintainer 审批
  • 合并方式：优先使用 cherry-pick，禁止直接合并

3. 多版本修复同步

若多个版本需要同一个修复：

  1. 优先合入最新演进主干（如 0.82-main）
  2. 根据影响范围 cherry-pick 到其他版本的 -main
  3. 如需发布，再 cherry-pick 到对应的 -stable
  4. 记录修复的 commit hash 和影响范围

八、常见问题与注意事项

1. Commit 校验失败

检查 type 是否正确、标题长度是否 ≤ 72 字符、subject 是否符合格式，修改后使用 git commit --amend 重新提交。

2. PR 冲突无法合并

重新同步目标分支代码，手动解决冲突后提交，确保本地分支与目标分支无差异。

3. 遗漏 Changelog 更新

PR 审核时会提醒补充，若已合并，可提交新的 PR 补充 Changelog 条目。

4. 禁止提交无关变更

一个 PR 只做一件事（如一个功能、一个 Bug 修复），避免将多个无关变更合并到一个 PR。

5. Commit 历史整洁

避免多次提交无意义的 Commit（如「fix bug」「修改」），可使用 git rebase -i 提交ID 合并多个 Commit，保持历史清晰。

6. 发布分支不接受新特性

发布分支（*-stable）仅接受关键 bug 修复、安全补丁、兼容性修复。新特性必须在演进主干开发，等待下一个发布周期。

7. 禁止强制推送

禁止使用 git push -f 强制推送，除非在明确的回滚场景下。

九、总结

代码提交流程核心：「配置准备 → 代码开发 → 规范 Commit → 同步分支 → 提交 PR → 审核修改 → 合并 → Changelog 同步」，严格遵循本指南与社区相关规范，可提升协作效率，确保代码可追溯、可维护。

核心原则

  1. 一个 PR 只做一件事：避免将多个无关变更合并到一个 PR 中
  2. 规范优先：严格遵循 Commit、PR、Changelog 规范
  3. 测试先行：确保代码质量，避免 PR 审核驳回
  4. 文档同步：变更涉及文档时，同步更新相关文档
  5. 可追溯性：关联 Issue、PR，保持变更可追溯

若有疑问，可查看社区规范文档或在社区群咨询维护者。

相关规范文档：

文档版本：v1.0 | 最后更新：2026年4月