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根据变更对下游的影响程度选择提升哪一段版本段触发条件典型变更patchbug 修复、文档更新、代码风格修正等不影响最终构建产物的变更修复链接在 Safari 下的插入问题2.30.7、修复 onChange 对原生select的触发2.31.7minor新增功能且不存在向后兼容问题只读模式下支持带isReadOnlySupported的内联工具2.31.0major破坏性变更与上一版本 API 不再向后兼容公共 API 或配置结构发生不兼容调整预发布版本可以在基础版本号后追加-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-version-on-merge-next.ymlPR 合并到next分支pull_request_targettypes: [closed]检查 package.json 版本是否已更新若未更新则自动提议下一个预发布版本并开 PRcreate-a-release-draft.ymlPR 合并到next分支且版本号发生变化构建产物并自动创建 GitHub 发布草稿draft含 UMD/MJS 两个构建产物附件publish-package-to-npm.ymlGitHub 发布Release被正式published构建并发布包到 NPM按是否为预发布版本打next或latest标签三者构成一条完整链路合代码 → 自动 bump 版本 → 建发布草稿 → 人工审核 → 正式发布 → 自动上 NPM。发布草稿的自动创建当带有已更新版本号的 PR 合并到next后create-a-release-draft.yml会通过codex-team/action-nodejs-package-infov1读取合并前后的 package.json 版本并比对若版本未变化则调用 GitHub API 取消本次工作流运行检出代码含递归子模块、yarn安装依赖、执行yarn build构建产物使用actions/create-releasev1以draft: true创建发布草稿标签名取自v${{ steps.package.outputs.version }}上传dist/editorjs.umd.js与dist/editorjs.mjs两个构建产物作为 Release 附件通过codex-team/action-codexbot-notifyv1向内部频道推送草稿已创建的提醒消息。草稿的描述默认取 PR 标题与编号body: ${{ github.event.pull_request.title }} #${{ github.event.pull_request.number }}。发布者需要把草稿描述替换为目标版本对应的 changelog 内容——即从 docs/CHANGELOG.md 中摘出该版本条目再点击发布发布后自动上 NPMGitHub 上正式发布 Release 后publish-package-to-npm.yml随即被release事件的published类型触发检出代码含递归子模块配置 Node 18 与 npm registry执行yarn与yarn build对应package.json中的build脚本vite build --mode production执行yarn publish --accesspublic --tagnext先把包发布到 NPM 的next标签关键一步仅当github.event.release.prerelease ! true即非预发布时执行npm dist-tag add nameversion latest把该版本补打上默认的latest标签完成后由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标签发布。三类版本的命名关系如下类型示例NPM 标签是否 pre-release稳定版Stable2.19.0latest否候选版Release candidate2.19.1-rc.0、2.19.1-rc.1、…next是下一个正式版Next version2.19.1latest否即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-requestv3创建 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完整流程如下将一个或若干包含修复的 PR 合并到默认开发分支next工作流 bump-version-on-merge-next.yml 将 package.json 中的版本自动提升到2.19.1-rc.0并打开一个新的版本提升 PR该 bump PR 合并后工作流 create-a-release-draft.yml 自动在 GitHub 上创建发布草稿到 releases 页面检查这个新草稿确认 tag 为v2.19.1-rc.0若这是候选版本请留意 This is a pre-release 复选框应处于勾选状态RC 版本会被自动勾选然后把 changelog 填入描述并发布工作流 publish-package-to-npm.yml 自动把该版本发布到 NPM标签为next当候选版验证完成、准备发布正式版时在bump-version-on-merge-next.yml生成的 PR 中把版本号去掉-rc后缀2.19.1-rc.0 - 2.19.1再次走第 3-5 步新版本将以latest标签发布最后把next分支合并回master为历史留存稳定版源码快照。实践要点小结版本号是发布流程的唯一事实来源三个工作流均通过action-nodejs-package-info读取 package.json 的version字段做判断任何手动打 tag、改 Release 标题都不会改变 NPM 发布行为。latest标签只属于稳定版即使发布动作统一带--tagnext非预发布版本也会被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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考