开发工具CLI文档【免费下载链接】conventional-changelogGenerate changelogs and release notes from a projects commit messages and metadata.项目地址https://gitcode.com/gh_mirrors/co/conventional-changelog点击查看免费下载本文以 packages/conventional-changelog-writer/CHANGELOG.md 为主线结合conventional-changelog-writer包的源码writers.ts、options.ts、commit.ts、context.ts 等系统梳理该包从独立仓库时期v1.x2016 年到 monorepo 化v2.0.02017 年再到 TypeScript 重写v8.0.02024 年与渲染函数替换v9.0.02026 年的完整演进史并逐项讲解当前版本的 API、CLI 用法与全部配置项。一、包定位conventional-changelog-writer 在工具链中的角色conventional-changelog-writer是 conventional-changelog 生态中负责把结构化 commit 数据渲染成 Markdown 变更日志的核心渲染层。它的上游是conventional-commits-parser把原始 commit message 解析成结构化对象下游则是直接生成CHANGELOG.md文本。README 对其功能的描述只有一句话——Write logs based on conventional commits and templates基于 Conventional Commits 与模板编写日志但整个包的能力远不止于此提供流式、异步迭代器、整串三种使用形态见 writers.ts内置 commit 分组、排序、日期格式化、revert 过滤、上下文推导等默认逻辑支持通过transform、generateOn、template、各 partial 渲染函数实现完全定制化输出附带一个可直接消费行分隔 JSONLDJSON的 CLI 工具。二、版本演进主线从模板字符串到渲染函数CHANGELOG.md 记录了从 v0.42015 年到 v9.2.12026 年的完整历史。以下是决定架构走向的几个关键节点2.1 独立仓库时期v1.x2016 年v1.0.02016-02-05首个正式发布。此前的 v0.x 阶段奠定了核心概念doFlush、generateOn、notes、transform等选项已具雏形。v1.1.0generate时把originalCommits作为最后一个参数传入。v1.4.0/v1.4.1context 在repoUrl存在时自动回退并使用它做引用链接auto link references。2.2 并入 monorepo 与 2.0.0 大重构2017 年v2.0.0 是第一个里程碑式破坏性版本CHANGELOG 中列出的变更揭示了当时的设计决策context.host不再能改变context.linkReferences的默认值——如果 host 未知context.host为undefined所有链接将直接使用context.repositorycloses更名为referencesnotes对象从键值对象改为数组每个 note 形如{ title: BREAKING AMEND, text: some breaking change }options.replacements更名为options.map且可以接受函数commitGroupsCompareFn→commitGroupsSort、commitsCompareFn→commitsSort、noteGroupsCompareFn→noteGroupsSort、notesCompareFn→notesSortversion不再是必需字段移入context对象若最后一个 commit 中带版本号会覆盖它默认排序函数从按字典序改为localeCompareoptions.hashLength、options.maxSubjectLength、options.map被废弃统一收进options.transformcontext暴露finalizeContext允许在最后阶段修改 context。2.3 统一版本节奏期v3-v72018-2023 年v3.0.02018-01-29重构 release 标题生成逻辑所有标题层级统一为##h2patch 版本标题用small包裹以保持视觉层级目的是更好地兼容屏幕阅读器与 Markdown 解析器对应 issue #214。v4.0.02018-05-29从 header 模板中移除锚点标签并明确建议消费者使用版本对应的完整 release 页面 URLpermalink而非依赖可能不存在的锚点。v5.0.02020-12-30排序时不再支持嵌套对象属性nested object properties并移除compare-func依赖使排序结果在不同 Node 版本间保持一致。v6.0.02023-06-06要求 Node 14并尽可能从依赖中移除 lodash。v7.0.02023-08-26要求 Node 16使用Intl.DateTimeFormat替代dateformat统一各 preset 的接口preset 均导出配置工厂函数transform异步处理器得到修复。2.4 TypeScript 重写与 ESM 化v8.0.02024 年v8.0.0 是近年来影响最大的一次破坏性发布重写为 TypeScriptPR #1150conventional-changelog-writer与conventional-commits-filterPR #1178同步 TS 化除gulp-conventional-changelog外所有包均为 ESM-onlyPR #1144从 CommonJS 迁移要求Node 18新增formatDate选项PR #1189关闭 issue #1186与timeZone选项PR #1162修复了 Date 对象防修改逻辑PR #1285preventModifications的 Proxy 在 getter 中遇到Date实例时直接返回原值避免把 Date 包进不可变代理导致格式化失败见 commit.ts8.1.0 起transformCommit方法与相关 utils 被加入导出PR #13508.2.0 新增skip选项可在写 changelog 时跳过指定 commitPR #1346关闭 issue #1179 与 #3428.3.0 统一各 preset 的换行格式并从simple-libs引入工具函数8.4.0 把 hbs 模板内联为代码字符串。2.5 v9.0.0渲染函数取代 Handlebars2026 年v9.0.0 是当前最新的大版本两项破坏性变更直接重塑了定制方式Handlebars 模板字符串与 partial 文件被替换为渲染函数render functionsPR #1477template、headerPartial、commitPartial、footerPartial、preamblePartial不再是 hbs 字符串而是接收 context 并返回字符串或 Promise 的函数见 types/options.ts 中TemplateFunction的定义。要求 Node.js 22 或更新版本PR de5e136。v9.1.0 支持 changelog 前言的 partialpreamblePartialPR #1491v9.2.0 把 CLI 参数解析从meow换成argue-cliPR #1505v9.2.1 修复了 host URL 路径拼接问题PR #1534关闭 issue #986。三、当前版本 API三种调用形态conventional-changelog-writer对外暴露三种写入方式实现于 writers.ts3.1writeChangelogString最直接的整串输出README 给出的最小示例即此形态。输入是conventional-commits-parser解析后的 commit 数组输出是完整 changelog 字符串import { writeChangelogString } from conventional-changelog-writer // commits parsed by conventional-commits-parser const commits [/* ... */] const context { version: 1.0.0, host: https://github.com, owner: conventional-changelog, repository: conventional-changelog } console.log(await writeChangelogString(commits, context)) /* ## 1.0.0 (2015-05-29) ### Features * **ng-list:** Allow custom separator ([13f3160](https://github.com/...)) ... */其实现writers.ts只是对异步迭代器形态做拼接累加底层仍是writeChangelog。3.2writeChangelog异步生成器async generator返回一个(commits) AsyncGeneratorstring函数逐个 yield 每个版本区块的 changelog 文本。第三个参数includeDetails为true时yield 的不再是纯字符串而是DetailsCommit对象export interface DetailsCommit extends CommitKnownProps CommitKnownProps { log: string keyCommit: Commit | null }见 types/index.ts——log是渲染结果keyCommit是触发本区块生成的关键 commit通常是携带版本号的提交。3.3writeChangelogStreamTransform 流Transform.from(writeChangelog(...))一行代码把生成器包装成 Node.js Transform 流writers.ts便于与pipeline、stdin/stdout等流式场景组合。3.4 核心工作流从 writers.ts 的生成器实现可以还原完整处理流水线getFinalOptions(options)合并默认选项见下节getFinalContext(context, finalOptions)推导最终 context对每个 commit 调用transformCommit(chunk, transform, finalContext, finalOptions)——先经preventModifications包裹为不可变代理再交给 transform 函数返回值patch与原始 commit 合并并把raw指向原始 commitcommit.ts若skip?.(keyCommit)返回 true则跳过该 commitgenerateOn(keyCommit, commitsGroup)判定是否该生成一个 changelog 区块默认实现是commit.version 是合法 semver 时生成见 options.ts命中的 commit 累积到commitsGroup由createTemplateRenderer渲染出文本块最终按doFlush/reverse语义决定是否 yield。注意reverse语义正常顺序是时间倒序最新在前reverse: true则按时间正序处理——对应 types 注释normal order means reverse chronological order。四、配置项全解析Options Reference当前版本的完整配置项定义在 types/options.ts默认值在getFinalOptionsoptions.ts中集中给出。下表是全部可配置项配置项类型默认值说明groupBykeyof Committype按哪个字段对 commit 分组设为 falsy 则不分组commitsSort字段名 | 字段名数组 | 比较函数headercommit 组内排序falsy 则不排序commitGroupsSort同上无分组之间的排序notesSort同上textnote 的排序noteGroupsSort同上titlenote 分组的排序ignoreRevertedbooleantrue是否忽略被 revert 的 commit借助conventional-commits-filter的filterRevertedCommitsSync见 context.tsreversebooleanfalsetrue 时按时间正序chronological处理doFlushbooleantrue是否把最后一段可能为空的commit 冲刷输出从 v0.5.0 引入transform函数defaultCommitTransform变换 commit返回 patch 对象与原始 commit 合并返回 falsy 值则该 commit 被忽略generateOn函数 | 字段名 |nullcommit Boolean(semverValid(commit.version))判定何时生成 changelog 区块字符串形式表示该字段存在即生成非函数非字符串则永不生成见 options.tstemplate渲染函数内置 template把准备好的 context 渲染成文本v9 起为函数而非 hbs 字符串headerPartial渲染函数内置渲染 release 标题preamblePartial渲染函数内置渲染 release 标题之后的引言文本v9.1.0 新增支持commitPartial渲染函数内置渲染单条 commit 条目footerPartial渲染函数内置渲染 release 底部 notesfinalizeContext函数恒等函数渲染前最后一次修改 context 的机会接收(context, options, filteredCommits, keyCommit, commits)debug(message) voidnoop输出调试信息默认会打印最终 contextYour final context is: ...见 context.tsformatDate(date) stringyyyy-mm-dd格式v8.0.0 新增默认实现取toISOString().slice(0, 10)见 utils.tsskip(commit) boolean无v8.2.0 新增返回 true 则跳过该 commit 的写入几个容易忽略的实现细节排序统一走createComparator字符串字段名会被编译成(a[key] || ).localeCompare(b[key] || )字段名数组则逐字段拼接后比较也可直接传自定义比较函数utils.ts。这正是 v5.0.0 起不再支持嵌套对象属性的原因。默认 transform 的裁剪行为defaultCommitTransform会把 hash 截断为前 7 位、header 截断为前 100 个字符并用formatDate格式化committerDate注意用的是 committerDate 而非 authorDate这一约定自 v2.0.0 起确立见 options.ts。linkReferences 的自动推导只要linkReferences不是显式 boolean、且同时存在repository/repoUrl与commit/issue就会自动置为 truecontext.ts这是 v0.4.1/v1.4.x 时期linkReferences 与 host 无关这一破坏性变更的延续。isPatch推断若 context.version 是合法 semver会据此推导isPatchsemver.patch(version) ! 0见 context.ts。版本号非必需version不是必需字段v2.0.0 起移入 context若 keyCommit 上带版本号会覆盖 context 中的版本——这与generateOn的默认 semver 判定共同支撑一个 commit 对应一个 release 区块的模型。五、CLI 使用指南包内自带 CLI 入口src/cli/index.ts可直接消费行分隔 JSON 文件或 stdinUsage conventional-changelog-writer path [path ...] cat path | conventional-changelog-writer Example conventional-changelog-writer commits.ldjson cat commits.ldjson | conventional-changelog-writer Options -c, --context A filepath of a json that is used to define template variables -o, --options A filepath of a javascript object that is used to define options参数解析由argue-cli完成v9.2.0 起替换原meow-c, --context指向一个 JSON 文件内容作为模板变量context-o, --options指向一个 JavaScript 对象文件.json或可导入的模块loadDataFile依据扩展名决定JSON.parse还是动态import见 cli/utils.ts位置参数为 commit 文件列表每个文件按JSON.parse解析单条 commit 对象若未提供且 stdin 非 TTY则从 stdin 按 LDJSON 流式读取parseJsonStream。内部实现通过pipeline(inputStream, writeChangelog(context, options), process.stdout)把解析流、生成器与 stdout 串起来任何错误都会打印并process.exit(1)。测试夹具中的 commits.ldjson 与 context.json 可直接作为 CLI 输入的参考样例。六、配套测试与验证包的测试覆盖了以上全部行为可在仓库中直接查阅writers.spec.ts验证三种 API 的输出、includeDetails、doFlush、reverse等生成语义commit.spec.ts验证 transform 的异步处理、falsy 返回值忽略 commit、不可变代理包括 Date 特殊处理等context.spec.ts 与 options.spec.ts见 utils.spec.ts验证分组、排序、日期格式化、比较器编译template.spec.ts验证渲染函数模板与 partial 的组合CLI 相关测试见 cli/index.spec.ts。七、迁移要点与实战建议针对 CHANGELOG 中列出的各破坏性变更升级到 v9 时需注意Node 版本v9 要求 Node 22v8 要求 Node 18v7 要求 Node 16按需选择匹配版本ESM-onlyv8 起包只能通过import使用CommonJS 项目需改用动态import()或升级构建模板改写v9 起把 hbs 字符串模板含 partial 文件改写为渲染函数——这是迁移工作量最大的部分函数签名均为(context) string | Promisestring排序与选项名v5 起排序不再支持嵌套属性、按localeCompare比较v2 起的commitsSort/commitGroupsSort/notesSort/noteGroupsSort命名沿用至今不要使用旧的*CompareFn命名定制入口收敛hashLength/maxSubjectLength/map等旧选项早已废弃统一在transform内实现需要按 commit 粒度过滤请用skipv8.2.0需要整体跳过 revert 提交请保持ignoreReverted: true。从 v0.4 到 v9.2.1 的十年演进中conventional-changelog-writer经历了模板字符串 → 内联 hbs → 渲染函数的模板机制迭代、CJS → ESM的模块体系迁移、JS → TypeScript的类型化改造以及依赖面的持续瘦身移除 lodash、compare-func、meow。理解这份 CHANGELOG等于同时掌握了该包全部配置项的来历、默认值与最佳实践。赞分享开发工具CLI文档【免费下载链接】conventional-changelogGenerate changelogs and release notes from a projects commit messages and metadata.项目地址https://gitcode.com/gh_mirrors/co/conventional-changelog点击查看免费下载相关推荐从 v1 到 v6next-forge 版本演进全解析Changelog 深度导读从 v1 到 v6next forge 版本演进全解析Changelog 深度导读 本篇以 next forge 仓库的 CHANGELOG.md htt前端后端示例工程CLIhighlight.js 版本演进全解析从 CHANGES.md 解读 v9 到 v11 的架构变迁与升级路径highlight.js 版本演进全解析从 CHANGES.md 解读 v9 到 v11 的架构变迁与升级路径 本文以开源仓库 highlight.js ht前端Ionic Framework ionic/core 版本演进全解从 v6 到 v9 的 CHANGELOG 深度导读Ionic Framework ionic/core 版本演进全解从 v6 到 v9 的 CHANGELOG 深度导读 本篇技术指南以开源仓库 gh_mir前端移动开发跨平台上一篇如何优化Doom3.gpl的内存管理与资源加载开发者必看的终极指南下一篇Whisper.cpp终极指南高性能离线语音识别的颠覆性解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
