从 CHANGELOG 到发布管线:@browser-logos/tor-nightly 版本演进与 browser-logos 的包发布机制解读
从 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 有三种途径:
- npm 安装:
npm install --save-dev @browser-logos/tor-nightly; - Yarn 安装:
yarn add --dev @browser-logos/tor-nightly; - 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。