Marked 版本发布指南semantic-release、Conventional Commits 与语义化版本管理实战【免费下载链接】markedA markdown parser and compiler. Built for speed.项目地址: https://gitcode.com/gh_mirrors/ma/markedMarked 作为一款以速度为设计目标的 Markdown 解析与编译库当前仓库版本为 18.0.12其新版本发布完全由 semantic-release 自动化驱动配合 Conventional Commits 提交规范与严格的语义化版本SemVer规则。本文以 docs/PUBLISHING.md 为核心骨架结合仓库内的 CI/CD 工作流、发布插件配置 与 构建脚本 源码系统讲解 Marked 的版本发布流程、major/minor/patch判定标准、Node.js 支持策略以及发布者的职责边界读者可据此理解并复现一套主分支始终可发布的自动化发布工程。一、发布工具链semantic-release 驱动的全自动流程Marked 使用semantic-release来自动发布新版本这一选择直接决定了整个仓库的协作方式开发者在日常提交时无需手动维护版本号package.json中的版本字段由发布工具在发布时自动递增。仓库中的发布插件配置见 .releaserc.json其按顺序注册了 5 个插件{ plugins: [ semantic-release/commit-analyzer, semantic-release/release-notes-generator, semantic-release/npm, semantic-release/github, semantic-release/git ] }各插件在发布管线中的职责如下插件作用阶段实际产出semantic-release/commit-analyzer分析根据提交信息决定下一次发布是major、minor还是patchsemantic-release/release-notes-generator生成依据 Conventional Commits 自动生成 release notessemantic-release/npm发布将包发布到 npm registry并处理版本号写入semantic-release/github发布在 GitHub 创建 Release 与 git tagsemantic-release/git收尾将版本号变更等提交回仓库对应地package.json 的devDependencies中声明了semantic-release/commit-analyzer、semantic-release/release-notes-generator、semantic-release/npm、semantic-release/github、semantic-release/git以及核心的semantic-release本体^25.0.9与.releaserc.json的插件清单一一对应。前提约束这套流程要求合并进master的每个提交都遵循规范格式否则 commit-analyzer 无法正确判断版本增量这也就引出了下文的提交规范要求。二、协作入口Squash and merge 与 Conventional Commits原文档明确规定了两条协作纪律所有 PR 都应使用 Squash and merge压缩合并策略。这意味着每个 PR 合并后只产生一条提交记录保证master的历史线是干净、线性的也让 semantic-release 对提交信息的解析结果唯一且确定——否则一个 PR 若包含多条风格不一的提交版本判定会失真。提交信息必须遵循 Conventional Commits约定式提交规范。这是 commit-analyzer 判读版本增量的事实依据以feat:开头的提交触发minor以fix:开头的提交触发patch而feat!:或BREAKING CHANGE:则触发major。在 docs/CONTRIBUTING.md 中可以看到与此配套的贡献流程从master分支切出特性分支、修改src目录源码lib目录为自动编译产物、运行npm test修复问题、提交 Pull Request。也就是说规范的提交信息是主分支可发布策略能够成立的前提。三、总体策略Master 永远可发布原文档点明了 Marked 发布策略的核心思想Master is always shippable主分支永远可发布团队在合并 PR 时尽量保证master是唯一真正需要关注的、并且随时可以发布的分支。这一设计带来的实际收益是新功能、Bug 修复、规范对齐等不同类型的工作可以在同一条主线上平滑流动不必为攒一个发布而维护长期存在的 release 分支每次推送到master都等价于一次潜在的发布机会发布时间由语义化版本规则自动决定而不是靠人工挑日子。这一策略在 .github/workflows/tests.yml 的Releasejob 中得到工程化落地该 job 仅在github.ref refs/heads/master且非 fork 仓库时触发且needs: [UnitTests, OtherTests]——即只有全部测试通过才会执行发布。四、版本号规则语义化版本SemVer的判定标准Marked 遵循语义化版本规范版本号形式为[major].[minor].[patch]其递增判定标准原文档给出了明确的定义Major主版本满足以下任一条件时递增——公共 API 至少有一处破坏性变更breaking change与 CommonMark 或 GFM 规范相比出现规范层面的破坏性偏离值得注意的是对某个 Node.js 版本的支持终止不一定会导致 Marked 的 semver 主版本号递增。项目只承诺在任何时间点支持 当前活跃与 LTS 的 Node.js 版本。Minor次版本公共 API 至少新增一个特性时递增。Patch补丁版本使 Marked 更接近规范合规spec compliance的修改或不破坏向后兼容性的公共 API 变更。汇总成对照表版本位触发条件示例major公共 API 破坏性变更与 CommonMark/GFM 规范的破坏性偏离可能包含 Node.js 支持范围调整不一定触发18.x.x→19.0.0minor公共 API 新增特性18.0.x→18.1.0patch更贴近规范合规的修改不破坏向后兼容的 API 变更18.0.12→18.0.13仓库现状正好是这套规则的注脚当前 package.json 中的版本为18.0.12patch 位engines字段声明node: 20而 .github/workflows/tests.yml 的UnitTestsjob 使用 Node 20、lts/*、latest三档做矩阵测试注释明确指出最低版本应与engines字段保持一致。这印证了原文档只支持 current 和 LTS Node.js 版本的承诺——一旦 Node 20 退出 LTSengines上调并不必然伴随 major 版本号递增。另外README.md 的兼容性章节同样重申了这一点只有当前活跃与 LTS 的 Node.js 版本被支持EOL生命周期结束的 Node.js 版本可能在任何时间点与 Marked 不兼容与发布文档的口径完全一致。五、发布在 CI 中的真实执行链路原文档只描述了用 semantic-release 发布而仓库内的 .github/workflows/tests.yml 完整展现了这条自动化管线的实际编排可分为三个 job1. UnitTests构建与核心测试Node 版本矩阵[20, lts/*, latest]下依次执行npm ci、npm run build、npm run test:unit、npm run test:specs、npm run test:cjs。2. OtherTests格式、类型与打包产物测试在lts/*上执行npm run test:umd、npm run test:types含attw包导出类型检查与npm run test:lintESLint。3. Release真正的发布步骤这是理解 Marked 发布工程的关键其核心逻辑分为两步第一步——预构建带版本号的产物并提交export SEMANTIC_RELEASE_NEXT_VERSION$(npx semantic-release --no-ci --dry-run | grep -oP The next release version is \K[0-9]\.[0-9]\.[0-9]) npm run build if ! git diff --quiet; then git commit -am ️ build v$SEMANTIC_RELEASE_NEXT_VERSION [skip ci] fi它先以--dry-run模式让 semantic-release 预测下一次发布版本号把该版本号注入构建过程随后若构建产物有变化lib/下的编译文件会随版本号更新则自动提交提交信息形如build v18.1.0 [skip ci]。第二步——正式发布npx semantic-release该 job 的permissions明确申请了contents: write创建 GitHub Release与id-token: write启用 OIDC 可信发布与 npm provenance对应 package.json 中的publishConfig: { provenance: true }。版本号注入构建的源码实现版本号之所以能预知是因为 esbuild.config.js 的第 5 行做了环境变量回退const version process.env.SEMANTIC_RELEASE_NEXT_VERSION || JSON.parse(fs.readFileSync(./package.json)).version;即存在SEMANTIC_RELEASE_NEXT_VERSION环境变量CI 的 dry-run 阶段设置时优先使用它否则回退到读取package.json中的当前版本。该版本号最终被写入lib/marked.esm.js与lib/marked.umd.js的文件头 bannermarked v${version} - a markdown parser ...。这解释了为何 CI 要在npm run build之前先算出 next version否则打包产物里携带的就是旧版本号发布后产物与版本不一致。此外CHANGELOG.md 只有一行see https://github.com/markedjs/marked/releases说明变更日志不再手工维护而是完全由 semantic-release 的 release-notes-generator 在 GitHub Release 中自动生成——这也是该发布体系与 Conventional Commits 深度绑定的又一佐证。六、发布者的职责边界与治理约束版本发布不仅是技术动作还涉及人的职责划分。docs/AUTHORS.md 的 Publishers 章节对此有明确说明Publishers发布者是具有管理员权限、同时承担向 npm 发布新版本、对外沟通与外部利益相关方联络职责的角色发布顺利时由他们主要表扬贡献者出问题时他们也是主要承压方。数量约束发布者人数不应超过 2 人。文档给出的理由是拥有发布权限的人越多越容易演变成委员会式共识困境单人Directly Responsible Individual直接责任人是首选但考虑到项目历史设置一个直接后备和一个深度后备原作者较为合适。从源码结构可以推断发布权限与 Git 写入权限、npm 包发布权限是分离治理的日常贡献者只需遵循 docs/CONTRIBUTING.md 的流程提交 PR而真正触发发布动作的Releasejob 被限制在master分支且非 fork 仓库再由持有 npm 凭据的发布者角色兜底。这种提交者—管理员—发布者的三层治理保证了自动化流程不会因权限过散而失控。七、发布前的质量闸门测试体系一览在版本被允许发布之前必须通过完整的测试闸门。Releasejob 通过needs: [UnitTests, OtherTests]依赖前面两个 job任何一项失败都会阻断发布。完整的本地验证命令为见 package.json 的 scriptsnpm test该命令实际串联了build:reset清理编译产物→build:docs构建文档与示例→test:specsCommonMark/GFM 规范测试→test:unit单元测试→test:umdUMD 打包产物测试→test:cjsCommonJS 兼容测试→test:types类型声明测试→test:lintESLint 检查。规范测试的语料分布在与发布策略直接相关的目录中见 docs/CONTRIBUTING.md 的测试矩阵说明目录验证目标test/specs/commonmarkCommonMark 规范合规test/specs/gfmGFM 规范合规test/specs/new非原始 markdown.pl 的新增行为test/specs/original与原始 markdown.pl 行为对照test/specs/redos正则拒绝服务ReDoS漏洞防护这与版本规则中的Patch 版本使 Marked 更接近规范合规形成闭环规范测试的推进是 patch 版本的合法触发源而任何规范层面的破坏性偏离则要求 major 版本。八、实践要点与常见误区综合原文档与仓库实现参与 Marked或借鉴其模式的同类项目版本发布时有以下要点提交即版本决策一次合并的提交信息决定了下次版本号因此务必使用 Conventional Commits 前缀feat:、fix:、perf:、docs:等破坏性变更使用BREAKING CHANGE或!标记。不要在 PR 中手动修改版本号版本号由 semantic-release 自动管理手工改动会在发布时被覆盖还可能污染提交历史。理解 Node.js 支持与版本号解耦Node 版本支持窗口收窄不等于 major 版本递增判断依据只有公共 API 是否破坏与规范是否偏离。master 常绿合并策略固定为 Squash and merge避免在master上出现中间状态提交确保任何时刻的master都满足可发布条件。发布失败时先看测试闸门Releasejob 依赖单元测试、规范测试、UMD/CJS/类型测试与 lint 全部通过任何 red 状态都会阻止 semantic-release 执行。以上流程均可在当前仓库中直接核验发布配置见 .releaserc.jsonCI 编排见 .github/workflows/tests.yml版本注入实现见 esbuild.config.js版本声明与脚本入口见 package.json发布者治理规则见 docs/AUTHORS.md。对于希望为 Marked 贡献代码的开发者可进一步阅读 docs/CONTRIBUTING.md 了解提交前的完整流程。【免费下载链接】markedA markdown parser and compiler. Built for speed.项目地址: https://gitcode.com/gh_mirrors/ma/marked创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考