web3.js 仓库 CHANGELOG 规范与实践基于 Keep a Changelog 与 SemVer 的自动化维护指南【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js本篇技术指南以 web3.js 仓库scripts/changelog工具链及其配套 CHANGELOG 测试夹具为切入点系统讲解该 monorepo 中每个 npm 包所遵循的变更日志CHANGELOG.md书写规范、版本区段组织方式以及「一条命令添加条目、一键同步根日志」的自动化维护流程。读完本文你将掌握 web3.js 的 CHANGELOG 文件结构约定、六大变更分类的语义、yarn changelog命令的完整用法与底层实现原理并能基于仓库中的源码与测试夹具验证每一步行为。从一份示例骨架看 web3.js 的 CHANGELOG 约定在 web3.js 仓库中scripts/changelog/test/fixtures/mock_packages_directory/mock-package-1/CHANGELOG.md是一份被单元测试反复使用的真实夹具。它表面上是某个 mock 包的变更日志实际承载的是 web3.js 全仓库统一的 CHANGELOG 格式规范任何真实包如packages/web3/CHANGELOG.md、packages/web3-eth/CHANGELOG.md都遵循同一套骨架。这份文件的整体结构可以拆解为三层头部说明# Changelog标题 All notable changes to this project will be documented in this file. 的用途声明并注明格式基于 Keep a Changelog、版本号遵循 Semantic Versioning语义化版本。模板注释块用!-- EXAMPLE ... --包裹的示例展示新增版本区块时应该书写的完整六段结构。版本区段列表从## [0.1.0-alpha.0]一路排到## [1.0.0]最后是## [Unreleased]未发布区段每个版本号下都包含六类标准变更小节。需要注意的是该夹具中的条目文案如- Ive added feature XY (#1000)均为占位内容用于测试数据比对真实包中的 CHANGELOG 则以实际变更描述为主但格式约定完全一致。六大变更分类CHANGELOG 正文的标准词汇表无论是模板注释块还是每个版本区段web3.js 的 CHANGELOG 都固定使用六类三级标题组织条目这一约定在源码中同样被硬编码。查看 types.ts可以看到ENTRY_SECTION_HEADERS数组export const ENTRY_SECTION_HEADERS [ Added, Changed, Deprecated, Removed, Fixed, Security, ];这与 mock-package-1 的 CHANGELOG.md 中每个版本区段下的小节一一对应六类的语义如下小节语义夹具示例### Added新增的功能feature- Ive added feature XY (#1000)### Changed对既有功能的修改或清理- Ive cleaned up XY (#1000)### Deprecated即将废弃但暂未移除的功能- Ive deprecated XY (#1000)### Removed已被移除的功能- Ive removed XY (#1000)### Fixed缺陷修复- Ive fixed XY (#1000)### Security安全相关改进- Ive improved the security in XY (#1000)条目本身统一采用-连字符后接三个空格开头的列表项格式并以(#PR号)结尾关联对应的 Pull Request。这一缩进约定并非偶然——sync.ts 中的解析逻辑正是通过item.startsWith(- )来识别包级 CHANGELOG 中的条目缩进格式错误会导致条目无法被工具正确归类和同步。版本区段从 alpha 到正式版的演进序列夹具中的版本区段按时间从旧到新排列展示了一个包从预发布到正式发布的典型路径## [0.1.0-alpha.0] → ## [0.1.0-alpha.1] → ## [0.1.0] → ## [0.1.1] → ## [1.0.0] → ## [Unreleased]0.1.0-alpha.0/0.1.0-alpha.1语义化版本中的预发布版本prerelease通常用于内部测试或先行体验0.1.0/0.1.10.x 阶段的正式版本其中 patch 位递增表示向后兼容的修复1.0.0主版本号升至 1标志 API 进入稳定承诺期## [Unreleased]始终悬浮在列表最顶部的待发布区记录下一个版本将会包含但尚未发布的变更。从 mock-package-2 与 mock-package-3 的夹具可以看出见 mock-package-2/CHANGELOG.md、mock-package-3/CHANGELOG.md每个 mock 包刻意设计了不同的版本演进路径和条目数量如 mock-package-3 在0.1.1和1.0.0区段有多个条目目的是让同步工具在各种复杂度输入下都能被验证正确。新增版本区段的标准做法按照夹具头部注释块!-- EXAMPLE ... --的提示当某个版本正式发布时维护者需要把## [Unreleased]下的内容整理为具体的版本号区段例如## [1.1.0]保留六类小节结构条目文案与 PR 号不变在文件顶部重新生成一个空的## [Unreleased]区段供后续变更继续累积。这样既保证了历史可追溯也让未发布变更始终有一个固定的落点供自动化工具定位。[Unreleased] 区段自动化工具的锚点## [Unreleased]在 web3.js 的工具链中扮演着核心锚点的角色。所有解析和重写逻辑都围绕这一行展开sync.ts 中的getUnreleasedSection通过parsedChangelog.findIndex(item item ## [Unreleased])定位区段起点并截取其后所有内容add_changelog_entry.ts 在写回文件时用parsedChangelog.splice(parsedChangelog.findIndex(item item ## [Unreleased]) 2)保留标题行及其后的空行然后追加重组后的条目列表——源码注释明确说明2是为了让标题、空行不被删掉同理sync.ts 在重写根 CHANGELOG 时也使用相同的2策略。从源码结构看可以推断这套设计有一个重要前提每个包和根 CHANGELOG 文件中必须恰好存在一个、且只存在于末尾之前的## [Unreleased]标题。如果文件缺失该区段findIndex会返回-1splice(-1 2)即splice(1)将导致不可预期的文件内容变化因此维护者在手写 CHANGELOG 时务必保留该区段。自动化入口yarn changelog 命令体系web3.js 将 CHANGELOG 维护封装为一条 npm script见仓库根目录 package.json 中的定义changelog: ts-node -P scripts/changelog/tsconfig.json scripts/changelog/src/index.ts命令入口 index.ts 只做一件事调用 helpers.ts 中的parseArgs读取process.argv[2]作为命令名在 types.ts 的getCommands()注册表中匹配后分发执行。注册表包含两类共七个命令命令功能sync检查./packages/下每个包的 CHANGELOG.md 中是否有尚未收录进根 CHANGELOG.md 的条目并完成同步added向指定包的 CHANGELOG.md 的### Added小节添加一条变更changed向### Changed小节添加一条变更deprecated向### Deprecated小节添加一条变更removed向### Removed小节添加一条变更fixed向### Fixed小节添加一条变更security向### Security小节添加一条变更命令名统一由ENTRY_SECTION_HEADERS小写生成见 types.ts因此分类集合在文档规范与CLI 能力两个层面完全一致。实战向包添加一条变更记录以添加一条 Added 类条目为例命令格式为yarn changelog added [packageName] [changelogEntry] # 示例 yarn changelog added web3-eth Ive added feature XY (#1000)执行流程由 add_changelog_entry.ts 中的addChangelogEntry完成核心步骤为解析配置若第一个参数以.json结尾则将其读入并解析为ChangelogConfig否则使用默认配置DEFAULT_CHANGELOG_CONFIG./packages目录、CHANGELOG.md文件名、根日志路径./CHANGELOG.md见 types.ts读取目标包日志按${packagesDirectoryPath}/${packageName}/CHANGELOG.md拼接路径并读入按换行符切分为字符串数组提取并分组 Unreleased 条目调用getPackageGroupedUnreleasedEntries见 sync.ts将## [Unreleased]区段中-开头的条目按所属的### 分类标题分组格式化并归并新条目命令名首字母大写后拼接为### Added形式的标题条目前缀-三个空格若该分类已存在则追加否则新建分类add_changelog_entry.ts扁平化重写按分类标题 → 空行 → 条目 → 空行的顺序重组 Unreleased 区段用splice清空旧内容后写入文件。用测试夹具验证行为上述行为在 add_changelog_entry.test.ts 中有直接对应的断言。两个期望文件展示了两种典型场景expected_modified_CHANGELOG.json在已有的### Added分类下追加新条目- Some new change (#42)其余五类保持原样expected_modified_CHANGELOG_2.json追加到尚不存在的分类如### Newheader时工具会新建该分类并插入条目同时保持## [Unreleased]头部完整。这两个夹具清楚地说明了追加到已有分类与创建新分类两条代码路径对应 add_changelog_entry.ts 的 if/else 分支。一键同步把各包变更汇总到根 CHANGELOGweb3.js 采用 monorepo 结构每个包packages/web3、packages/web3-eth、packages/web3-utils等都维护自己的 CHANGELOG.md而仓库根目录的CHANGELOG.md需要汇总全部包的未发布变更供发版与读者查阅。sync命令正是为此设计yarn changelog sync其实现位于 sync.ts 的syncChangelogs处理流水线为读取根CHANGELOG.md用getUnreleasedSection取出## [Unreleased]区段用 helpers.ts 的getListOfPackageNames枚举packagesDirectoryPath下所有子目录名得到包名列表对每个包调用getPackageGroupedUnreleasedEntries提取其 Unreleased 条目通过getSyncedGroupedUnreleasedEntriessync.ts把各包条目归并到根分组中分类标题用### Added这种三级标题每个包名用#### 包名这种四级标题作为子分组从而在根 CHANGELOG 中形成「分类 → 包 → 条目」的三层结构flattenSyncedUnreleasedEntriessync.ts按分类、包顺序扁平化输出保留## [Unreleased]头后重写根日志。值得注意的细节是getRootGroupedUnreleasedEntriessync.ts会通过skipSection跳过根日志中手写的### Breaking Changes区段避免破坏根日志已有的特殊说明同时只有以-开头、且在### 分类与#### 包名上下文中的行才会被归并。这些边界处理都可以在 sync.test.ts 的多个it用例中找到对应断言包括should get package unreleased section、should get root grouped unreleased entries等。自定义配置脱离默认目录结构sync与各add命令都支持传入一个自定义 JSON 配置作为首个参数以.json结尾即被识别结构如下{ packagesDirectoryPath: ./packages, packagesChangelogPath: CHANGELOG.md, rootChangelogPath: ./CHANGELOG.md }三个字段分别对应packagesDirectoryPath存放各包的目录sync会递归枚举其子目录作为包名packagesChangelogPath包内 CHANGELOG 文件名允许改成docs/CHANGELOG.md等自定义路径rootChangelogPath根汇总日志的相对路径。测试中使用的配置样例见 test_changelog_config.json它把packagesDirectoryPath指向./scripts/changelog/test/fixtures/mock_packages_directory从而让单元测试在隔离的夹具目录上安全运行不会污染真实packages/目录。小结规范与工具互为表里回看 mock-package-1 的 CHANGELOG.md它之所以采用「Keep a Changelog 风格 语义化版本 六类标准小节 固定-条目缩进 顶部[Unreleased]锚点」这套看似刻板的格式正是因为每一项约定都被 scripts/changelog 的解析与重写逻辑所依赖六类分类对应ENTRY_SECTION_HEADERS常量与七个 CLI 命令-三空格缩进是getPackageGroupedUnreleasedEntries识别条目的关键## [Unreleased]是getUnreleasedSection与splice(2)重写策略的定位锚点。对于参与 web3.js 或其他类似 monorepo 的开发者而言本文的实战价值在于先让 CHANGELOG 格式与工具约定对齐再用yarn changelog added|changed|deprecated|removed|fixed|security逐条记录变更、用yarn changelog sync汇总到根日志即可在保持人工可读性的同时把变更记录的繁琐机械劳动交给脚本完成。若需深入源码可继续研读 add_changelog_entry.ts、sync.ts 及其对应的 单元测试它们是理解这套工具链行为的最佳起点。【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 web3.js 仓库 CHANGELOG 规范与实践：基于 Keep a Changelog 与 SemVer 的自动化维护指南
web3.js 仓库 CHANGELOG 规范与实践基于 Keep a Changelog 与 SemVer 的自动化维护指南【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js本篇技术指南以 web3.js 仓库scripts/changelog工具链及其配套 CHANGELOG 测试夹具为切入点系统讲解该 monorepo 中每个 npm 包所遵循的变更日志CHANGELOG.md书写规范、版本区段组织方式以及「一条命令添加条目、一键同步根日志」的自动化维护流程。读完本文你将掌握 web3.js 的 CHANGELOG 文件结构约定、六大变更分类的语义、yarn changelog命令的完整用法与底层实现原理并能基于仓库中的源码与测试夹具验证每一步行为。从一份示例骨架看 web3.js 的 CHANGELOG 约定在 web3.js 仓库中scripts/changelog/test/fixtures/mock_packages_directory/mock-package-1/CHANGELOG.md是一份被单元测试反复使用的真实夹具。它表面上是某个 mock 包的变更日志实际承载的是 web3.js 全仓库统一的 CHANGELOG 格式规范任何真实包如packages/web3/CHANGELOG.md、packages/web3-eth/CHANGELOG.md都遵循同一套骨架。这份文件的整体结构可以拆解为三层头部说明# Changelog标题 All notable changes to this project will be documented in this file. 的用途声明并注明格式基于 Keep a Changelog、版本号遵循 Semantic Versioning语义化版本。模板注释块用!-- EXAMPLE ... --包裹的示例展示新增版本区块时应该书写的完整六段结构。版本区段列表从## [0.1.0-alpha.0]一路排到## [1.0.0]最后是## [Unreleased]未发布区段每个版本号下都包含六类标准变更小节。需要注意的是该夹具中的条目文案如- Ive added feature XY (#1000)均为占位内容用于测试数据比对真实包中的 CHANGELOG 则以实际变更描述为主但格式约定完全一致。六大变更分类CHANGELOG 正文的标准词汇表无论是模板注释块还是每个版本区段web3.js 的 CHANGELOG 都固定使用六类三级标题组织条目这一约定在源码中同样被硬编码。查看 types.ts可以看到ENTRY_SECTION_HEADERS数组export const ENTRY_SECTION_HEADERS [ Added, Changed, Deprecated, Removed, Fixed, Security, ];这与 mock-package-1 的 CHANGELOG.md 中每个版本区段下的小节一一对应六类的语义如下小节语义夹具示例### Added新增的功能feature- Ive added feature XY (#1000)### Changed对既有功能的修改或清理- Ive cleaned up XY (#1000)### Deprecated即将废弃但暂未移除的功能- Ive deprecated XY (#1000)### Removed已被移除的功能- Ive removed XY (#1000)### Fixed缺陷修复- Ive fixed XY (#1000)### Security安全相关改进- Ive improved the security in XY (#1000)条目本身统一采用-连字符后接三个空格开头的列表项格式并以(#PR号)结尾关联对应的 Pull Request。这一缩进约定并非偶然——sync.ts 中的解析逻辑正是通过item.startsWith(- )来识别包级 CHANGELOG 中的条目缩进格式错误会导致条目无法被工具正确归类和同步。版本区段从 alpha 到正式版的演进序列夹具中的版本区段按时间从旧到新排列展示了一个包从预发布到正式发布的典型路径## [0.1.0-alpha.0] → ## [0.1.0-alpha.1] → ## [0.1.0] → ## [0.1.1] → ## [1.0.0] → ## [Unreleased]0.1.0-alpha.0/0.1.0-alpha.1语义化版本中的预发布版本prerelease通常用于内部测试或先行体验0.1.0/0.1.10.x 阶段的正式版本其中 patch 位递增表示向后兼容的修复1.0.0主版本号升至 1标志 API 进入稳定承诺期## [Unreleased]始终悬浮在列表最顶部的待发布区记录下一个版本将会包含但尚未发布的变更。从 mock-package-2 与 mock-package-3 的夹具可以看出见 mock-package-2/CHANGELOG.md、mock-package-3/CHANGELOG.md每个 mock 包刻意设计了不同的版本演进路径和条目数量如 mock-package-3 在0.1.1和1.0.0区段有多个条目目的是让同步工具在各种复杂度输入下都能被验证正确。新增版本区段的标准做法按照夹具头部注释块!-- EXAMPLE ... --的提示当某个版本正式发布时维护者需要把## [Unreleased]下的内容整理为具体的版本号区段例如## [1.1.0]保留六类小节结构条目文案与 PR 号不变在文件顶部重新生成一个空的## [Unreleased]区段供后续变更继续累积。这样既保证了历史可追溯也让未发布变更始终有一个固定的落点供自动化工具定位。[Unreleased] 区段自动化工具的锚点## [Unreleased]在 web3.js 的工具链中扮演着核心锚点的角色。所有解析和重写逻辑都围绕这一行展开sync.ts 中的getUnreleasedSection通过parsedChangelog.findIndex(item item ## [Unreleased])定位区段起点并截取其后所有内容add_changelog_entry.ts 在写回文件时用parsedChangelog.splice(parsedChangelog.findIndex(item item ## [Unreleased]) 2)保留标题行及其后的空行然后追加重组后的条目列表——源码注释明确说明2是为了让标题、空行不被删掉同理sync.ts 在重写根 CHANGELOG 时也使用相同的2策略。从源码结构看可以推断这套设计有一个重要前提每个包和根 CHANGELOG 文件中必须恰好存在一个、且只存在于末尾之前的## [Unreleased]标题。如果文件缺失该区段findIndex会返回-1splice(-1 2)即splice(1)将导致不可预期的文件内容变化因此维护者在手写 CHANGELOG 时务必保留该区段。自动化入口yarn changelog 命令体系web3.js 将 CHANGELOG 维护封装为一条 npm script见仓库根目录 package.json 中的定义changelog: ts-node -P scripts/changelog/tsconfig.json scripts/changelog/src/index.ts命令入口 index.ts 只做一件事调用 helpers.ts 中的parseArgs读取process.argv[2]作为命令名在 types.ts 的getCommands()注册表中匹配后分发执行。注册表包含两类共七个命令命令功能sync检查./packages/下每个包的 CHANGELOG.md 中是否有尚未收录进根 CHANGELOG.md 的条目并完成同步added向指定包的 CHANGELOG.md 的### Added小节添加一条变更changed向### Changed小节添加一条变更deprecated向### Deprecated小节添加一条变更removed向### Removed小节添加一条变更fixed向### Fixed小节添加一条变更security向### Security小节添加一条变更命令名统一由ENTRY_SECTION_HEADERS小写生成见 types.ts因此分类集合在文档规范与CLI 能力两个层面完全一致。实战向包添加一条变更记录以添加一条 Added 类条目为例命令格式为yarn changelog added [packageName] [changelogEntry] # 示例 yarn changelog added web3-eth Ive added feature XY (#1000)执行流程由 add_changelog_entry.ts 中的addChangelogEntry完成核心步骤为解析配置若第一个参数以.json结尾则将其读入并解析为ChangelogConfig否则使用默认配置DEFAULT_CHANGELOG_CONFIG./packages目录、CHANGELOG.md文件名、根日志路径./CHANGELOG.md见 types.ts读取目标包日志按${packagesDirectoryPath}/${packageName}/CHANGELOG.md拼接路径并读入按换行符切分为字符串数组提取并分组 Unreleased 条目调用getPackageGroupedUnreleasedEntries见 sync.ts将## [Unreleased]区段中-开头的条目按所属的### 分类标题分组格式化并归并新条目命令名首字母大写后拼接为### Added形式的标题条目前缀-三个空格若该分类已存在则追加否则新建分类add_changelog_entry.ts扁平化重写按分类标题 → 空行 → 条目 → 空行的顺序重组 Unreleased 区段用splice清空旧内容后写入文件。用测试夹具验证行为上述行为在 add_changelog_entry.test.ts 中有直接对应的断言。两个期望文件展示了两种典型场景expected_modified_CHANGELOG.json在已有的### Added分类下追加新条目- Some new change (#42)其余五类保持原样expected_modified_CHANGELOG_2.json追加到尚不存在的分类如### Newheader时工具会新建该分类并插入条目同时保持## [Unreleased]头部完整。这两个夹具清楚地说明了追加到已有分类与创建新分类两条代码路径对应 add_changelog_entry.ts 的 if/else 分支。一键同步把各包变更汇总到根 CHANGELOGweb3.js 采用 monorepo 结构每个包packages/web3、packages/web3-eth、packages/web3-utils等都维护自己的 CHANGELOG.md而仓库根目录的CHANGELOG.md需要汇总全部包的未发布变更供发版与读者查阅。sync命令正是为此设计yarn changelog sync其实现位于 sync.ts 的syncChangelogs处理流水线为读取根CHANGELOG.md用getUnreleasedSection取出## [Unreleased]区段用 helpers.ts 的getListOfPackageNames枚举packagesDirectoryPath下所有子目录名得到包名列表对每个包调用getPackageGroupedUnreleasedEntries提取其 Unreleased 条目通过getSyncedGroupedUnreleasedEntriessync.ts把各包条目归并到根分组中分类标题用### Added这种三级标题每个包名用#### 包名这种四级标题作为子分组从而在根 CHANGELOG 中形成「分类 → 包 → 条目」的三层结构flattenSyncedUnreleasedEntriessync.ts按分类、包顺序扁平化输出保留## [Unreleased]头后重写根日志。值得注意的细节是getRootGroupedUnreleasedEntriessync.ts会通过skipSection跳过根日志中手写的### Breaking Changes区段避免破坏根日志已有的特殊说明同时只有以-开头、且在### 分类与#### 包名上下文中的行才会被归并。这些边界处理都可以在 sync.test.ts 的多个it用例中找到对应断言包括should get package unreleased section、should get root grouped unreleased entries等。自定义配置脱离默认目录结构sync与各add命令都支持传入一个自定义 JSON 配置作为首个参数以.json结尾即被识别结构如下{ packagesDirectoryPath: ./packages, packagesChangelogPath: CHANGELOG.md, rootChangelogPath: ./CHANGELOG.md }三个字段分别对应packagesDirectoryPath存放各包的目录sync会递归枚举其子目录作为包名packagesChangelogPath包内 CHANGELOG 文件名允许改成docs/CHANGELOG.md等自定义路径rootChangelogPath根汇总日志的相对路径。测试中使用的配置样例见 test_changelog_config.json它把packagesDirectoryPath指向./scripts/changelog/test/fixtures/mock_packages_directory从而让单元测试在隔离的夹具目录上安全运行不会污染真实packages/目录。小结规范与工具互为表里回看 mock-package-1 的 CHANGELOG.md它之所以采用「Keep a Changelog 风格 语义化版本 六类标准小节 固定-条目缩进 顶部[Unreleased]锚点」这套看似刻板的格式正是因为每一项约定都被 scripts/changelog 的解析与重写逻辑所依赖六类分类对应ENTRY_SECTION_HEADERS常量与七个 CLI 命令-三空格缩进是getPackageGroupedUnreleasedEntries识别条目的关键## [Unreleased]是getUnreleasedSection与splice(2)重写策略的定位锚点。对于参与 web3.js 或其他类似 monorepo 的开发者而言本文的实战价值在于先让 CHANGELOG 格式与工具约定对齐再用yarn changelog added|changed|deprecated|removed|fixed|security逐条记录变更、用yarn changelog sync汇总到根日志即可在保持人工可读性的同时把变更记录的繁琐机械劳动交给脚本完成。若需深入源码可继续研读 add_changelog_entry.ts、sync.ts 及其对应的 单元测试它们是理解这套工具链行为的最佳起点。【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考