OWASP Juice Shop 发布说明生成规范：图标体系、Checklist 质量门禁与分类模板实战指南

• 网络安全
• 后端

本文基于仓库.ai/skills/generate-release-notes/技能包，系统讲解 OWASP Juice Shop 发布说明（Release Notes）的结构约定、emoji 图标体系、难度星级标注、Kudos 致谢规范与三套发布模板（大版本/小版本/热修复），并深入剖析其配套的release-notes-checklist.md质量检查清单，帮助维护者、贡献者与 AI Agent 产出风格统一、可被检索与引用的高质量发布说明。

一、为什么 OWASP Juice Shop 需要一套发布说明规范

OWASP Juice Shop 是一款被广泛用于 Web 安全教学、CTF 竞赛与渗透测试训练的开源靶场应用。它维护着一个跨越 Runtime、Frontend、Challenges、UI、I18N 等多个维度的庞大仓库（当前版本为 package.json 中声明的20.1.1）。每一个新版本都可能同时包含：新增挑战、挑战难度调整、Angular 前端升级、Node.js 版本支持范围变化、翻译更新、Bugfix 与配置项增删。

面对如此复杂的变更集，如果没有统一的发布说明格式，很容易出现三类问题：

1. 分类混乱：把 UI 改动写成 Bugfix，把翻译更新塞进 Runtime，读者无法快速定位关注点；
2. 破坏性变更被忽略：挑战结构性调整可能摧毁既有 CTF 部署与通关攻略，Node.js 版本变化可能中断用户的运行环境，这些信息若不醒目提示会造成严重的社区影响；
3. 致谢与引用缺失：外部贡献者的劳动成果得不到体现，PR/commit 无法回溯。

因此，仓库在 .ai/skills/generate-release-notes/SKILL.md 中定义了完整的生成流程、图标映射与格式规则，并配套了本篇要深入讲解的 release-notes-checklist.md 作为最终质量门禁。

二、Checklist 逐项解读：发布说明的 10 条质量门禁

release-notes-checklist.md 是发布说明发布前的最终检查表，共 10 项。逐条拆解如下：

1. 免责声明（Disclaimer）

Does the release include⚡,⚠️, or📜changes? If so, is there a disclaimer blockquote at the top?

检查本次发布是否包含三类"高风险"变更，若包含则必须在发布说明顶部放置>开头的 blockquote 免责声明。例如 major.md 模板 中的标准措辞：

> This release brings significant changes to existing challenges (⚡) which might break canned CTF setups as well as solution guides made for previous versions of OWASP Juice Shop! It also contains technical breaking changes or renamings (⚠️) which might require migrating to a newer Node.js version or updating existing customization files.

三个图标对应的风险语义（依据 SKILL.md 中的 Status Icons 定义）：

2. 挑战完整列举与难度星级

Are all new challenges listed with their difficulty rating (e.g.,⭐⭐-challenge)?

所有新增挑战必须出现在发布说明中，并以难度星级标注。难度星级与 data/static/challenges.yml 中每个挑战的difficulty字段（取值 1–6）对应，由该值换算为⭐到⭐⭐⭐⭐⭐⭐的星级后缀，如模板中的写法：

* Added new <name> ⭐⭐⭐⭐⭐-challenge (kudos to @<contributor>)

在 minor.md 模板 中同样要求：

* Added new <name> ⭐⭐-challenge (kudos to @<username>)

实际仓库中的难度数据可参考 challenges.yml，例如其第 6 行、第 19 行、第 33 行等处的difficulty: 2/3/4配置，即分别对应二星、三星、四星挑战。

3. 破坏性挑战变更标记

Do breaking challenge changes have the⚡icon?

凡是可能破坏 CTF 环境与旧版通关攻略的挑战变更，必须在列表项上显式加上⚡图标，例如：

* Significant overhaul of <category> challenges (⚡)

4. 技术性破坏变更标记

Are technical breaking changes (Node.js version, removals) marked with⚠️?

Node.js 版本支持范围变化、配置项移除、API 重命名等必须使用⚠️标记。仓库当前的 Node.js 支持范围可在 package.json 的engines字段确认：

"engines": { "node": "22 - 26" }

当新版本将支持范围从22 - 26改为其他区间时，发布说明中应如此书写：

## 👟 Runtime * Removed support for Node.js <old_version>.x (⚠️) * Added support for Node.js <new_version>.x

5. 外部贡献者致谢

Are external contributors properly credited with(kudos to @username)? (Excluding@J12934and@bkimminich)

每一个由外部贡献者完成的变更，都要在列表项末尾追加(kudos to @username)后缀。项目维护者@J12934与@bkimminich是项目核心维护人，永不使用 kudos 后缀（依据 SKILL.md 第 49 行）。贡献者名单可参考 package.json 的contributors字段，其中列出了Aashish683、MarcRler、agrawalarpit14等大量外部贡献者。

6. 章节标题图标

Do all section headings have their corresponding emoji?

所有 H2 章节标题必须携带规定的 emoji。完整的分类与图标映射表（源自 SKILL.md 的 Categorize & Iconize Changes 部分）：

7. 引用格式与位置

Are PRs and commits referenced using#numberandhashformat and prefixed to the list item?

PR 用#数字引用、commit 用哈希引用，且必须前缀在列表项开头，绝不能后缀。例如：

* #1234: Fixed <description> (kudos to @<username>) * abcdef: Added <description>

这条规则在 SKILL.md 第 50 行被再次强调："These must always be prefixed to the list item ... never suffixed"。

8. 分类准确性

Is the categorization accurate (Runtime, Frontend, Challenges, UI, etc.)?

每一个变更条目都必须落到最贴切的分类。判断依据是变更影响的代码区域，例如：

• 改动 routes/ 下的 Express 路由或lib/下的核心逻辑 → Runtime / Bugfixes；
• 改动 frontend/src/app 下的 Angular 组件 → Frontend / UI；
• 改动 data/static/challenges.yml → Challenges；
• 改动i18n/目录下的语言文件 → I18N（注意：仓库根目录的i18n/目录当前为空，实际翻译资源位于 frontend/src/assets/i18n）。

9. 语言翻译说明

Are translation expanded for specific languages mentioned in the🌐 I18Nsection?

在🌐 I18N章节中，必须明确点出本次扩展了哪些具体语言的翻译，而不是笼统地写"更新了翻译"。参考 minor.md 模板 的写法：

## 🌐 I18N * Expanded <language> translations (kudos to @<username>)

10. Checklist 的位置：Review and Refine 环节

Checklist 的最后落点在于 SKILL.md 第 4 步 "Review and Refine"：生成完发布说明后，必须与release-notes-checklist.md逐项比对，并确认第 1 步收集到的所有显著变更都被覆盖。

三、发布说明生成的完整工作流

SKILL.md 定义了从信息收集到成品发布的四步流程，Checklist 是其中第 4 步的质量保证环节。

Step 1：信息收集（Gather Information）

通过一组git命令获取两个版本之间的全部变更事实：

# 定位上一次发布的 tag git describe --tags --abbrev=0 # 列出上次 tag 之后的所有 commit git log <last_tag>..HEAD --oneline # 查找 PR 与外部贡献者（格式：hash + subject + author） git log <last_tag>..HEAD --pretty=format:"%h %s (%an)" # 版本/依赖变更 git diff <last_tag>..HEAD -- package.json # 产品/用户变更 git diff <last_tag>..HEAD -- config/default.yml # 挑战变更 git diff <last_tag>..HEAD -- data/static/challenges.yml # 配置变更（config schema） git diff <last_tag>..HEAD -- lib/config.schema.ts # UI/Frontend 变更 git diff <last_tag>..HEAD -- frontend/src/app # 翻译更新 git diff <last_tag>..HEAD -- i18n

这套命令精准对应了发布说明的分类维度：package.json的 diff 决定 Runtime/Frontend 条目，challenges.yml的 diff 决定 Challenges 条目，lib/config.schema.ts的 diff 决定 Configuration 条目，frontend/src/app的 diff 决定 UI 条目，i18n的 diff 决定 I18N 条目。仓库中对应的真实文件分别是 package.json、challenges.yml、config.schema.ts 与 frontend/src/app。

Step 2：分类与图标化（Categorize & Iconize Changes）

将第 1 步收集到的变更映射到上文的 17 个分类与对应 emoji，并对特殊变更附加⚡/⚠️/📜状态图标，对挑战条目附加⭐难度星级。

Step 3：格式化（Format the Notes）

• 有破坏性变更时，顶部放 blockquote 免责声明；
• 列表统一使用*作为 bullet 符号；
• 外部贡献者追加(kudos to @username)；
• PR 引用#number、commit 引用哈希，均前缀于列表项。

Step 4：审查与精修（Review and Refine）

用release-notes-checklist.md逐项核对（即本文第二节的 10 条门禁），确保第 1 步发现的显著变更全部覆盖。

四、三套发布类型模板详解

仓库在 .ai/skills/generate-release-notes/types/ 下维护了三套模板，分别对应三种发布类型。

1. 大版本 / 破坏性发布（major.md）

适用于包含 Node.js 版本变化、挑战大规模重构、UI 大规模重设计等破坏性变更的版本。完整模板：

> This release brings significant changes to existing challenges (⚡) which might break canned CTF setups as well as solution guides made for previous versions of OWASP Juice Shop! It also contains technical breaking changes or renamings (⚠️) which might require migrating to a newer Node.js version or updating existing customization files. ## 👟 Runtime * Removed support for Node.js <old_version>.x (⚠️) * Added support for Node.js <new_version>.x ## 🅰️ Frontend * Updated frontend to Angular <version>.x and Angular Material <version>.x (kudos to @<contributor>) ## 🎯 Challenges * Added new <name> ⭐⭐⭐⭐⭐-challenge (kudos to @<contributor>) * Significant overhaul of <category> challenges (⚡) ## 🎨 User Interface * Redesigned <screen_name> for better accessibility and modern look ## 🛒 Shop * Added <count> new products * Added <count> new customer user(s) ## 🧹 Technical Debt Reduction * Migrated <feature> to <new_tech> ## 🐛 Bugfixes * #<pr_number>: Fixed <description> (kudos to @<username>)

注意其章节顺序规范：Runtime → Frontend → Challenges → UI → Shop → Technical Debt → Bugfixes。这个顺序与 SKILL.md 第 68 行要求的 "correct order (Runtime, Frontend, Challenges, UI, etc.)" 完全一致。

2. 小版本 / 功能发布（minor.md）

适用于有新功能但无重大破坏性变更的版本：

## 🎯 Challenges * Added new <name> ⭐⭐-challenge (kudos to @<username>) ## 🎨 User Interface * Improved <feature> visuals (kudos to @<username>) ## 🌐 I18N * Expanded <language> translations (kudos to @<username>) ## 🔧 Configuration * Added <option> to <section> of configuration ## 🐛 Bugfixes * #<pr_number>: Fixed <issue_description>

3. 补丁 / 热修复发布（hotfix.md）

适用于仅包含 bugfix 或 hotfix 的版本：

## 🔥 Hotfix * <commit_hash>: Fixed <description> ## 🐛 Bugfixes * #<pr_number>: Fixed <description> (kudos to @<username>)

这类发布通常没有免责声明、没有挑战条目，结构最精简。

五、补全既有草稿：Checklist 的二次校验用法

SKILL.md 还规定了"补全既有发布说明草稿"的流程，此时 Checklist 同样适用：

1. 检查缺失章节：基于收集到的变更信息，判断是否有章节遗漏；
2. 补全图标：为所有章节标题补上对应 emoji，并确认免责声明是否恰当；
3. 标准化 kudos 格式：将不规范的(kudos to @username)统一为正确格式；
4. 确认章节顺序：所有章节必须遵循 Runtime → Frontend → Challenges → UI 的既定顺序。

六、发布草稿的创建与发布

当内容与格式都通过 Checklist 校验后，若环境已安装ghCLI 且具备相应 token，可直接创建草稿发布：

gh release create <tag> --title "<tag>" --notes-file <file> --draft

其中<file>为通过校验的发布说明 Markdown 文件。若gh不可用，则将 Markdown 内容交给维护者手动创建 Release 即可（依据 SKILL.md 的 "Draft Release Creation (Optional)" 部分）。

七、总结：Checklist 的定位与价值

release-notes-checklist.md是 OWASP Juice Shop 发布说明体系的最终质量门禁，它把 SKILL.md 中定义的图标映射、状态图标、kudos 规则、引用格式与三套 types/ 模板 全部收敛为 10 条可勾选、可执行的检查项。任何维护者或 AI Agent 只要严格遵循"收集 → 分类图标化 → 格式化 → Checklist 审查"四步流程，就能保证每次发布说明在结构、分类、图标、致谢与引用层面都保持一致，让庞大的多维度变更集对读者——尤其是依赖版本变更调整 CTF 部署与通关攻略的社区用户——保持高度可读与可信赖。

• 网络安全
• 后端