Sentry JavaScript SDK 发布流程实战指南：从 changelog 到 release 分支与自动化发布

导读

本文围绕 sentry-javascript 仓库的 release 技能文档 及其背后完整的 发布文档 展开，系统讲解发布一个新版本（含首次发布新 SDK）所需的分支操作、changelog 生成与整理、PR 合并方式，以及基于 GitHub Actions 的自动化发布链路。读完本文，你将掌握 yarn changelog 等关键命令的底层实现原理、prepare-release/VERSION 分支的正确切法与提交规范，并理解 Gitflow 分支模型在发布流程中的具体落地方式。

一、发布流程总览：谁在什么时机触发

发布动作由 Sentry 内部员工在准备发布新版本时执行。流程的核心脉络是"先改 changelog、再切分支、开 PR 合入 master、最终由自动化接管发布"，可以分为两条路径：

• 常规新版本发布（当前 master 分支）：在 develop 上生成 changelog 并切出 prepare-release/VERSION 分支，开 PR 合入 master，随后由 Auto Prepare Release 工作流 自动接管。
• 历史大版本（previous majors）或预发布版本（alpha / beta）：直接基于对应分支（如 v8、9.7.0-alpha）切出 changelog-8.45.1 这类分支，合并后需手动通过 Prepare Release 工作流 触发发布。

整个模型的背景是仓库采用的 Gitflow 分支模型：日常开发发生在 develop，准备发布时把 develop 合入 master 并发布，发布成功后再把 master 同步回 develop；master 上的内容始终代表最近一次已发布的 SDK 状态。下图清晰展示了这一流转关系：

二、标准发布流程的八个步骤

release 技能文档 将标准发布浓缩为如下步骤，每一步都对应具体命令或操作：

1. 确保位于 develop 且为最新代码。如有未保存的工作，先用 git stash -u 暂存。
2. 生成 changelog：运行 yarn changelog（需要复制输出时用 yarn changelog | pbcopy，macOS 下可直接存入剪贴板）。
3. **依据 semver 顶部确认当前版本，再根据本次变更决定版本递进策略——包含新功能则递增 minor，仅含 bug 修复则递增 patch。
4. 切分支：基于 develop 创建 prepare-release/VERSION，例如 prepare-release/8.1.0。
5. 更新 CHANGELOG.md：将上一步生成的 changelog 输出写入新版本条目，具体排版规则见下文"更新 Changelog"一节；注意不要删除已有条目。
6. 提交：提交信息固定为 meta(changelog): Update changelog for VERSION。
7. 推送分支，并提醒用户开一个指向 master 的 PR。
8. 收尾：如果原本不在 develop 分支上，切回去并视需要 git stash pop 恢复暂存内容。

三、更新 Changelog：从生成到排版

3.1 生成命令的底层原理

package.json 中注册了两个相关脚本（package.json）：

• yarn changelog 实际执行 tsx ./scripts/get-commit-list.ts；
• yarn generate-changelog 执行 tsx ./scripts/generate-changelog.ts，负责"尽力格式化"（best-effort formatting）。

看 get-commit-list.ts 的源码可以理解 yarn changelog 做了什么：

1. 执行 git log --format="- %s" 获取全部提交；
2. 找到最近一次 meta(changelog) 提交的位置，只取它之后的提交；
3. 过滤掉 Merge pull request、Merge branch 以及 release: 开头的合并/发布提交；
4. 按字母序排序，并把提交信息中的 #PR号 替换为指向 PR 的链接格式 [#PR号](https://github.com/getsentry/sentry-javascript/pull/PR号) 后输出。

而 generate-changelog.ts 则进一步做结构化处理：它解析 CHANGELOG.md 中 ## Unreleased 段落（getUnreleasedSection），把已有条目按类型归类——包含 **feat / **fix 的归入 Important Changes（isImportantEntry），以 chore / ref / test / meta 开头的归入 Internal Changes（isInternalCommit），其余归入 Other Changes；随后再从 git log 中补充尚未写入 changelog 的新提交，最终按字母序输出完整的 Markdown 段落（generateOutput）。

3.2 手写整理时的排版规则

发布文档 规定，无论自动生成还是手动整理，新版本条目都必须遵循以下格式：

1. 新建一个以版本号命名的小节，粘贴生成的 changelog 输出。
2. 重要的功能或修复放在 ### Important Changes 子标题下；若没有重要变更，则不要出现该小节。一旦使用了 Important Changes，其余所有面向用户的变更必须放在 ### Other Changes 子标题下。
3. 纯内部变更（如无用户可见影响的 ref 重构、测试、chore）放入 <details> 折叠块，<summary> 写 "Internal Changes"（见下方示例）。注意：标为 ref / chore 但实际有用户可见影响的变更应留在主 changelog 正文，不应放入内部变更区。
4. 所有条目按字母序排列。
5. 若包含外部贡献者的 PR，需在条目下方追加一行 Work in this release contributed by <贡献者用户名列表>. Thank you for your contributions!。只有一位外部贡献者时去掉末尾的 s；三位及以上使用牛津逗号。仓库内有一个 "External Contributors" GitHub Action 会在外部 PR 合入时自动在 Unreleased 区生成该行，可直接剪切粘贴，但建议仍做一次人工核对。

3.3 标准 Changelog 条目示例

发布文档给出了如下可复制的完整示例（docs/publishing-a-release.md）：

## 9.28.0

### Important Changes

- **feat(nestjs): Stop creating spans for `TracingInterceptor` ([#16501](https://github.com/getsentry/sentry-javascript/pull/16501))**

With this change we stop creating spans for `TracingInterceptor` as this interceptor only serves as an internal helper and adds noise for the user.

- **feat(node): Update vercel ai spans as per new conventions ([#16497](https://github.com/getsentry/sentry-javascript/pull/16497))**

This feature ships updates to the span names and ops to better match OpenTelemetry. This should make them more easily accessible to the new agents module view we are building.

### Other Changes

- fix(sveltekit): Export `vercelAIIntegration` from `@sentry/node` ([#16496](https://github.com/getsentry/sentry-javascript/pull/16496))

<details>
  <summary> <strong>Internal Changes</strong> </summary>

- ref(node): Split up incoming & outgoing http handling ([#17358](https://github.com/getsentry/sentry-javascript/pull/17358))
- test(node): Enable additionalDependencies in integration runner ([#17361](https://github.com/getsentry/sentry-javascript/pull/17361))

</details>

Work in this release was contributed by @agrattan0820. Thank you for your contribution!

3.4 版本号确定的语义参考

步骤 3 中"按 semver 决定版本号"的判据是：包含新功能时递增 minor，仅 bug 修复时递增 patch。当前仓库的 CHANGELOG.md 顶部即为最新版本号（当前为 11.0.0 之后的 Unreleased 区），确认版本号时应以该文件顶部为准。遇到 breaking changes 等跨版本变更，仓库还维护了 MIGRATION.md 与 docs/migration 目录（如 v9-to-v10、v10-to-v11 迁移指南），供发布说明参考。

四、PR 的合并方式与自动化发布

4.1 常规发布（master 路径）

• PR 标题固定为 meta(changelog): Update changelog for VERSION，目标分支为 master。
• 注意：合入 master 的 PR 必须使用 Merge Commit（合并提交） 方式合并——发布文档对此特别标注了 "Be cautious!"（docs/publishing-a-release.md）。
• PR 合入后，会自动触发 Auto Prepare Release 工作流（运行在 master 上），随后在发布仓库（Sentry 内部的 publish 仓库）生成一个新的 issue，issue 中附有 CI 检查运行的链接。
• 等待 CI 全部通过后，在 issue 上打上 accepted 标签即表示批准发布；发布完成后会自动触发一次 master → develop 的同步。

4.2 历史大版本与预发布版本（alpha / beta）

发布文档单列了此路径（docs/publishing-a-release.md）：

1. 在目标分支（如 v8 或 9.7.0-alpha）上运行 yarn changelog 确定版本。
2. 从该分支切出如 changelog-8.45.1 的临时分支。
3. 更新 CHANGELOG.md 后，开 PR 指向对应的历史分支（如 v8）。
4. 注意：合入历史分支的 PR 使用 Squash and Merge 方式合并（因为相关提交已存在于该分支上）。
5. 合并后，手动打开 Prepare Release 工作流，填写以下三个参数后运行：
   • 要发布的大版本分支（major branch），如 v8 或 9.7.0-alpha；
   • 要发布的版本号，如 8.45.1、9.7.0-alpha.1；
   • 要合入的目标大版本分支（major branch to merge into），如 v8、9.7.0-alpha。

下图为该工作流运行表单的实际界面，直观展示三个必填/可选参数的填写位置：

五、发布前的质量验证命令

release 技能文档 明确列出发布前应执行的四条关键命令：

• yarn changelog —— 生成 changelog 条目；
• yarn lint —— 验证代码质量；
• yarn test —— 运行测试套件；
• yarn build:dev —— 验证构建。

这些命令对应仓库根 package.json 中注册的脚本，建议在提交 changelog 前依次跑一遍，确保 prepare-release/VERSION 分支上的代码可发布。

六、首次发布新 SDK：专项检查清单

如果目标是"首次发布一个新 SDK"（例如新增一个 package），release 技能文档 要求遵循 new-sdk-release-checklist.md，清单内容与技能流程不符时需提醒用户。该清单覆盖发布前准备、正式发版、发布后跟进三个阶段：

6.1 发布前准备

• 项目完整度：package 正确导出必需模块；有可用的单元测试环境；构建产物正确（检查 <package>/build 目录）。
• README.md：包含正确的 SDK 名称与简介、指向 NPM 包的徽章、alpha/beta 状态说明（若未稳定）、安装配置说明（或链接到父级 SDK 文档）、额外信息（如 sourcemap 上传方式）。
• LICENSE：文件存在且为 MIT，并在 package.json 中同步声明。
• tarball 内容：yarn build:tarball 产物至少包含 build/cjs/<entrypoint>.js（或 build/npm/cjs/...）、build/esm/<entrypoint>.js（或 build/npm/esm/...）、build/types/<entrypoint.d.ts>（或 build/npm/types/...）、package.json（入口与实际文件结构一致）、LICENSE、README.md 及其他应打包的文件。推荐把 tarball 用 yarn add path/to/tarball.tar.gz 装到测试应用里验证完整性。
• CI 配置：build.yml 覆盖新包测试；若是浏览器 SDK，需加入 scripts/ci-unit-tests.ts 的 BROWSER_TEST_PACKAGES；确认 "Upload Artifacts" job 包含新产物路径（新增 CDN bundle 时尤其重要）。
• 依赖关系：若新包是 Remix、NextJS 等全栈框架 SDK 的依赖，需加入集成测试应用 package.json 的 "resolutions" 字段。
• 仓库登记：把新包加入仓库根 README、GitHub Issue 的 bug 模板，并在仓库中创建名为 Package: foobar 的 label。

6.2 正式发版（注意合并顺序）

清单强调各步骤的合并顺序至关重要，且都应在新 SDK 确定纳入"下一个即将发布"的版本后进行：

1. 移除 SDK package.json 中的 private: true，并设置 "publishConfig": {"access": "public"}。
2. 在 craft.yml 中为新包添加 npm 目标（放在该包所有 Sentry 依赖之后、依赖该新包的包之前）：

   - name: npm
     id: '@sentry/[yourPackage]'
     includeNames: /^sentry-[yourPackage]-\d.*\.tgz$/
   

3. 在 craft.yml 中添加 registry 目标，Craft 会自动在 Sentry Release Registry 中创建目录结构与初始 manifest：

   name: 'Sentry [Package] SDK'
   sdkName: 'sentry.javascript.[package]'
   packageUrl: 'https://www.npmjs.com/package/@sentry/[package]'
   mainDocsUrl: 'https://docs.sentry.io/platforms/javascript/guides/[package]/'
   onlyIfPresent: /^sentry-[package]-\d.*\.tgz$/
   

4. 按上文标准发布流程正式发版。

6.3 发布后跟进

• 确认包已成功发布到 NPM；
• 确认 SDK 已加入 Sentry Release Registry 的 npm packages 与 SDK symlinks；缺失则按该 registry 的说明补充；
• 持续监控 GitHub 上新的 bug 报告与反馈。

七、常见注意事项小结

• master 合并方式：常规 changelog PR 用 Merge Commit；历史分支的 changelog PR 用 Squash and Merge，切勿混淆。
• package.json 冻结：根据 Gitflow 文档 的说明，发布进行期间 develop 上可以合入任何改动，唯独不能改 package.json——否则 release 时 master 上更新的 package.json 会在 master → develop 的同步 PR 中引发合并冲突。
• 合并冲突兜底：若 master → develop 的自动化同步 PR 出现冲突，可关闭该自动 PR，基于 master 新建分支（如 manual-develop-sync），把 develop 以 merge commit 方式合入并解决冲突，再向 develop 开 PR 并同样用 merge commit 合并。
• 发布面向人群：上述完整流程（含 Auto Prepare Release 触发与 accepted 标签审批）仅对 Sentry 内部员工开放；外部贡献者通常只参与 changelog 内容本身。