开发工具桌面应用【免费下载链接】desktopFork of GitHub Desktop to support various Linux distributions项目地址https://gitcode.com/gh_mirrors/des/desktop点击查看免费下载本篇技术指南基于 GitHub Desktop 仓库的docs/process/writing-release-notes.md系统讲解该项目的发布说明Release Notes写作规范包括条目结构、五种标签的语义与排序、面向用户影响的写作原则以及yarn draft-release草稿生成工具背后完整的自动化解析链路。读完本文你将掌握一套可复用的发布说明写作与校验工作流既能写出符合社区规范的条目也能理解草稿是如何从 PR 合并记录与changelog.json中自动生成的。发布说明的构成Anatomy of a Release Note每一条发布说明由三到四个部分组成其标准格式如下[Tag] Description of work or change - #{issue_number}Tag标签用于归类的标记取值来自固定的五类详见下文「标签体系」一节。Description描述对本次改动的一句话说明必须遵循「面向用户」的写作原则。Issue/PR 编号以- #编号形式附在描述之后用于追溯对应的 issue 或 PR。贡献者致谢可选第四部分当改动由外部贡献者完成时追加一段致谢[Tag] Description of work or change - #{issue_number}. Thanks {contributor_username}!这一「感谢外部贡献者」的约定不仅在写作规范中存在也被工具链实际解析在 script/changelog/parser.ts 的getChangelogEntry中会检查 PR 所属仓库所有者是否等于官方账号desktop若不是则自动追加. Thanks {owner}!后缀script/draft-release/run.ts 的辅助脚本 script/generate-release-notes.ts 也使用正则\[(.*)\](https://link.gitcode.com/i/d9679a7f8bd70fcd071f3f59f7697654)- (.*)\. Thanks (.*)!来识别并提取带贡献者的条目。写作风格指南规范文档用较大的篇幅约束描述文案本身这些约束大致可归纳为四条原则。只写面向用户的变化不收录不影响用户使用体验的改动。例如修复 CI 配置如 Appveyor、升级 Electron 这类纯内部工程改动通常不会出现在发布说明中。安全漏洞修复属于例外即使是内部层面的修复只要是安全漏洞尤其是高关注度漏洞就会收录且措辞通常比较宽泛、不附带具体 CVE 编号。原文档给出的例子[Fixed] Update embedded Git to address security vulnerability - #4791描述用户影响而非技术过程条目应说明「这项改动如何改变用户的工作流或体验、帮用户做到了什么」而不是堆砌技术实现细节。原文档中的对比示例[Fixed] Keep PR badge on top of progress bar - #8622 ✅ 推荐 [Fixed] Increase z-index of the progress bar PR badge - #8622 ❌ 不推荐前者描述的是用户可感知的结果PR 徽标保持在进度条上方后者则是在复述 CSS 实现提升 z-index用户并不关心也不理解。使用现在时态除非会显著损害清晰度否则统一使用现在时。对比[Added] Add external editor integration for Xcode - #8255 ✅ 推荐 [Added] Adding external editor integration for Xcode - #8255 ❌ 不推荐描述以动词原形开头Add / Fix / Improve / Remove保持简洁直接。措辞描述独立于标签可读虽然把标签当作描述的第一个词很诱人但规范要求描述本身脱离标签后依然通顺、自成一句。对比[Improved] Always fast forward recent branches after fetch - #7761 ✅ 推荐 [Improved] Branch fast-forwarding after fetch - #7761 ❌ 不推荐去掉[Improved]后Always fast forward recent branches after fetch依然是一句完整的话而Branch fast-forwarding after fetch只是短语可读性较差。标签体系与排序项目使用五个标签来组织发布说明且在最终展示时严格按以下顺序排序[New][Added][Fixed][Improved][Removed]同一标签组内各条目的顺序则相对随意。这一排序同样反映在自动化脚本中script/generate-release-notes.ts 的generateDraftReleaseNotes按 New → Added → Fixed → Improved → Removed 的顺序渲染各个分组标题。[New]通常保留给「最闪亮的新功能」条目本身可能很短、层级很高却浓缩了大量开发工作。写作时一个自查技巧是检查[New]条目是否与该版本对外宣传的「亮点 / 最重要的新特性」一一对应。[Added]本质上是「小一号的 [New]」功能更小或者不是本版本重点宣传的内容。编辑器与终端集成类的新功能经常使用[Added]——例如 changelog 中可见的[Added] Add Cursor support on macOS - #17462、[Added] Add JetBrains RustRover support - #18802等条目见 changelog.json。[Fixed]发布说明的中流砥柱表示「之前坏了现在不坏了」。注意措辞应描述做了什么、行为如何改善而不是描述之前错在哪里。原文档示例[Fixed] Keep conflicting untracked files when bringing changes to another branch - #8084 ✅ [Fixed] Conflicting untracked files are lost when bringing changes to another branch - #8084 ❌[Improved]介于 [Added] 与 [Fixed] 之间表示「把已有功能做得更好」但功能此前并非损坏。与 [Added] 的区分规则是新增一段端到端的小功能用 [Added]对已有功能某个部分的修改用 [Improved]。例如 changelog.json 中的[Improved] Allow resizing Branch and Push/Pull toolbar buttons - #4569 #17388即为典型的「增强既有功能」条目。[Removed]描述应用中不再可用的功能使用频率较低。示例[Removed] Remove Discard all changes context menu item from Changes list - #7394关于标签的灵活性文档明确提醒这些标签并不是硬性、绝对的规则需要结合具体情境运用判断力与细微差别原文即注明「These arent hard and fast rules or categories」。发布渠道与严谨程度规范指出生产版本production的发布说明比 beta 版本的更严谨。这一点在工具链中有直接对应yarn draft-release支持production、beta、test三种渠道见 script/draft-release/channel.ts其中production只会收集自上一个生产版本以来的条目且拒绝基于 beta/test 版本起草生产发布见 script/draft-release/version.tsbeta从 git 历史中提取自上一个版本 tag 以来的合并 PR再调用 GitHub API 解析成 changelog 格式test不为测试发布猜测发布说明直接跳过收集阶段见 script/draft-release/run.ts。从草稿到定稿yarn draft-release自动化链路规范文档指出yarn draft-release是一个很好的起点但不是最终版本。理解这条命令背后的自动化流程有助于更准确地理解为什么草稿需要人工修订。第一步环境校验与渠道解析入口脚本 script/draft-release/index.ts 首先通过gh auth status校验 GitHub CLI 是否已认证未认证则提示先执行gh auth login并退出。随后 script/draft-release/run.ts 解析渠道参数production/beta/test并根据渠道从git tag中选取上一个版本production/test 渠道排除 beta 版本production/beta 渠道排除 test 版本再调用getNextVersionNumber计算出下一个版本号并创建releases/版本分支。第二步按渠道收集条目production 渠道调用getChangelogEntriesSince(previousVersion)见 script/changelog/parser.ts从仓库根目录的 changelog.json 中收集所有版本号大于上一版本、且非-beta0的条目beta0 是生产更新同步到 beta 渠道的约定占位予以跳过。beta 渠道通过git log ...上一版本 --merges --grepMerge pull request --formatformat:%s拉取合并提交标题见 script/changelog/git.ts随后逐条解析并调用 GitHub PR API 获取详情最终转换成 changelog 条目格式。另外若传入--pretext参数还会读取 app/static/common/pretext-draft.md将其包装成[Pretext] ...条目置于最前见 script/draft-release/run.ts。第三步PR 到条目的转换规则script/changelog/parser.ts 定义了从 PR 信息生成 changelog 条目的核心逻辑这正好印证了规范中「格式是[Tag] 描述 - #编号」的写法PR 正文的Notes:段优先解析 PR body 中最后一行以Notes:开头的内容作为发布说明若内容为no-notes则明确表示该 PR 不需要发布说明若完全没有Notes:段则回退到自动生成自动生成规则类型占位为???描述取 PR 标题并首字母大写若 PR body 中出现fixes/closes/resolves #编号之类的引用则类型自动置为Fixed且编号取被修复的 issue 编号否则编号取 PR 自身编号外部贡献者PR 来源仓库所有者不是desktop时自动追加. Thanks {owner}!致谢。上述规则都有对应的单元测试验证见 script/changelog/test/parser-test.ts例如「多个 Notes 取最后一个」「Notes: no-notes返回 null」「Fixes #2314被识别为 issue 引用」等场景。第四步写入 changelog.json 并给出后续步骤草稿条目会被写入 changelog.json 的releases对象新版本号对应的数组随后脚本打印后续操作清单其中明确包含一条指向本规范文档的提示——「根据写作发布说明的规范修订草稿」随后用yarn draft-release:format进行格式检查lint、提交到 release 分支并推送。可见自动化工具负责「收集素材」而是否符合 docs/process/writing-release-notes.md 的写作规范仍需人工把关。changelog.json 的数据结构与校验草稿与最终定稿都沉淀在仓库根目录的 changelog.json 中其结构为{ releases: { 3.4.9: [ [Fixed] App no longer crash for first time users going through the welcome flow and attempting to sign in more than once - #19442, [Improved] Allow resizing Branch and Push/Pull toolbar buttons - #4569 #17388. Thanks jpedroso!, [Removed] Remove ruleset bypass confirmation modal - #19281. Thanks lofcz! ] } }注意几个值得借鉴的细节一个条目可引用多个编号如#4569 #17388对应 PR 同时关闭/关联多个 issue 的情况版本号格式主.次.补丁可选-betaN或-testN后缀beta 与生产版本的条目存在重叠beta 阶段的条目会逐步合并进后续生产版本这是「beta 严谨度低于 production」的又一体现。该文件由 script/validate-changelog.ts 负责校验要求 JSON 可解析、只有releases一个顶层键、至少包含一个发布版本、版本号符合x.y.z(-betaN|-testN)?正则、且每个版本的改动均为字符串数组校验通过后输出The changelog is totally fine。而 script/generate-release-notes.ts 则是在正式发布时把 changelog 条目连同构建产物3 种架构 × 3 种包格式 × 2 个文件 18个一起渲染成最终的发布说明文件release_notes.txt。写作自查清单综合规范文档与工具链实现撰写一条合格的发布说明可以按以下清单自查结构完整[Tag] 描述 - #编号外部贡献者追加. Thanks 用户名!面向用户描述用户能感知的结果不写内部实现z-index、CI 配置等现在时以 Add/Fix/Improve/Remove 原形动词开头脱离标签可读去掉[Tag]后描述仍是完整通顺的句子标签准确亮点大功能用[New]小功能用[Added]修复用[Fixed]既有功能增强用[Improved]移除功能用[Removed]排序正确New → Added → Fixed → Improved → Removed无编号缺失编号可追溯issue 或 PR并可被 script/changelog/parser.ts 的正则正确解析符合渠道要求production 发布说明必须比 beta 更严谨纯内部改动不收录安全修复除外。遵循这套规范既能保证发布说明对最终用户友好、可读、可追溯也能确保yarn draft-release、changelog 校验与正式发布脚本整条自动化链路顺畅运转——这正是规范文档与工具链设计相辅相成的完整闭环。赞分享开发工具桌面应用【免费下载链接】desktopFork of GitHub Desktop to support various Linux distributions项目地址https://gitcode.com/gh_mirrors/des/desktop点击查看免费下载相关推荐GitHub Desktop 发布说明编写指南格式规范、写作原则与 changelog 自动化流程GitHub Desktop 发布说明编写指南格式规范、写作原则与 changelog 自动化流程 本文以 GitHub Desktop仓库 gh_mirr桌面应用版本控制开发工具Bazel 贡献者发布说明撰写指南RELNOTES 标签规范与自动化生成流程Bazel 贡献者发布说明撰写指南RELNOTES 标签规范与自动化生成流程 Bazel 仓库要求每个可能影响用户的提交在 commit message 中携构建工具LobeHub 版本发布工作流Minor/Patch 双轨自动化与 GitHub Release 编写规范LobeHub 版本发布工作流Minor/Patch 双轨自动化与 GitHub Release 编写规范 本文以 LobeHub 仓库内的 version人工智能AI 应用大模型AI Agent多智能体工具调用前端后端上一篇Apache Log4j2配置文件详解XML、JSON、YAML三种格式对比下一篇探秘DOSBox重温经典电脑时代的魅力创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考