plotly.js 的 Draftlog 机制：用 PR 编号命名的 CHANGELOG 草稿如何驱动版本发布记录
plotly.js 的 Draftlog 机制用 PR 编号命名的 CHANGELOG 草稿如何驱动版本发布记录【免费下载链接】plotly.jsOpen-source JavaScript charting library behind Plotly and Dash项目地址: https://gitcode.com/GitHub_Trending/pl/plotly.jsplotly.jsOpen-source JavaScript charting library behind Plotly and Dash采用了一套轻量但严谨的变更日志CHANGELOG管理约定每个 Pull Request 都必须在draftlogs/目录下提交一个以 PR 编号命名的 Markdown 草稿文件由 CI 强制校验最终在发版时被汇总进 CHANGELOG.md。读完本文你将掌握 draftlog 的完整命名规范、内容格式、豁免流程以及 CI 检查脚本与发版汇总脚本use_draftlogs.js背后的实现细节从而能正确地为任何 plotly.js PR 撰写并通过 draftlog 检查。目录定位为下一次发布准备 CHANGELOG 的草稿区draftlogs/README.md 开宗明义地说明了该目录的用途存放草稿日志draft logs用于帮助准备即将到来的 CHANGELOG。每个 PR 都应向该目录添加至少一个 Markdown 文件。draftlog 与 CHANGELOG.md 的关系是草稿—成品草稿文件在 PR 合并前就写入仓库在版本发布时由维护者运行汇总脚本一次性合入 CHANGELOG之后再清空草稿区如此循环。从仓库结构看这套机制的闭环由四部分组成环节位置职责规范文档draftlogs/README.md定义文件名、内容格式与豁免流程CI 强制检查.github/workflows/check-draftlog.yml校验 PR 是否新增合法命名的 draftlog 且包含自引用链接发版汇总脚本tasks/use_draftlogs.js读取所有草稿按分类追加到 CHANGELOG 的UNRELEASED段草稿清空脚本tasks/empty_draftlogs.js发版后删除draftlogs/下所有以数字开头的文件其中draftlogs/路径常量与CHANGELOG.md路径常量统一在 tasks/util/constants.js 中定义pathToDraftlogs、pathToChangelog两个脚本共用保证读写同一目录。文件名规范PR 编号 变更类型后缀README 规定文件名必须以 PR 编号开头后跟五个变更类型后缀之一后缀含义汇总到 CHANGELOG 的小节NNNN_fix.md提议一个 bug 修复### FixedNNNN_add.md提议一个新功能### AddedNNNN_remove.md提议移除某个功能### RemovedNNNN_change.md提议一个 minor/major 变更### ChangedNNNN_deprecate.md提议废弃某个功能### Deprecated如果同一个 PR 跨越多个类别——例如既添加了新功能又修改了现有功能——README 明确要求把不同类别分别写在单独的文件中而不是塞进一个文件。这个五分类并非仅存在于文档。发版脚本 tasks/use_draftlogs.js 中有一个一一对应的分发逻辑if(filename.endsWith(_add.md)) { all.Added.push(message); } else if(filename.endsWith(_remove.md)) { all.Removed.push(message); } else if(filename.endsWith(_deprecate.md)) { all.Deprecated.push(message); } else if(filename.endsWith(_change.md)) { all.Changed.push(message); } else if(filename.endsWith(_fix.md)) { all.Fixed.push(message); } else { skippedFiles.push(filename); }也就是说后缀名直接决定该条目最终出现在 CHANGELOG 的哪个分类小节下后缀不匹配任何类别的文件会被记入skippedFiles脚本结束时以 JSON 报错抛出迫使维护者修正文件名。CI 侧的校验正则与之一致。check-draftlog.yml 第 56 行用如下正则验证新增文件名^draftlogs/${PR_NUMBER}_(fix|add|remove|change|deprecate)\.md$任何不符合该模式的新增文件都会被判定为INVALID_NAMES并让检查失败。内容格式以动词开头的 changelog 条目 PR 自引用链接README 给出了针对为 5546 号 PR 添加新功能的完整示例文件名5546_add.md文件内容- Add icicle trace type [[#5546](https://github.com/plotly/plotly.js/pull/5546)]渲染效果即为一行带 PR 链接的 changelog 条目。README 还附了两条书写要求以动词开头无论是单行还是多行消息都要求句子以动词起头Add、Fix、Remove、Deprecate 等这与 CHANGELOG.md 中既有条目的风格完全一致必须回链自身 PR每条条目必须包含指向自己 PR 的链接形式为[[#1234](https://github.com/plotly/plotly.js/pull/1234)]指向/issues/1234的链接也被接受因为 GitHub 会在两者之间重定向。文件名中的编号、#1234标签、URL 三处必须是同一个 PR 编号。这一条同样是机器可校验的。CI 检查脚本在确认存在新增草稿后会用gh api拉取每个草稿文件在 PR head SHA 上的原始内容并用正则验证是否包含自引用链接\[\[#${PR_NUMBER}\]\(https://github\.com/plotly/plotly\.js/(pull|issues)/${PR_NUMBER}\)\]正则在(pull|issues)处做了兼容正好对应 README 中issues 链接也可接受的说明。缺失链接的文件会被列出并报Draftlog entry(ies) missing a link to this PR错误。CI 强制检查check-draftlog 工作流的完整流程draftlogs/README.md 提到CI 检查强制每个 PR 都新增一个draftlogs/下的文件其实现位于 .github/workflows/check-draftlog.yml。逐层拆解该工作流触发条件pull_request事件的opened、reopened、synchronize、labeled、unlabeled、ready_for_review六种动作。把labeled/unlabeled纳入触发是为了让维护者事后补打/撤掉no-draftlog标签时检查能重新运行concurrency组按 PR 编号隔离并cancel-in-progress: true保证同一 PR 只保留最新一次检查。跳过 draft 状态 PRjob 级if: github.event.pull_request.draft false只对非草稿状态的 PR 执行。第一步检查no-draftlog标签。脚本读取 PR 的 labels JSON若命中no-draftlog则输出skiptrue后续步骤整体跳过。第二步校验新增草稿文件未跳过时执行依次做三件事通过gh api --paginate /repos/$REPO/pulls/$PR_NUMBER/files列出本 PR 状态为added的文件过滤出draftlogs/前缀且排除draftlogs/README.md本身避免修改规范文档被误算若结果为空报错No new draftlog entry was added under draftlogs/并给出豁免提示用上述五后缀正则校验文件名合法性非法文件名逐个列出并报错逐个拉取草稿文件内容校验 PR 自引用链接是否存在缺失者逐个列出报错。三步全部通过后输出Found new draftlog entry(ies):及文件清单检查成功。这个检查也写进了 PR 模板 PULL_REQUEST_TEMPLATE.md 的开发者清单中should create a new small markdown log file using the PR number e.g.1010_fix.mdor1010_add.mdinsidedraftlogsfolder ... A CI check enforces this与 README 形成文档层面的双重约束。豁免流程no-draftlog标签并非每个 PR 都值得在 CHANGELOG 中留名。README 明确说明如果你的 PR 确实不产生面向用户的变更例如仅改 CI、内部重构、文档错字修正可以给 PR 打上no-draftlog标签以豁免检查。该标签在 CONTRIBUTING.md 的标签表中也有正式登记| Label | Purpose | |no-draftlog| PR opted out of the draftlog check |在 CI 侧如前所述标签检查是check-draftlogjob 的第一个步骤命中即整链跳过。因此豁免的生效路径是维护者或有权限者给 PR 添加no-draftlog标签 → 触发labeled事件 → 工作流重新运行 → 首个步骤检测到标签并输出skiptrue→ 文件校验步骤不再执行。发版闭环use_draftlogs.js 如何把草稿并入 CHANGELOGPR 合并只是把草稿存入draftlogs/真正合入 CHANGELOG 发生在发版时。package.json 提供了两个 npm 脚本use-draftlogs: node tasks/use_draftlogs.js, empty-draftlogs: node tasks/empty_draftlogs.jsnpm run use-draftlogs的执行逻辑见 tasks/use_draftlogs.js列出draftlogs/下所有以数字开头的文件startsWithNumber过滤若无则直接退出——这与 CI 只关心 PR 编号命名的文件相呼应读取 CHANGELOG.md 全文用分隔句where X.Y.Z is the semver of most recent plotly.js release.切成头、尾两段。这句话正好出现在 CHANGELOG 开头说明如何查看下个版本包含的 commit的段落末尾读取每个草稿文件内容去掉空行split(ENTER).filter(e !!e).join(ENTER)按后缀分发到Added / Removed / Deprecated / Changed / Fixed五个桶组装新的 CHANGELOG头部说明 一个## [X.Y.Z] -- UNRELEASED新版本标题随后按Added → Removed → Deprecated → Changed → Fixed的顺序追加各分类仅输出非空分类再接原 CHANGELOG 的其余历史内容整体写回CHANGELOG.md。这个顺序与当前 CHANGELOG 的实际结构吻合文件第 12 行即为## [X.Y.Z] -- UNRELEASED占位段当前为空其下是[4.0.0] -- 2026-08-24等已发布版本每个版本内含### Added、### Removed、### Changed、### Fixed等小节。npm run empty-draftlogs则在草稿并入后清理现场tasks/empty_draftlogs.js 调用 tasks/util/make_empty_directory.js 的emptyDir仅删除draftlogs/下以数字开头的文件即草稿本身保留README.md等说明文件并重建目录。值得注意的是draftlogs/同时被 .npmignore 排除不会随 npm 包发布——它纯粹是仓库内部的协作基础设施与发布产物dist/、lib/完全隔离。一个完整的草稿工作流示例综合以上机制一个贡献者提交新增icicle类 trace功能 PR假设编号 5546时的完整流程是在本地draftlogs/目录新建5546_add.md内容为- Add icicle trace type [[#5546](https://github.com/plotly/plotly.js/pull/5546)]若该 PR 同时改动现有行为另建5546_change.md书写对应条目动词开头带同一自引用链接将草稿文件与功能代码一并 commit、pushcheck-draftlog工作流在 PR 事件上运行确认存在新增草稿 → 文件名匹配5546_(fix|add|remove|change|deprecate).md→ 内容含[#5546]链接三步通过PR 合并后草稿留在draftlogs/中等待发版维护者执行npm run use-draftlogs将其并入 CHANGELOG 的UNRELEASED段再执行npm run empty-draftlogs清空草稿区。小结plotly.js 的 draftlog 机制用极低的成本解决了大型协作项目中CHANGELOG 谁写、何时写、写在哪的经典难题变更说明随代码 PR 一起评审避免发版时翻 commit 考古命名规则与内容格式都可被 CI 正则精确校验见 check-draftlog.yml汇总与清理则由两个幂等的 npm 脚本use_draftlogs.js、empty_draftlogs.js自动完成no-draftlog标签为纯内部变更提供了干净的豁免通道。对参与 plotly.js 贡献的开发者而言掌握PR 编号 五类后缀的命名规范、动词开头的条目写法以及三处 PR 编号必须一致的链接要求是让自己的 PR 顺利通过 draftlog 检查的全部前提。【免费下载链接】plotly.jsOpen-source JavaScript charting library behind Plotly and Dash项目地址: https://gitcode.com/GitHub_Trending/pl/plotly.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考