一、前置思考

1.1 为什么开源贡献比写代码更难？

写业务代码: 对产品负责 → 需求明确、验收标准在 PM 手里
开源贡献:   对社区负责 → 代码规范、测试覆盖、文档、署名全部自证

社区不会为"你的代码能跑"买单
社区只接受"可审计、可回归、可维护"的代码
→ 贡献的第一步不是写代码，而是理解流程

1.2 一次 PR 的完整旅程

Fork 仓库 → Clone 到本地 → 切分支 → 写代码
  → 本地测试 → Commit(DCO 签署) → Push
  → 发起 PR → CI 门禁检查 → 社区 Review
  → 修改意见 → 迭代 → Approve → Merge
  → 清理分支（PR 被合入后自动删除）

1.3 三个核心心智

1. 分支即隔离: 主分支永远可发布，一切改动先在分支上
2. Review 即质量: 代码合入前至少 1 个 Maintainer 批准
3. CI 即底线: 测试不过 = 代码不存在，门禁卡死一切

二、核心原理

2.1 SIG 组管理架构

OpenHarmony 社区: SIG (Special Interest Group) 专项兴趣组

  ┌────────────────────────────────────────────┐
  │ PMC (项目管理委员会)                          │
  │   └─ 决策方向 / 发布版本 / 跨 SIG 协调         │
  ├────────────────────────────────────────────┤
  │ SIG-A: ArkUI   │ SIG-B: 内核   │ SIG-C: 驱动  │
  │   Maintainer×N │   Maintainer×N │ Maintainer×N│
  │   └ Committer └ Committer  └ Committer       │
  ├────────────────────────────────────────────┤
  │ Contributors (贡献者): 提 PR / 报 Issue / 写文档 │
  └────────────────────────────────────────────┘

角色职责:
  Maintainer: 审批合入、领导方向、社区治理
  Committer:  深度 Review、主导模块设计
  Contributor: 提交代码/文档/Issue，成长为 Committer 的路径

2.2 代码 Review 规范

Review 关注点 (按优先级):
  1. 正确性: 逻辑是否对？边界是否处理？
  2. 安全性: 是否引入注入/越权/数据泄露？
  3. 性能:   复杂度？是否在主线程做耗时操作？
  4. 兼容性: API Level？旧版本降级？
  5. 规范:   命名/格式/注释 (lint 门禁)

Review 铁律:
  → 小步提交: 一个 PR 只做一件事 (≤500 行)
  → 拒绝"顺便改": 无关改动单独提 PR
  → 有问必答: 每条 comment 都要有回应
  → 24h 响应: 社区节奏靠及时反馈维持

2.3 CI 门禁流水线

Push → Trigger CI → 并行执行:
  ├─ 静态检查: cjlint / ArkTS Lint / 格式检查
  ├─ 单元测试: 全量单测 (新增代码必须带测试)
  ├─ 编译构建: 多平台交叉编译
  ├─ 兼容性:   XTS 用例子集
  └─ 覆盖率:   增量覆盖率 ≥ 门限
全部通过 → 可以合入
任一失败 → 必须修复后重跑 (不能绕过)

2.4 DCO 签署机制

DCO (Developer Certificate of Origin) 开发者原创声明
  → 每次 commit 附加: Signed-off-by: 姓名 <邮箱>
  → 声明: 我保证这段代码是我写的/我有权提交

为什么需要 DCO:
  → 法律层面的版权溯源
  → 防止未授权代码混入 (如抄袭/泄密代码)
  → 与 CLA (Contributor License Agreement) 互补

签署方式:
  git commit -s -m "feat: xxx"
  → 自动追加 Signed-off-by 行

三、源码/API 深度解析

3.1 合规的 Git 提交流程

# 1. Fork 上游仓库到个人账号 → Clone
git clone https://gitee.com/<user>/openharmony_xxx.git
cd openharmony_xxx

# 2. 添加上游 remote，保持同步
git remote add upstream https://gitee.com/openharmony/xxx.git
git fetch upstream

# 3. 从最新主干切功能分支 (命名: feat/fix/docs/refactor + 描述)
git checkout -b feat/optimize-list-lazy-load upstream/master

# 4. 写代码 + 本地测试
# ...

# 5. 提交 (小步 + DCO 签署 + 规范 message)
git add entry/src/main/ets/pages/ListOptimize.ets
git commit -s -m "feat(list): 优化长列表 LazyForEach 预加载策略

- cachedCount 按屏高动态计算
- 复用池增加容量上限，防止内存膨胀
- 补充单元测试覆盖预加载边界

Signed-off-by: Zhang San <zhangsan@example.com>"

# 6. 推送并提 PR
git push origin feat/optimize-list-lazy-load

3.2 Commit Message 规范（Conventional Commits）

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

type 类型:
  feat:     新功能
  fix:      Bug 修复
  docs:     文档
  style:    格式 (不影响逻辑)
  refactor: 重构 (不改功能)
  perf:     性能优化
  test:     测试
  build:    构建/依赖
  chore:    杂项

示例:
  feat(arkui): 新增 Grid 拖拽排序能力
  fix(router): 修复深链跳转偶发白屏
  perf(list): 列表滑动内存峰值降低 40%

3.3 开源贡献规范检查清单（提交前自检）

□ 分支是否从最新主干切出？
□ PR 是否只做一件事？
□ 是否有对应的 Issue 链接？
□ 单元测试是否覆盖新增逻辑？
□ 本地是否跑通 lint + 单测 + 构建？
□ Commit 是否 Signed-off-by？
□ 是否补充了 CHANGELOG/文档？
□ 是否遵守了 SIG 的贡献指南 (CONTRIBUTING.md)？

四、企业级实战落地

4.1 开源贡献流程速查表

阶段	动作	关键工具/规范
准备	Fork + Clone + 上游同步	git remote
开发	切分支 + 小步提交	Conventional Commits
自检	lint + 单测 + 构建	cjlint / hvigor test
提交	Push + 发起 PR	DCO 签署
门禁	CI 全量检查	静态检查/单测/XTS
评审	回应 Review 意见	逐条 comment 处理
合入	Maintainer Approve	必须 ≥1 批准
善后	清理分支 + 跟进 Issue	标记 closed

4.2 完整示例：开源协作状态机演示

@Entry
@ComponentV2
struct OpenSourceRepoDemo {
  @Local prState: string = '待提交';
  @Local reviewComments: number = 0;
  @Local ciPassed: boolean = false;
  @Local logs: string[] = [];

  // 模拟一次 PR 从提交到合入的全流程
  private runPrFlow(): void {
    this.logs = [];
    this.prState = 'developing';
    this.log('📝 ① Fork + 切分支: feat/optimize-cache');
    this.log('💻 ② 编写代码: 优化缓存命中策略');
    this.log('🧪 ③ 本地单测: 12/12 通过');
    this.log('🔏 ④ DCO 签署: Signed-off-by ✓');
    this.log('⬆️ ⑤ Push + 发起 PR #4521');

    this.prState = 'ci';
    this.ciPassed = false;
    this.log('🔧 ⑥ CI 门禁启动...');
    this.log('   静态检查: 通过 (0 error)');
    this.log('   单元测试: 通过 (全部用例)');
    this.log('   编译构建: 通过 (3 平台)');
    this.log('   XTS 兼容: 通过');
    this.ciPassed = true;

    this.prState = 'review';
    this.reviewComments = 0;
    this.log('👀 ⑦ 社区 Review 开始');
    this.log('   Maintainer A: 建议补充边界测试');
    this.log('   Maintainer B: 提问缓存失效时序');
    this.log('   → 回应 2 条意见 + 补充用例');
    this.reviewComments = 2;

    this.prState = 'merged';
    this.log('✅ ⑧ Maintainer Approve → Merge');
    this.log('🧹 ⑨ 自动删除分支 + 关闭 Issue #4508');
  }

  build() {
    Column({ space: 12 }) {
      Text('🌐 开源协作流程演示').fontSize(20).fontWeight(FontWeight.Bold)
      Text('状态: ' + this.prState).fontSize(13).fontColor('#0969DA')

      Row({ space: 8 }) {
        Button('▶ 模拟 PR 全流程').layoutWeight(1).height(40).fontSize(12)
          .onClick(() => this.runPrFlow())
        Button('清空').height(40).fontSize(12)
          .onClick(() => this.logs = [])
      }
      .width('100%')

      Scroll() {
        Column() {
          ForEach(this.logs, (l: string) => {
            Text(l).fontSize(11).lineHeight(18).fontColor('#24292F').width('100%')
          }, (l: string, i: number) => l + i)
        }.width('100%')
      }
      .layoutWeight(1).width('100%').scrollBar(BarState.Off)
    }
    .width('100%').height('100%').padding(16)
    .backgroundColor('#F6F8FA')
  }
}

4.3 提交流程最佳实践清单

1. 一个 PR 一件事，控制在 500 行以内，Review 才高效
2. Commit message 用 Conventional Commits，机器可解析
3. 每次 commit 都 -s 签署 DCO，别等提 PR 再补
4. Review 意见逐条回复，附上修改后的 commit 链接
5. 合入前 rebase 到最新主干，保持历史线性清晰

五、问题排查与性能优化

问题	原因	解决
PR 冲突	主干已前进	fetch + rebase 到最新
CI 失败	静态检查/单测不过	本地先跑完整门禁再 push
Review 无人响应	改动太大/描述不清	拆小 PR + 写清背景和测试
DCO 缺失	commit 未 -s	git commit --amend -s
分支过期	基于旧主干	频繁同步 upstream
合入被拒	无测试/超范围	补测试 + 拆分无关改动

5.1 Review 效率优化

1. PR 描述模板化: 背景/改动/测试/影响面 四段式
2. 附截图/录屏: UI 改动可视化，减少沟通成本
3. 提前自 Review: 提交前通读 diff，消灭低级问题
4. 小步推送: 每完成一个逻辑点就 push，方便分段 review

六、高阶总结与最佳实践

1. 流程即质量：SIG 治理 + Review 规范 + CI 门禁，是开源协作的质量三支柱。
2. 小步提交：一个 PR 一件事，是让 Review 高效、合入顺利的第一原则。
3. DCO 是底线：每次 commit 签署原创声明，法律风险前置到提交那一刻。
4. 门禁不可绕过：CI 失败绝不强行合入，质量红线一视同仁。
5. 贡献是双向的：回应 Review 是贡献，写文档是贡献，参与社区讨论同样是贡献。

一句话记住：开源协作的本质是"流程化信任"——SIG 定方向、Review 保质量、CI 守底线、DCO 立声明，把"一个人写代码"升级为"一群人共建代码"。