Barrier 项目的 towncrier 发布说明工作流用 newsfragments 管理变更并自动生成 Release Notes【免费下载链接】barrierOpen-source KVM software项目地址: https://gitcode.com/gh_mirrors/ba/barrier开源 KVM 软件 Barrier 使用 towncrier 为核心结合仓库中的 towncrier.toml、doc/release_notes/index.template.jinja、doc/release_notes/index.md 与 RELEASING.md完整讲解 newsfragments 的目录约定、文件命名规范、支持的变更类型、配置原理以及它与 Barrier 发布流程的衔接帮助你在提交用户可见变更时正确书写发布说明片段并理解最终 Release Notes 是如何生成的。newsfragments 目录在 Barrier 项目中的角色在 Barrier 仓库根目录下有一个专门目录 doc/newsfragments/它的定位是发布说明片段release note fragments的存放地。这些片段由 towncrier 工具统一收集处理每当你做出一个**用户可见user-visible**的变更例如新增功能、修复缺陷、加固安全、改进文档或移除功能就在该目录中创建一个文件该文件会在下一个版本发布时被 towncrier 自动并入发布说明文档目录中现存的实际片段如1260_macos-launchinfo.bugfix、japanese-translation.bugfix、fix-wrong-encoding-for-text-copied-between-linux-and-windows.bugfix等正是这种工作流的真实产物是书写新片段时最直接的范例。这种变更即片段的模式让贡献者无需在开发时就去手工维护一份长 changelog而是由仓库在发布节点统一收口避免合并冲突与遗漏。文件扩展名决定变更类型根据 doc/newsfragments/README.mdnewsfragments 目录中每个文件的**扩展名file extension**直接指定了该变更的类型。当前支持以下五种扩展名含义发布说明中的归类名称见 towncrier.toml.feature一项新功能Features.bugfix一个缺陷修复Bug fixes.security一个安全问题修复Security fixes.doc文档改进Improved Documentation.removal功能的弃用或移除Deprecations and Removals扩展名的语义在 towncrier.toml 中被完整映射为发布说明中的章节。例如[[tool.towncrier.type]]中定义了directory feature、name Features、showcontent true而security类型则是name Security fixes、showcontent false——这意味着安全类变更在生成时只列出 issue 编号不渲染具体描述文本。目录中还实际存在未出现在 README 列表里的.doc、.bugfix等类型片段扩展名体系与配置文件一一对应。五种变更类型与仓库中的真实范例要理解每种类型的写法直接查看 doc/newsfragments/ 目录中已有的文件最直观.feature新功能Feature 片段用于描述新增的用户能力。在 doc/release_notes/index.md 的 2.4.0 章节中可以看到这类片段的最终渲染形态例如Added--drop-targetoption that improves drag and drop support on Windows when Barrier is being run as a portable app.The--enable-cryptocommand line option has been made the default … A new--disable-cryptocommand line option has been added to explicitly disable encryption.Added support for randomart images for easier comparison of SSL certificate fingerprints. The algorithm is identical to what OpenSSH uses.Added--profile-diroption that allows to select custom profile directory.这些内容在发布时以-列表项逐条呈现表明 feature 片段的写作应以新增了什么、为什么、如何使用为要点。.bugfix缺陷修复bugfix是仓库中现存最多的片段类型。例如 1260_macos-launchinfo.bugfixCorrected macOS packaging to provide a better error message when a user attempts to launch Barrier on an incompatible macOS version.又如 fix-wrong-encoding-for-text-copied-between-linux-and-windows.bugfixFix wrong encoding for text copied between Linux and Windows.以及 restore-dpiawareness.bugfixFixed a regression in 2.4.0 that caused Barrier to not support scaling other than 100%.从这些范例可以看出bugfix 片段应写明修复了什么、影响哪个平台/场景、对应哪个 issue 编号涉及回归的还应点明引入问题的版本方便用户判断是否需要升级。.security安全修复安全片段默认不展示正文showcontent false在 doc/release_notes/index.md 的 2.4.0 章节中安全修复如客户端身份校验 CVE-2021-42072/CVE-2021-42073、SHA256 指纹等以较长的描述性文字与 CVE 编号列出。可见安全修复属于最高优先级变更写作时应讲清漏洞影响面、修复方式与升级/兼容注意事项。.doc文档改进1260_update-faqs.doc 是现存范例Updated FAQs in project README.md with more detail on OS support and links to issues for infrequent users.而 linux-drag-drop-faq.doc 则更简短Fixed FAQ link to Linux drag and drop issue.这说明.doc片段既可以描述一次实质性的文档增补也可以仅仅记录一个链接修正核心是让用户在 changelog 中感知到文档层面的变化。.removal弃用与移除当前仓库中暂无.removal实例但结合 towncrier 配置可知它会被归入 Deprecations and Removals 章节并展示正文。从 Barrier 的演进历史如默认启用--enable-crypto、以--disable-crypto显式关闭加密可以看出涉及命令行行为默认值变更、旧能力下线时正是该类型片段的应用场景。towncrier.toml仓库中的发布说明配置Barrier 将 towncrier 的完整配置固化在仓库根目录的 towncrier.toml 中它把 newsfragments 与发布说明文档粘合在一起[tool.towncrier] package directory doc/newsfragments filename doc/release_notes/index.md template doc/release_notes/index.template.jinja title_format \nBarrier {version} ( {project_date} )\n\n start_string [comment]: (towncrier release notes start) [[tool.towncrier.section]] path [[tool.towncrier.type]] directory security name Security fixes showcontent false [[tool.towncrier.type]] directory feature name Features showcontent true [[tool.towncrier.type]] directory bugfix name Bug fixes showcontent true [[tool.towncrier.type]] directory doc name Improved Documentation showcontent true [[tool.towncrier.type]] directory removal name Deprecations and Removals showcontent true [[tool.towncrier.type]] directory misc name Miscellaneous showcontent false关键配置项的语义如下directory片段来源目录即doc/newsfragmentsfilename发布说明的写入目标即 doc/release_notes/index.mdtemplate生成发布说明所用的 Jinja2 模板 doc/release_notes/index.template.jinjatitle_format每次发布生成的主标题格式包含{version}与{project_date}占位符start_string发布说明文档中的锚点标记towncrier 会将新内容插入到该标记之后[comment]: (towncrier release notes start)同时出现在 doc/release_notes/index.md 的第 4 行是生成结果与配置互相印证的位置type 段每一类扩展名对应的目录名、章节显示名以及showcontent是否展示片段正文。值得注意的是配置中还定义了misc类型Miscellaneousshowcontent false但 newsfragments README 的五类列表中并未提及它——这暗示misc属于维护者可用的扩展类型印证了配置与实际约定之间存在弹性空间。Jinja 模板Release Notes 是如何渲染的towncrier 并非简单地把片段拼接进文档而是通过 doc/release_notes/index.template.jinja 模板控制最终排版。模板核心逻辑是按sections遍历所有变更分组为每个分组生成标题与下划线分隔线对每个分组遍历配置中定义的definitions即 towncrier.toml 里的 type 定义只处理该分组实际存在的category对showcontent true的类型逐条渲染为- 文本列表项对showcontent false的类型如 security、misc只渲染通过逗号连接的条目集合当某个分组或分类没有任何条目时输出占位文案 No significant changes.。这条模板链路意味着newsfragments 中的正文文本去除文件名就是最终渲染进 Release Notes 的列表项文本因此片段正文必须自含完整语义、可独立阅读。对照 doc/release_notes/index.md 中 Barrier 2.4.0 的实际排版Security fixes / Bug fixes / Features 三节各节内以-列表呈现可以直观看到模板输出与配置定义的对应关系。与发布流程的集成RELEASING.md 中的使用方式newsfragments 只是发布流程的前半段真正触发收集动作的是维护者的发布脚本。在 RELEASING.md 的 Step 2: Release notes PR 中给出了唯一一条核心命令export VERSIONX.Y.Z towncrier --version ${VERSION} --date date -u %F该命令会读取 towncrier.toml 的配置把 doc/newsfragments/ 中的全部片段按类型归类渲染进 doc/release_notes/index.md随后维护者提交这批收集后的发布说明并在后续步骤中同步更新 Build.properties当前版本号为BARRIER_VERSION_MAJOR 2、MINOR 4、PATCH 0、STAGE release等版本文件。RELEASING.md 还特别提醒了一个实践要点Certain file names are not properly supported by thetowncriertool and it ignores them. Checknewsfragmentsdirectory for any forgotten release notes.也就是说towncrier 对某些文件名如以.md、特殊字符开头或不遵循编号.类型命名习惯的文件会静默忽略。发布前需要人工复查 newsfragments 目录确认没有遗漏未被收集的片段——这正是目录内保留README.md文档文件也不会被误收的原因README.md 扩展名为.md不在五类类型之列。实操指南如何为一次用户可见变更添加 newsfragment结合上述约定在 Barrier 中为一次变更书写发布说明的完整步骤如下判断是否需要片段只有影响用户新增功能、修 bug、修安全、改文档、移除/弃用功能的变更需要纯内部重构、CI 调整等可不必添加。命名文件建议按变更主题或 issue 编号 类型扩展名命名仓库现有范例包括1260_macos-launchinfo.bugfixmacOS 打包错误提示修复1260_update-faqs.docFAQ 文档更新fix-wrong-encoding-for-text-copied-between-linux-and-windows.bugfixLinux/Windows 间剪贴板文本编码修复japanese-translation.bugfix日文翻译更新linux-drag-drop-faq.docFAQ 链接修正restore-dpiawareness.bugfix2.4.0 回归修复书写正文正文即最终 Release Notes 中的列表项文本应自含语义。可参照 fix-wrong-encoding-for-text-copied-between-linux-and-windows.bugfix 的写法——一句话说明问题与影响涉及已知 issue 时可在正文中标注对应编号。提交并等待收集片段随 PR 合入仓库无需手动修改 doc/release_notes/index.md它会在维护者执行towncrier --version ${VERSION} --date ...时被自动并入下一版发布说明。发布前复查确认文件名符合命名习惯避免因 towncrier 不支持的文件名而被静默忽略。小结Barrier 的 newsfragments 工作流是一套轻量、可自动化的发布说明管理体系贡献者以扩展名即类型的方式在 doc/newsfragments/ 中沉淀每一次用户可见变更towncrier.toml 定义类型与章节的映射doc/release_notes/index.template.jinja 负责渲染最终由 RELEASING.md 中的towncrier命令在发布节点统一写入 doc/release_notes/index.md。理解这套约定后无论是提交贡献还是参与 Barrier 的发布维护你都能准确书写、定位并生成高质量的 Release Notes。【免费下载链接】barrierOpen-source KVM software项目地址: https://gitcode.com/gh_mirrors/ba/barrier创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考