从 CHANGELOG 到发布管线:@browser-logos/tor-nightly 版本演进与 browser-logos 的包发布机制解读

原创2026-10-15 12:09:581,770 阅读
文章标签:前端

从 CHANGELOG 到发布管线:@browser-logos/tor-nightly 版本演进与 browser-logos 的包发布机制解读

@browser-logos/tor-nightly 是 browser-logos 仓库中以 npm 包形式独立发布的 Tor Nightly 浏览器 Logo 资源包。本文以仓库内的 src/tor-nightly/CHANGELOG.md 为叙事主线,逐条还原该包从 1.0.0 到 1.0.4 的五次版本变更,并结合 scripts/release.js、scripts/prepare-for-publishing.js 等源码,说明这份 changelog 是如何被自动化生成、版本号背后的 semver 规则如何推导,最后给出通过 npm、Yarn 与 cdnjs 获取该 Logo 的完整实操方式。读完本文,你将掌握 browser-logos 仓库"单浏览器一目录、单浏览器一 npm 包"的组织方式,以及其发布工程的全貌。

tor-nightly 包在 browser-logos 仓库中的定位

browser-logos 仓库以「每个浏览器一个目录」的方式组织 Logo 资源。当前活跃的 Logo 统一放在 src/ 下,每个子目录(如 tor-nightly)都包含以下四类文件:

  • README.md:展示 Logo 图片,并给出安装/获取方式;
  • CHANGELOG.md:记录该包的版本发布历史;
  • package.json:声明 npm 包元信息(包名、版本、关键词、仓库位置等);
  • 一组 PNG:一张原始主图加上 8 个不同尺寸的成品图。

在 src/README.md 的 Tor 章节中,tor、tor-alpha、tor-nightly 三个包并列展示,说明 Tor Nightly 作为 Tor 浏览器的夜间构建渠道,在仓库中被视为一个独立的当前活跃 Logo 源。其 package.json 中的关键字段如下:

{
  "name": "@browser-logos/tor-nightly",
  "description": "Tor Nightly browser logo",
  "version": "1.0.4",
  "keywords": ["browser-logos", "logo", "tor-nightly", "tor-nightly-logo"],
  "repository": {
    "type": "git",
    "directory": "src/tor-nightly",
    "url": "https://github.com/alrra/browser-logos.git"
  },
  "homepage": "https://github.com/alrra/browser-logos",
  "bugs": "https://github.com/alrra/browser-logos/issues"
}

当前 version 为 1.0.4,与 CHANGELOG 最新一条记录完全对应,说明 package.json 与 CHANGELOG.md 之间保持着版本同步。

版本演进时间线:1.0.0 到 1.0.4

src/tor-nightly/CHANGELOG.md 记录了从 2019 年 7 月到 2020 年 7 月共五个版本。将各版本信息整理为下表:

版本 发布日期 变更类型 变更内容 对应提交
1.0.0 2019-07-17 ✨ 新特性 包首次发布(初始 npm 发布) —
1.0.1 2019-08-27 🔧 改进 在 package.json 中指定包所在目录 3799655cbd
1.0.2 2019-10-13 📚 文档 增加通过 Yarn 安装的说明 8fab53c254
1.0.3 2019-11-30 📚 文档 移除 cdnjs 使用推荐 896ab303b4
1.0.4 2020-07-11 📚 文档 重新加入 cdnjs 使用推荐 a94987f297

从变更类型看,除 1.0.0 的初始发布属于"新特性"外,其余四次都属于"缺陷修复/改进"(Bug fixes / Improvements)。这五次变更对应了包发布生命周期中的典型工程动作:首次发布 → 修正包元数据 → 补齐安装文档 → 调整分发渠道推荐。下面逐一展开。

v1.0.0:初始发布与包生成机制

CHANGELOG 中 1.0.0 的正文只有一个 ✨ 符号。结合 scripts/prepare-for-publishing.js 可以还原这个符号的来历:该脚本负责把仓库中的某个浏览器目录"准备为可发布的 npm 包",它会自动生成 package.json 与 README.md 两个文件(见 createPackageJSON 与 createReadme)。

具体生成逻辑包括:

  • 以目录名 tor-nightly 推导 npm 包名 @browser-logos/tor-nightly;
  • 以 prettifyName 将 tor-nightly 转为展示名 "Tor Nightly",并拼出描述字段 "Tor Nightly browser logo";
  • 通过 git log 取该目录最近一次提交的 SHA,写入 README 中图片的固定版本引用;
  • 将 version 初始化为 1.0.0,并保留 "private": true 占位(防止误发布),同时把 release notes 初始值设为 ✨——这正是 CHANGELOG 中 1.0.0 那条 ✨ 的来源(见 updateChangelog 对未发布包的处理分支)。

与之配套的图片产物由 scripts/generate-images.sh 生成:脚本以目录内的主图(tor-nightly.png,955×955)为源,用 ImageMagick 的 convert 配合 Sinc/Jinc 高质量缩放参数,批量输出 8 个固定尺寸(16、24、32、48、64、128、256、512,见 IMAGE_SIZES 定义)。因此 src/tor-nightly/ 下最终呈现为"1 张主图 + 8 张规格图"的结构。

v1.0.1:修复 package.json 的 directory 字段

1.0.1 的变更描述是"在 package.json 文件中指定包的目录"。该修复落实为 package.json 中的 repository.directory 字段,其值为 "src/tor-nightly"。

这一字段对 npm 生态有两个实际作用:

  • 告诉 npm 该包的源码位于 monorepo 的哪个子目录,方便溯源与 issue 定位;
  • 配合 repository.url(https://github.com/alrra/browser-logos.git),可被工具自动拼接出指向该目录的浏览地址。

在 prepare-for-publishing.js 的模板中,directory 由 data.packagePath(即包所在目录路径)直接填充,可见该字段是从生成环节就被设计好的规范字段。CHANGELOG 中该条目的提交前缀为 3799655cbd。

v1.0.2:补齐 Yarn 安装说明

1.0.2 的变更是在文档中增加"如何通过 Yarn 安装"的说明,对应提交 8fab53c254。该说明最终固化在 src/tor-nightly/README.md 的 "How to get the logo" 一节中:

# 通过 npm 安装为 devDependency
npm install --save-dev @browser-logos/tor-nightly

# 通过 Yarn 安装为 devDependency
yarn add --dev @browser-logos/tor-nightly

两点实操说明:

  • 两个命令都使用 --save-dev/--dev 将包写入 devDependencies,符合 Logo 资源常用于构建期(文档站点、演示项目)而非运行时依赖的定位;
  • 仓库根目录的 README.md 中同样保留了通配形式 npm install --save-dev @browser-logos/<logo>,各浏览器包共用同一套安装范式。

v1.0.3 与 v1.0.4:cdnjs 推荐的移除与回归

1.0.3(2019-11-30,提交 896ab303b4)将 README 中的 cdnjs 使用推荐移除,CHANGELOG 中关联了 issue #181;1.0.4(2020-07-11,提交 a94987f297)又重新加入"使用 cdnjs"的推荐。两次变更叠加后,当前 README.md 的获取方式即「npm / Yarn / cdnjs」三者并列:

You can either:

  • Install it using npm / Yarn
  • Use cdnjs

cdnjs 作为 browser-logos 全库的公共 CDN 分发渠道,可以免安装、直接通过 URL 引用任意尺寸的 PNG。需要说明的是:README 中指向 cdnjs 库页面的链接为外部地址,本文不展开其内容;从仓库证据看,仅能确认该推荐在 1.0.3→1.0.4 之间存在一次"移除—回归"的文档调整。

CHANGELOG 的自动化生成机制:release.js 源码解读

tor-nightly 的 changelog 并非手写维护,而是由 scripts/release.js 在每次发版时自动生成。理解这份 changelog 的格式,关键在于三个机制。

1. 提交 emoji 标签 → 变更分节

release.js 依据 commit message 首字符的 emoji 对提交归类(见 getChangelogData):

Emoji 归入章节 语义
💥 Breaking Changes 破坏性变更
🐛 📚 🔧 🗜 Bug fixes / Improvements 缺陷修复/改进(含文档)
✨ New features 新特性
🚀 仅根包使用的发布提交 版本发布

tor-nightly 的 1.0.1~1.0.4 都落在 🔧/📚,因此它们在 changelog 中都出现在 "### Bug fixes / Improvements" 小节下;1.0.0 的 ✨ 则属于初始发布标记。

2. semver 版本号推导

getChangelogData 同时承担版本号决策:存在破坏性变更 → 升 major;存在新特性 → 升 minor;否则 → 升 patch。tor-nightly 四次后续版本均为文档/元数据改进,故版本号按 1.0.0 → 1.0.1 → 1.0.2 → 1.0.3 → 1.0.4 的 patch 递增路径演进,与 CHANGELOG 记录完全吻合。

3. changelog 文件格式与写入

文件头部固定为 8 行(含 <!-- markdownlint-disable line-length --> 注释),随后是 <版本号> (<日期>) 标题行与正文(见 getReleaseNotes 对结构的注释)。发版时 updateChangelog 将新版本内容插入头部之后、旧内容之前。这也是为什么每条变更都带有 <a href="https://link.gitcode.com/i/b58f735faa28a1ec0810ccf0207a8e18" target="_blank">提交前缀] - 变更描述 (by 作者 / see also: issue) 这种统一格式——它由 [prettyPrintCommit 从 commit 信息(作者、关联 issue)自动拼装。

4. 发布任务序列

getTasks(scripts/release.js)定义了单个包的完整发布流水线:获取自上次发布以来的 commit → 生成 release notes 与 semver 增量 → 更新 package.json 版本号 → 更新 README → 更新 CHANGELOG → 人工复核 → 提交变更 → 发布到 npm(含 OTP 二次验证)→ 推送到远端。因此本文开篇那张版本时间线表格,本质上就是该流水线在 tor-nightly 包上运行五次的产物。

获取 tor-nightly Logo 的完整方式

综合 src/tor-nightly/README.md 与仓库根 README.md,获取该 Logo 有三种途径:

  1. npm 安装:npm install --save-dev @browser-logos/tor-nightly;
  2. Yarn 安装:yarn add --dev @browser-logos/tor-nightly;
  3. cdnjs:通过 browser-logos 库的公共 CDN 直接引用(无需安装)。

安装后,包内包含 9 张 PNG:tor-nightly.png(955×955 主图)以及 _16x16、_24x24、_32x32、_48x48、_64x64、_128x128、_256x256、_512x512 八个规格图,可满足从 favicon(16px)到高分辨率展示(512px)的不同场景需求。所有图片均为透明背景的高分辨率素材,可直接用于演示文档、技术博客或站点资源。

结语

一份只有 5 条记录的 CHANGELOG,背后是 browser-logos 仓库一整套"单浏览器一目录、一目录一 npm 包"的工程约定:prepare-for-publishing.js 负责包骨架生成,generate-images.sh 负责多尺寸图片产物,release.js 负责按 emoji 标签归类变更、推导 semver 并自动写入 changelog。从 @browser-logos/tor-nightly 的版本时间线,可以完整观察到 npm 包从首次发布到文档完善、分发渠道调整的典型生命周期。如果你在维护类似的"资源型 monorepo",这套"目录即包、脚本即管线"的做法值得直接借鉴。

进一步阅读:完整 changelog 见 src/tor-nightly/CHANGELOG.md;发布脚本见 scripts/release.js;包生成模板见 scripts/prepare-for-publishing.js;多尺寸图片生成逻辑见 scripts/generate-images.sh。

登录后查看全文
browser-logos