企业官网建设流程全解析

Editor.js 分支管理与版本发布指南：从next分支到 NPMlatest标签的完整自动化管线

【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.js

本篇指南系统讲解 Editor.js 开源仓库（包名@editorjs/editorjs）的分支策略、语义化版本规则与 Release 发布流程。你将掌握master/next双分支的职责划分、major.minor.patch与-rc.*预发布后缀的取舍方法，以及三份 GitHub Actions 工作流如何自动完成"版本号提升 → 创建发布草稿 → 发布到 NPM"的全链路，最终能够独立走通一次从 bug 修复到正式发版的完整管线。

分支策略：master 与 next 双轨并行

Editor.js 仓库维护两条主干分支，职责划分非常清晰：

• master分支：承载编辑器的最新稳定版本。该分支上合入的版本会以默认标签（latest）发布到 NPM，用户执行npm i @editorjs/editorjs默认获取的就是它。
• next分支：用于开发下一个（候选发布，Release Candidate）版本。它可能包含 bug 修复、功能改进或新特性，对应包会以next标签发布到 NPM。

换句话说，master面向生产消费者，next面向尝鲜用户与内部迭代。从当前仓库快照看（git branch显示远端 HEAD 指向origin/next，最新标签为v2.31.7），开发工作始终在next上进行，稳定版则从其中挑选合适的节点发布——这正是下文整套自动化流水线的前提。

说明：master与next的约定是仓库发布策略的核心（见 docs/releases.md），而 package.json 中的包名、版本号（当前为2.31.7）与构建产物入口（dist/editorjs.umd.js、dist/editorjs.mjs）则共同构成了"版本号 → NPM 包"的事实映射。

语义化版本：major.minor.patch 的取舍

Editor.js 以 [Semantic Versioning] 语义化版本规范作为版本命名的基本准则，版本号格式为：

<major>.<minor>.<patch>

根据变更对下游的影响程度，选择提升哪一段：

预发布版本可以在基础版本号后追加-rc.*后缀（rc即 Release Candidate），例如2.19.1-rc.0。

仓库的 docs/CHANGELOG.md 是这条规则的实践样本：例如 2.31.7 仅包含一条Fix（触发原生<select>的 onChange），属于典型 patch 级发布；而 2.31.0 混入了New/Improvement/Fix多种类型，其中包含新特性，因此提升 minor。逐条对照 changelog 的类型前缀（Fix、New、Improvement、DX），可以快速判断某次合并应当落在哪个版本段。

发布工作流总览：三份 Actions 分工协作

版本发布不是手工过程，而是由三份 GitHub Actions 工作流接力完成，它们全部位于 .github/workflows 目录：

三者构成一条完整链路：合代码 → 自动 bump 版本 → 建发布草稿 → 人工审核 → 正式发布 → 自动上 NPM。

发布草稿的自动创建

当带有已更新版本号的 PR 合并到next后，create-a-release-draft.yml会：

1. 通过codex-team/action-nodejs-package-info@v1读取合并前后的 package.json 版本并比对，若版本未变化则调用 GitHub API 取消本次工作流运行；
2. 检出代码（含递归子模块）、yarn安装依赖、执行yarn build构建产物；
3. 使用actions/create-release@v1以draft: true创建发布草稿，标签名取自v${{ steps.package.outputs.version }}；
4. 上传dist/editorjs.umd.js与dist/editorjs.mjs两个构建产物作为 Release 附件；
5. 通过codex-team/action-codexbot-notify@v1向内部频道推送"草稿已创建"的提醒消息。

草稿的描述默认取 PR 标题与编号（body: "${{ github.event.pull_request.title }} #${{ github.event.pull_request.number }}"）。发布者需要把草稿描述替换为目标版本对应的 changelog 内容——即从 docs/CHANGELOG.md 中摘出该版本条目，再点击发布：

发布后自动上 NPM

GitHub 上正式发布 Release 后，publish-package-to-npm.yml随即被release事件的published类型触发：

1. 检出代码（含递归子模块），配置 Node 18 与 npm registry；
2. 执行yarn与yarn build（对应package.json中的build脚本：vite build --mode production）；
3. 执行yarn publish --access=public --tag=next先把包发布到 NPM 的next标签；
4. 关键一步：仅当github.event.release.prerelease != true（即非预发布）时，执行npm dist-tag add <name>@<version> latest，把该版本补打上默认的latest标签；
5. 完成后由notify任务向公开频道推送发布成功消息。

也就是说：发布动作统一走next标签，latest标签只授予正式版本。这保证了 NPM 上latest永远指向稳定版，next永远指向最新的候选版。

Release Candidate 预发布：-rc.*后缀

如果你想发布候选版本，只需在 package.json 的版本号与 releases 页面的标签中都使用-rc.*后缀。工作流会检测到该标记并自动把发布标为pre-release：

具体机制见 create-a-release-draft.yml：创建草稿时prerelease: ${{ contains(steps.package.outputs.version, '-rc') }}——只要版本号里包含-rc字符串，预发布复选框即被自动勾选。相应地，publish-package-to-npm.yml中github.event.release.prerelease != true的条件判断会阻止 RC 版本获得latest标签，它只以next标签发布。

三类版本的命名关系如下：

即：2.19.1-rc.0 → 2.19.1-rc.1 → … → 2.19.1，候选版迭代完成后再剥离-rc后缀发布正式版。

自动版本号提升（Auto-bump）

每次 PR 合并到next分支后，bump-version-on-merge-next.yml 都会检查 package.json 中的版本是否已更新：

• 若 PR 已手动改过版本号，工作流直接取消运行（Stop workflow if version was changed already步骤）；
• 若版本号未更新，则自动打开一个新 PR，提议下一个预发布版本。

工作原理

bump 动作的核心命令是：

yarn version --prerelease --preid rc --no-git-tag-version

• --prerelease：将版本号提升为预发布版本；
• --preid rc：预发布标识符使用rc；
• --no-git-tag-version：只改 package.json，不打 git tag。

行为分两种情况：

2.19.1 -> 2.19.2-rc.0 （基础版本 bump 一个 patch，并加上 rc.0） 2.19.2-rc.0 -> 2.19.2-rc.1 （已有 rc 则递增 rc 序号）

随后工作流用peter-evans/create-pull-request@v3创建 PR：分支名固定为auto-bump-version，标题为Bump version up to <新版本号>，PR 描述中注明触发来源（**<PR 标题>** #<PR 编号>），合并后delete-branch: true自动删除分支。

安全提示：该工作流与create-a-release-draft.yml均使用pull_request_target触发器，其官方注释特别警告——该触发器为 fork 来源的 PR 也授予仓库 secrets 与写权限，因此严禁 checkout PR 自身的提交（github.event.pull_request.head.sha），以避免恶意代码执行，这是阅读这两个工作流时应当知晓的约束。

修改版本号

自动提议的版本未必符合预期。例如下一轮计划是提升 minor 版本（2.19.1 -> 2.20.0），那么应该在"版本更新合并之前"手动修改：

默认：2.19.1 会被提升为 2.19.2-rc.0 修改：将 2.19.2-rc.0 改为 2.20.0-rc.0

同理，如果你需要直接发布正式版本而非预发布版本，也可以直接编辑版本号（以及 PR 标题）。这些修改应在 bump PR 合并之前完成，因为后续的发布草稿创建与 NPM 发布都以 package.json 中的版本号为准。

忽略更新

如果本次合并的 PR 不需要发布新版本（例如纯文档更新或其他无关紧要的变更），直接关闭工作流生成的这个auto-bump-versionPR 即可。关闭 PR 后版本号保持不变，不会触发后续的发布草稿创建流程。

完整发布示例管线

假设当前 package.json 版本为2.19.0，你想合入一些 bug 修复并发布2.19.1，完整流程如下：

1. 将一个或若干包含修复的 PR 合并到默认开发分支next；
2. 工作流 bump-version-on-merge-next.yml 将 package.json 中的版本自动提升到2.19.1-rc.0，并打开一个新的版本提升 PR；
3. 该 bump PR 合并后，工作流 create-a-release-draft.yml 自动在 GitHub 上创建发布草稿；
4. 到 releases 页面检查这个新草稿：确认 tag 为v2.19.1-rc.0，若这是候选版本请留意 "This is a pre-release" 复选框应处于勾选状态（RC 版本会被自动勾选），然后把 changelog 填入描述并发布；
5. 工作流 publish-package-to-npm.yml 自动把该版本发布到 NPM，标签为next；
6. 当候选版验证完成、准备发布正式版时：在bump-version-on-merge-next.yml生成的 PR 中，把版本号去掉-rc后缀（2.19.1-rc.0 -> 2.19.1），再次走第 3-5 步，新版本将以latest标签发布；
7. 最后把next分支合并回master，为历史留存稳定版源码快照。

实践要点小结

• 版本号是发布流程的唯一事实来源：三个工作流均通过action-nodejs-package-info读取 package.json 的version字段做判断，任何手动打 tag、改 Release 标题都不会改变 NPM 发布行为。
• latest标签只属于稳定版：即使发布动作统一带--tag=next，非预发布版本也会被npm dist-tag add补上latest，消费者默认安装永远拿到稳定版。
• 构建产物随草稿一起生成：发布草稿自动附带editorjs.umd.js与editorjs.mjs，与 package.json 中main/module字段声明的入口一一对应，方便不通过包管理器使用的用户直接从 Release 页面下载。
• 不想发版就关掉 bump PR：文档更新类改动无需发布时，关闭自动生成的版本提升 PR 即可，简单直接。
• 回归对照：发布前将草稿描述替换为 docs/CHANGELOG.md 中对应版本的条目，同时结合该版本的Fix/New前缀判断版本段是否 bump 正确，可作为每次发布前的人工检查清单。

【免费下载链接】editor.jsA block-style editor with clean JSON output项目地址: https://gitcode.com/gh_mirrors/ed/editor.js