Bevy 贡献者指南为高影响 PR 撰写发布说明Release Notes的完整流程与实践【免费下载链接】bevyA refreshingly simple>项目地址: https://gitcode.com/GitHub_Trending/be/bevy本文以 Bevy 仓库_release-content/release_notes.md为骨架讲解 Bevy 开源项目随 PR 编写发布说明草稿的内部协作机制当 PR 被标记M-Release-Note后该做什么、草稿存放在哪里、应包含哪些内容、如何按功能特性而非PR 粒度进行归组以及草稿最终如何汇入官网发布说明。读完本文你将能作为贡献者或审阅者为 Bevy 高影响变更提交一份符合社区规范、可直接进入发布流程的发布说明草稿。为什么 Bevy 要求写代码的人同时写发布说明Bevy 的发布说明以其详尽深入著称见bevy.org/news。当项目对用户以及潜在用户产生高影响变更时必须及时、清晰地传达变更内容。如果所有发布说明都堆到发布周期结束时统一撰写会形成巨大的期末赶工压力crunch质量与体验都无法保证。因此 Bevy 的协作模式是在提交高影响功能的 Pull Request 时由作者和审阅者同步写好发布说明草稿。发布说明草稿不需要打磨——即使你不是母语英语者、不擅长文字雕琢也没关系因为后续有专门的编辑环节。社区真正想要的是具备实现该功能专业能力的作者提供一份粗糙但专家级的视角素材再由编辑把它塑造成行文流畅、语气一致的正式文案。实践中的触发机制很直接如果某个维护者给你的 PR 贴上了M-Release-Note标签就说明该变更属于高影响你需要按本文流程补上对应的发布说明草稿。发布说明草稿放在哪里Bevy 的每个主版本如 0.12、2.0当前仓库版本为 0.20.0-dev见 Cargo.toml都会拥有一套自己的发布说明。草稿按约定存放在仓库根目录的_release-content/release-notes文件夹中该目录整体由 _release-content/README.md 管理它集中存放当前开发周期的文档草稿并指向 release_notes.md发布说明流程与 migration_guides.md迁移指南流程两份说明文件。开始一篇新发布说明的标准动作把 发布说明模板 复制到release-notes文件夹中的一个新文件里然后填写内容。例如当前_release-content/release-notes/目录下已积累了一批草稿pan_orbit_camera.md、ready_event.md、compressed_image_saver.md、number_input.md、contextual_theming.md、schedule_randomization.md、panics-to-errors.md等每个文件对应一个即将发布的新特性。发布说明模板的结构与元数据每个草稿文件都以 YAML front matter 开头包含三类元数据见 release_notes_template.md字段含义示例title发布说明的标题应清晰对应特性名称Feature nameauthors该特性的贡献者 GitHub 账号列表[FerrisTheCrab, BirdObsessed]pull_requests与该特性相关的所有 PR 编号[14791, 15458, 15269]以真实草稿 ready_event.md 为例其元数据写作authors: [cart]对应 PR 编号如实列出。front matter 之下的正文则遵循模板 Style Guide 的约束可以使用二级、三级标题但正文不允许以标题开头应先写一段引言式文字散文式叙述更受青睐但也接受要点列表复制你 PR 的引言部分往往是个不错的起点。草稿应回答的三个核心问题发布说明的本质是捕捉变更的精华围绕三个问题展开对应 release_notes.md 的定义改了什么 / 新增了什么what has been changed or added?为什么这对用户很重要why is this a big deal for users?用户该如何使用它how can they use it?看一个真实示例compressed_image_saver.md 完美贯彻了这三个问题先说改了什么——CompressedImageSaver资产处理器换用了基于ctt库的新压缩后端将纹理压缩为桌面 GPU 的 BCn 格式或移动 GPU 的 ASTC 格式再说为什么重要——相比旧的 Basis Universal 方案质量更高且会自动依据输入纹理通道数与类型挑选最佳输出格式单通道 → BC4HDR → BC6H标准 RGBA → BC7最后讲怎么用——运行compressed_image_saver示例、通过设置BEVY_COMPRESSED_IMAGE_SAVER_ASTC环境变量如4x4、6x6、8x8为移动 GPU 选择 ASTC 块大小旧的 Basis Universal 行为则移至compressed_image_saver_universalfeature。再如 panics-to-errors.md系统、命令与 observer 原本只能处理显式返回的错误panic 会直接拖垮整个应用现在 panic 被转成错误并交给 fallback error handler默认行为是再次 panic但你可以自行决定是记录错误继续运行还是采取其他策略——这就是典型的变更内容 为什么是大事 用户如何受益三段式草稿。关于多媒体素材放进 PR 描述而非仓库截图、视频能让发布说明锦上添花——渲染特性的精美截图、架构图、性能指标、炫酷示例都很合适。但规范明确禁止在_release-content目录中存放多媒体内容见 release_notes.md。原因很实际避免让bevyengine/bevy仓库体积膨胀大二进制文件会给贡献者与 GitHub 本身带来问题。正确做法是把图片、视频放进 PR 描述等到正式汇总发布说明时再统一收集。这也可以从仓库结构得到印证_release-content/release-notes/下的草稿文件全部是纯 Markdown 文本没有任何媒体附件。按功能特性归组而非按 PR 归组发布说明的组织粒度是粗略的功能特性不是每个 PR 一篇依据见 release_notes.md。Bevy 用户不关心某个功能是拆成 17 个 PR 完成还是一个一万行的大 PR 一次性落地。具体操作要求为每个草稿取一个清晰的名字使其与章节标题对应——也就是说一个功能特性对应一个文件名与一个title把相关的 PR及其作者统一收集进该 Markdown 文件的 front matter 元数据authors与pull_requests字段而非分散在多篇文档里如果你对某个即将发布的大特性做了改动或扩展应当去修订该特性的既有发布说明而不是另起一篇。release-notes目录中正体现了这一约定一篇草稿文件往往对应多个 PR 或多名作者。例如pan_orbit_camera.md的作者字段同时收录aevyrie与taishi-samapanics-to-errors.md、compressed_image_saver.md同理都是把一个完整功能特性聚拢成一篇文档。从草稿到官网发布候选阶段的汇合流程整个流程存在一条清晰的生命周期开发周期内作者在提交高影响 PR 时从 模板 复制出草稿文件放入bevyengine/bevy/_release-content/release-notes随 PR 一起评审。当前仓库0.20.0-dev见 Cargo.toml中积累的这些草稿即属于当前开发周期。发布第一个候选版本first release candidate时这些草稿被合并汇总从bevyengine/bevy迁移到bevyengine/bevy-website仓库。在 bevy-website 中草稿接受最后一轮编辑润色并补入此前收集在 PR 描述里的多媒体素材最终以正式发布说明的形式出现在官网。这套设计与配套的 迁移指南流程 相互呼应发布说明面向新增/变更功能庆祝新能力迁移指南面向破坏性变更教用户如何迁移两者共享同一套_release-content草稿-合并机制README_release-content/README.md即同时指向这两份流程文档。快速自查清单在你提交带M-Release-Note标签的 PR 之前建议对照以下清单确认草稿合格草稿文件已复制到_release-content/release-notes/目录不是仓库其他位置更不是_release-content根目录front matter 中的title、authors、pull_requests已如实填写一个功能特性含多个相关 PR聚合为单篇文档正文回答了改了什么、为什么重要、怎么使用三个问题且没有以标题开头若原有草稿涉及你正在修改/扩展的大特性已同步修订该草稿而非新建截图、视频等多媒体素材放在 PR 描述中未塞入仓库语气允许粗糙但技术事实必须准确——你正是最了解该实现的人这正是社区需要你执笔的原因。【免费下载链接】bevyA refreshingly simple>项目地址: https://gitcode.com/GitHub_Trending/be/bevy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考