1.引言：为什么需要一套“工程化的 SDK 治理流程”

在开源生态中，SDK 并不是普通的应用代码。

• 它的每一次发布，都会被成百上千的下游项目直接依赖；
• 它的每一次 API 变更，都会在用户代码中被无限放大；
• 它的每一次安全疏忽，都会沿着依赖图扩散。

因此，SDK 的问题从来不是“能不能跑”，而是“能不能被长期信任”。

很多开源 SDK 在早期阶段依赖以下隐性假设：

• 维护者足够谨慎
• Reviewer 能人工兜底
• 用户会自己看源码理解变化

但当项目进入一定规模后，这些假设都会失效：

• PR 数量增加，人工 Review 质量不可控
• 外部贡献者加入，信任边界被打破
• 发布频率提高，版本语义开始混乱

此时，如果没有一套明确的工程治理流程：

• 分支策略会变成历史负担
• CI 会退化为“跑不跑得过”
• Release Notes 会变成流水账
• Breaking Change 会在 Patch / Minor 中悄然发生

本文的目标，正是系统性地回答一个问题：

一个成熟的开源 SDK，应该如何设计自己的变更、审计、发布与安全流程？

全文从以下几个维度展开：

• 变化从哪里开始（分支与合并策略）
• 变化如何被审计（PR 规范）
• 变化如何被自动校验（CI / Workflow）
• 变化如何被安全防护（Supply Chain / External PR）
• 变化如何被对外声明（Release Notes / Migration Guide）
• 变化如何最终交付（Publish Workflow）

这不是一份“工具清单”，而是一套以用户信任为核心的工程治理模型。

2. 分支策略：变化从哪里开始

在开源 SDK 中，合并策略的选择不是个人偏好问题，而是一个工程治理问题：

• 主分支历史是否可读？
• 出问题时能否快速定位？
• 是否方便生成 Release Note 和追踪 Breaking Change？

因此，需要明确区分不同合并方式的语义差异

2.1 三种合并方式的区别与适用场景

2.1.1 Squash and Merge

行为特征

• feature分支上的多个commit会被压缩为一个新的 commit

• 原feature分支上的commit SHA不会出现在目标分支

• 目标分支只保留“这个 PR 做了什么”，而不关心中间过程

结果

• 主分支历史线性、简洁
• 每一个commit都可以直接对应一个PR/一个功能点

典型适用场景

• feature/* → dev
• 一次性功能或修复分支

为什么适合 SDK

• SDK 的使用者关心的是能力变化，而不是开发过程
• Release Note可以直接从squash commit 聚合
• 降低维护者长期理解历史的成本

2.1.2 Rebase and Merge

行为特征

• feature 分支上的每个commit会被逐个应用到目标分支
• 每个commit都会生成新的SHA
• 不会产生merge commit
• 历史保持线性

结果

• 主分支看起来像是“直接在主分支上逐步开发”
• commit粒度和质量要求非常高

典型适用场景

• 核心维护者提交
• 每个commit都具备完整语义（可独立理解、可独立回滚）

在SDK中的谨慎使用

• 一旦commit质量不稳定，会迅速污染主分支历史
• 对外部贡献者不友好
• 更适合小规模、强约束团队

2.1.3 Merge Commit

行为特征

• feature分支上的原始commits保持原有SHA
• 会生成一个新的merge commit
• 历史中保留完整的分支结构（树状）

结果
可以清楚看到：

哪个feature分支在什么时候被合并进了哪个分支

典型适用场景

• dev → main
• 发布前的版本集成
• 需要明确“这一批变更作为一个整体进入稳定分支”

为什么适合SDK

• 清晰区分「开发中」和「已发布」
• 便于回溯某个 release 对应的 commit 范围
• 对审计、回滚、问题定位非常友好

3. Pull Request 规范：变化的审核与治理机制

在开源SDK中，Pull Request 的角色并不是“提交代码”，而是一次变更的正式审计记录（change audit record）。

一个PR是否清晰，直接决定了：

• reviewer 是否能判断风险
• 维护者是否敢于发布
• 用户是否能安全升级

3.1 PR 是唯一的合并入口

原则

• 禁止直接push到dev或main
• 所有代码变更必须通过PR

原因

• SDK的每一次变更都可能影响大量下游项目
• PR提供了：
  • 可审计的变更记录
  • 可追溯的讨论上下文
  • 可回滚的合并边界

工程约束

• 分支保护规则必须开启
• CI 必须作为 merge 的硬性前置条件

3.2 PR 的作用边界：一个 PR 只表达一个意图

核心约束

• 一个ticket对应一个PR
• 一个PR只解决一个明确问题

反模式

• “顺手修一下别的地方”
• “既然路过就一起重构”
• 混合feature、bugfix、refactor

为什么在 SDK 中这是硬规则

• Reviewer 需要判断：

  • 是否是 breaking change
  • 是否影响公共 API

• 多意图PR会导致：

  • review 漏洞
  • release note 语义模糊
  • 回滚成本指数级上升

3.3 控制PR的认知复杂度，而不仅是代码行数

在SDK项目中，“小 PR”指的不是行数，而是：

• 变更目标是否单一
• 是否能在有限时间内完整理解影响范围

推荐标准

• reviewer可在 10–20 分钟内完成一次完整 review
• 变更范围可被一句话总结

3.4 PR Description：Reviewer 的第一输入源

PR Description 的目标不是“解释实现细节”，而是帮助 reviewer 判断风险和兼容性。

推荐结构与关注点

• Context
  为什么需要这个改动？解决什么用户或系统问题？

• What’s Changed
  实际发生了哪些变化（偏事实，不写结论）

• Public API Impact
  是否影响用户可见接口？

  • 新增 / 修改 / 无影响

• Backward Compatibility
  是否存在 breaking change 或行为变化？

  • 如果没有，说明为什么安全

• Related Issues / PRs
  关联的 ticket、设计文档、前置或后续 PR

3.5 依赖关系必须显式声明

在开源SDK中，隐式依赖是高风险信号。

PR中必须显式说明：

• 是否依赖前置 PR
• 是否基于某个设计决策或 RFC
• 是否有后续跟进 PR

原因

• reviewer 无法凭空推断上下文
• 发布时需要明确变更顺序
• 防止半成品被提前发布

3.6 PR中必须回答的三个关键问题

一个合格的SDK PR，reviewer至少要能从PR中找到以下答案：

1. 这次变更会不会影响现有用户？
2. 如果有问题，能不能快速回滚？
3. 这次变更在版本语义上属于哪一类？

如果PR本身无法回答这三个问题，那么它还不具备合并条件。

4. CI / Workflow：面向开源SDK的持续集成设计

在开源SDK项目中，CI的首要职责并不是“自动化”，而是 在规模化协作下，保证代码质量、安全性与发布可信度。

因此，CI的设计必须首先明确 代码来源的信任边界。

4.1 External 与 Internal 的定义

开源 SDK 中，Pull Request 通常来自两类来源：

4.1.1 Internal PR（Trusted Contributors）

定义

• PR来自同一仓库
• 提交者为组织成员或 Core Maintainer
• 拥有写权限（Write / Maintain）

信任假设

代码来源相对可信，但仍可能犯错

Internal PR 仍然必须通过完整的 CI 校验，只是：

• 可以使用更高权限的 Workflow
• 可以在受控条件下访问 Secrets
• 可以触发 Release 相关流程

4.1.2 External PR（Untrusted Contributors）

定义

• PR 来自 fork 仓库
• 提交者不具备仓库写权限
• 通常是社区贡献者

信任假设

代码来源不可信，CI 本身必须具备防御能力

External PR 的 CI 设计重点不是“效率”，而是：

• 防止恶意代码
• 防止 CI / 发布系统被利用
• 降低 Maintainer 的安全与 Review 成本

4.2 所有 PR 的统一 Workflow（Quality Baseline）

这是 Internal 与 External 完全一致的部分。

无论代码来自哪里，SDK 项目都必须执行同一套工程质量校验。

4.2.1 Build & Test Workflow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

name: Build and Test

on:
  pull_request:
    branches: [main, dev]

jobs:
  build_and_test:
    name: Build and Test
    timeout-minutes: 60
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        node-version: [25.0.0]

    steps:
      - name: Check out code
        uses: actions/checkout@v4.1.5

      - name: Setup Node.js
        uses: actions/setup-node@v4.4.0
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type Check
        run: npm run tsc --noEmit

      - name: Unit / Integration Tests
        run: npm test

      - name: Build
        run: npm run build

目标

• 保证 SDK 在干净环境下可构建
• 防止基础工程问题进入主分支

4.2.2 Code Quality 与架构约束

在 SDK 项目中，代码质量不是主观判断，而是必须被自动化、可回溯、可审计的工程约束。

因此，SDK 不应仅依赖：

• ESLint 规则
• Code Review 经验

而必须引入 静态分析引擎（Static Analysis Engine），对代码质量、架构一致性与潜在风险进行系统性扫描。

在 GitHub 生态下，CodeQL 是事实上的企业级标准。GitHub 为 CodeQL 提供了 Default Setup，用于在不维护自定义 workflow 的情况下，自动执行代码扫描。

Default Setup 的核心行为

一旦在仓库中启用 Code Scanning – Default Setup：

• GitHub 会自动配置 CodeQL 扫描
• 无需在仓库中添加任何 workflow 文件
• 扫描由 GitHub 托管并持续维护

触发机制

根据官方文档说明，Default Setup 会在以下情况下自动触发扫描：

• 每次 push 到默认分支或受保护分支
• 创建或更新指向默认分支 / 受保护分支的 Pull Request
• 定期的后台扫描（schedule）

也就是说：

只要发生 push 或 PR 行为，Code Scanning 就会自动运行。

4.2.3 Public API / Breaking Change 检测

在 TypeScript SDK 中，Public API 本质上是 对外暴露的类型契约（Type Contract）。
任何破坏该契约的变更，都属于 Breaking Change。

为此，本项目采用 @microsoft/api-extractor 作为 Public API 变化检测工具。

4.2.3.1 工具选型（TypeScript SDK）

工具：@microsoft/api-extractor

适用范围：

• TypeScript SDK
• 明确的 Public API 入口（如 src/index.ts）
• 需要在 PR 阶段阻断不兼容变更的项目

对于非 TypeScript SDK，应选用等价的 API diff 工具，遵循相同的治理原则。

4.2.3.2 API Extractor 的作用与效果

API Extractor 会：

1. 从 TypeScript 编译产物中提取 Public API
2. 生成一份 API Snapshot（API Report）
3. 与基线版本进行对比
4. 在检测到 Breaking Change 时 直接使 CI 失败

其关注点不是实现细节，而是用户是否还能继续使用该 SDK。

4.2.3.3 Semantic Version & Breaking Change 定义规范

只要用户在不改代码的情况下无法继续编译或行为发生变化，该变更即视为 Breaking Change。为了避免对 Breaking Change 的主观判断，SDK 项目必须将 SemVer 规则显式制度化。

版本号与变更类型映射

4.2.3.4 Deprecated 的处理规范

对于需要重命名或替换的 API：

1. 旧 API 必须先标记 @deprecated
2. 提供明确的替代方案
3. 保留至少一个 minor / 多个 patch 版本
4. 仅在 Major 版本 中移除

示例：

1
2
3
4
5
6

/**
 * @deprecated Use createClientV2 instead
 */
export function createClient() {}

export function createClientV2() {}

4.2.3.5 在 CI 中的治理策略

在 CI（Pull Request）阶段：

• API Extractor 作为 强制检查
• 检测到 Breaking Change：
  • 如果 PR 目标版本号 MAJOR > baseline MAJOR → 合法
  • 如果 PR 目标版本号 MAJOR = baseline MAJOR → 不允许

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

name: API Stability Check

on:
  pull_request:

jobs:
  api-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 25.0.0
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Generate PR API Snapshot
        run: npx api-extractor run --local

      - name: Compare with baseline
        run: |
          # 安装 breakd（如果未全局安装）
          npm install --save-dev breakd
          
          # 对比 PR snapshot 和 baseline
          npx breakd --source temp/api-report.d.ts --target baseline/api-report.d.ts \
            --output result.json

      - name: Check for Breaking Change
        run: |
          BREAKING=$(jq '.breakingChanges | length' result.json)
          BASELINE_MAJOR=$(jq -r '.baselineVersion.major' baseline/version.json)
          TARGET_MAJOR=$(jq -r '.targetVersion.major' package.json)
          
          if [ "$BREAKING" -gt 0 ] && [ "$TARGET_MAJOR" -eq "$BASELINE_MAJOR" ]; then
            echo "Breaking change detected but target major version not incremented"
            exit 1
          fi

4.3 依赖与供应链安全（SCA）

目标

• 防止引入已知高危漏洞依赖
• 防止依赖投毒（typosquatting / compromised package）
• 保护 SDK 的下游用户

推荐方案（Node.js / TypeScript SDK）

SDK 项目的依赖安全应基于 Dependency Graph + 持续漏洞情报，而不仅仅是一次性扫描。

• 核心能力：GitHub Dependency Graph + Dependabot Alerts
• 自动构建仓库的依赖关系图（direct / transitive）
• 持续监控已发布漏洞数据库
• 当依赖被披露为漏洞时，即使代码未变也会触发告警
• 覆盖整个仓库生命周期，而不仅是 PR 阶段

4.4 External PR 的安全增强 Workflow（Security Hardening）

在通过统一质量基线之后，**External PR 还必须额外叠加一层安全防护流程。**这一层并不用于替代 Review，而是用于：在低信任来源的前提下，显性化风险，保护 CI 与发布系统本身。

4.4.1 External PR 的权限隔离

External PR 的首要原则是 最小权限执行。

强制约束

• 不访问任何 Secrets
• 不允许 publish / deploy
• 不写入任何外部系统
• 不产生不可逆 side-effect

执行模型

• CI 以「只读、无状态」方式运行，
• 即使 PR 内容存在恶意，也无法造成扩散性破坏。

4.4.2 PR 阶段的依赖安全门禁（npm audit）

在 External PR 场景下，依赖安全需要在 代码进入 Review 阶段之前 就被显性化。

因此，在 External PR 的 Security Hardening Workflow 中，
我们引入 基于 npm audit 的即时依赖安全门禁。

该机制关注的是「当前 PR 是否引入明显风险」，而不是长期依赖健康状态。

4.4.3 Secret 扫描（Credential Leak Prevention）

目标

• 防止 PR 中引入明文凭证
• 防止 CI 被用作凭证回传或攻击跳板

推荐工具

• gitleaks

职责边界说明

• 仅负责 Secret 泄露检测
• 不负责依赖漏洞分析
• 不负责恶意代码行为分析

4.4.4 静态安全扫描（Static Security Analysis）

目标

• 发现潜在危险代码模式
• 提供恶意行为的早期信号
• 降低 Maintainer 的人工安全审查成本

推荐方案

• GitHub CodeQL（Default Setup）

静态安全扫描 已在基础 CI Workflow 中统一配置，对 Internal / External PR 一视同仁。
External Security Workflow 不会重复执行 CodeQL，而是依赖统一的安全基线结果。

4.4.5 Security Workflow 的定位

External PR 的安全流程：

• 不做合并决策
• 不自动信任代码
• 不绕过人工 Review

它的唯一目标是：

• 将安全风险结构化为信号（Signal）
• 最终是否合并，始终由 Maintainer 决策。

4.4.6 External PR 安全增强 Workflow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

name: External PR Security

on:
  pull_request:

jobs:
  security:
    if: github.event.pull_request.head.repo.fork == true
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 25.0.0
          cache: npm

      - name: Install dependencies
        run: npm ci

      # Secret leak detection
      - name: Secret scan
        uses: gitleaks/gitleaks-action@v2

5. 发布准备：Release Notes 与 Migration Guide

在 SDK 项目中，版本号本身就是对外契约。发布不仅是代码进入仓库，更是对用户明确声明：
从这一刻开始，vX.Y.Z 所代表的行为将被长期支持。

5.1 Release Notes 的职责（以版本为中心）

Release Notes 的核心目标不是描述实现，而是：明确说明：从上一个版本升级到当前版本，会发生什么变化。

因此，Release Notes 必须始终围绕以下三个版本维度展开：

• 当前版本：vX.Y.Z
• 相对上一个稳定版本的变化
• 与未来版本的关系（deprecated / planned removal）

5.2 Release Notes 必须包含的内容与示例

5.2.1 Overview（版本概览）

必须明确回答：

1
2
3
4
5

Version: x.y.z
Release Type: Patch | Minor | Major
Breaking Changes: Yes | No
Recommended For: <target users>

目的
用一段话说明本次版本的核心变化与升级风险。

示例

This patch release focuses on bug fixes and stability improvements.
No behavior changes are expected. Users are encouraged to upgrade.

或（Major）

This major release introduces a redesigned API surface and removes several legacy behaviors.
Upgrading to this version requires code changes.

5.2.2 Features（仅在 Minor / Major 中出现）

只描述“用户能用什么新能力”，不描述实现细节。

示例

Added support for async initialization.

Introduced a new configuration option to control request retries.

5.2.3 Bug Fixes（Patch / Minor / Major 均可）

必须明确“之前的行为是什么，现在变成什么”。

示例

Fixed an issue where invalid input could cause silent failures.

Resolved incorrect default values when optional parameters were omitted.

5.2.4 Refactors / Internal Changes（非功能性调整）

只在可能影响用户理解或调试时出现。

示例

Refactored internal module structure for better maintainability.

Improved error handling consistency across modules.

5.2.5 Deprecated（必须与未来 Major 关联）

Deprecated 是未来 Breaking Change 的提前通知。

示例

⚠️ The legacyMode option is deprecated and will be removed in the next major release.
Users should migrate to the new configuration-based API.

5.2.6 Breaking Change 的显式声明规则

如果 Breaking Changes: Yes，则 Release Notes 中必须包含以下段落之一：

1
2

This release contains breaking changes. Please refer to the Migration Guide before upgrading.

5.3 Migration Guide：Major Version 的专项迁移文档

Migration Guide 是 仅在 Major Version 发布时才出现的特殊文档。它的目标不是“说明变化”，而是：指导用户如何把现有代码迁移到新主版本。

5.3.1 Migration Guide 的适用前提

每一份 Migration Guide 都必须明确：

• 起点版本：上一个稳定主版本（e.g. v1.x）
• 目标版本：当前主版本（e.g. v2.0.0）
• 假设用户已经在使用起点版本的推荐用法

5.3.2 Migration Guide 的标准结构与示例

5.3.2.1 Migration Scope（迁移范围）

示例

This guide describes how to migrate from v1.x to v2.0.0.
Earlier versions are not supported.

5.3.2.2 Summary of Breaking Changes（总览）

5.3.2.3 Detailed Migration Steps（关键迁移点）

示例 1：API 结构调整

背景

旧版本中，配置参数以扁平结构传入，新版本中统一收敛为配置对象。

Before (v1.x)

1
2

client.execute(timeout, retries);

After (v2.0.0)

1
2
3
4
5

client.execute({
  timeout,
  retries,
});

迁移说明

• 所有调用点必须更新为对象形式
• 旧参数顺序不再支持

示例 2：默认行为变更

背景

旧版本中，某些错误会被自动忽略，新版本中改为显式抛出异常。

Before (v1.x)

1
2

client.run(); // silently ignores invalid state

After (v2.0.0)

1
2
3
4
5
6

try {
  client.run();
} catch (e) {
  // handle error explicitly
}

迁移说明

• 用户必须处理潜在异常
• 推荐在边界层统一捕获

5.3.2.4 Removed Features（移除能力）

示例

The legacy execution mode has been completely removed.
There is no direct replacement. Users must adopt the new execution pipeline.

6 发布流程（Publish Workflow）：从版本决策到 npm Registry

在 SDK 项目中，发布不是“把包推上去”，而是一次对用户的正式承诺。

因此，npm 发布必须满足以下原则：

• 不依赖开发者本地环境
• 不依赖个人 npm 账号状态
• 可复现、可回滚、可审计
• 与版本号、Release Notes、Breaking Change 强绑定

6.1 发布的信任与权限模型

禁止本地发布

• 禁止 Maintainer 在本地执行 npm publish
• 所有发布行为必须通过 CI Workflow

原因

• 本地环境不可审计
• 容易绕过 CI / 安全校验
• npm token 泄漏风险极高

6.2 发布tag发布触发策略

推荐的企业级策略是：

6.2.1 基于 Tag 的发布

1
2
3

git tag v1.4.0
git push origin v1.4.0

约束

• Tag 名称必须匹配 vX.Y.Z
• 版本号必须与 package.json 一致
• Tag 只能由 Maintainer 创建

6.2.2 发布前置条件

在执行 publish 前，CI 必须确认：

• 所有 PR 已合并到 main
• CI（Build / Test / Security）全部通过
• Release Notes 已存在
• 若为 Major → Migration Guide 已存在

6.3 npm Publish Workflow（GitHub Actions）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

name: Publish Package

on:
  push:
    tags:
      - "v*.*.*"

jobs:
  publish:
    name: Publish to npm
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 25
          registry-url: https://registry.npmjs.org/

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build package
        run: npm run build

      - name: Verify version matches tag
        run: |
          PKG_VERSION=$(node -p "require('./package.json').version")
          TAG_VERSION=${GITHUB_REF#refs/tags/v}
          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
            echo "Version mismatch: package.json=$PKG_VERSION tag=$TAG_VERSION"
            exit 1
          fi

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

7.总结：SDK 治理的本质是“可预期性”

回顾整套流程，可以发现一个贯穿始终的核心原则：

让每一次变化，都变得可预期。

• 对维护者而言

  • 每一个 PR 的风险是可判断的
  • 每一次发布的影响是可控的

• 对贡献者而言

  • 知道什么样的改动可以被接受
  • 知道 breaking change 的边界在哪里

• 对用户而言

  • 版本号是可信的
  • Release Notes 是可执行的
  • 升级路径是清晰的

在这套体系中：

• 分支策略定义了变化的生命周期
• PR 规范定义了变化的语义边界
• CI 定义了不可妥协的工程底线
• 安全流程定义了信任的最小半径
• Release 与 Publish 定义了对外承诺的方式

它们共同构成了一件事：
SDK 的工程信誉（Engineering Credibility）。

最后需要强调的是：这套流程并不是为了“更严格”，而是为了在规模化协作下，减少不确定性。
如果你正在维护，或计划构建一个长期演进的开源 SDK，那么这套流程不是“可选优化”，而是迟早要面对的基础设施。