企业官网建设流程全解析

conda 变更日志片段（news fragment）贡献指南：releases/news/ 工作流深度解析

【免费下载链接】condaA system-level, binary package and environment manager running on all major operating systems and platforms.项目地址: https://gitcode.com/GitHub_Trending/co/conda

news fragment 是 conda 项目中每项面向用户的重要变更对应的一篇小型 Markdown 文档，统一存放在releases/news/目录，发布时由工具自动聚合进 CHANGELOG.md。本文以 releases/news/README.md 为核心骨架，结合 AGENTS.md、RELEASE.md、rever.xsh 与仓库内数十篇真实 fragment，完整讲解何时写、怎么写、如何随发布生命周期流转，帮助贡献者一次通过变更日志审查。

什么是 news fragment

news fragment（也称 changelog fragment、release news snippet）是 conda 仓库采用的一种"改代码的同时附带写变更日志条目"的工作流：每个有意义的用户可见变更，在合入前于releases/news/目录下新增一个独立的小文件。发布时这些碎片被聚合到仓库根目录的 CHANGELOG.md 中，成为该版本发行说明的主体。

这种做法的核心价值在于：

• 让变更日志贴近代码：改动与对应条目在同一 PR 中出现，审查者可确认"改了代码是否忘了写 changelog"；
• 避免发布前的追溯性回忆：release cut 时不再需要人工翻阅几百个 PR 补写说明，只需运行聚合工具；
• 保证格式统一：所有条目都从同一个 TEMPLATE 复制而来，章节与语气一致。

这一工作流还延伸出了并行的 releases/qa/ 目录（详见下文"与 QA 片段的区别"），两者生命周期完全平行。

何时添加 news fragment

原文档明确给出了触发条件：

Add one file for each significant user-facing change for the next release: enhancements, bug fixes, deprecations, docs updates, removals.

即每一个面向用户的显著变更都应新增一个 fragment，包括：

• 新功能增强（enhancements）
• 缺陷修复（bug fixes）
• 弃用标记与移除（deprecations / removals）
• 面向用户的文档更新（docs updates）

AGENTS.md 进一步给出了边界：纯粹的 CI、类型标注（typing）、内部实现调整不需要 fragment。判断标准是"是否显著影响用户"——例如releases/news/16604-speed-up-clone-env-with-conda、16605-speed-up-update-env-no-action-json-output这类加速测试的改动，都被归入 "Other" 章节，因为它们虽不是用户功能，但仍属于值得记录的仓库级变更；而纯重构且无用户可观察差异的改动则不需要任何 fragment。

如何编写一个 news fragment

从模板复制

所有 fragment 都以 releases/news/TEMPLATE 为起点，其内容如下：

### Enhancements * <news item> ### Bug fixes * <news item> ### Deprecations * <news item> ### Docs * <news item> ### Other * <news item>

模板固定了五个章节，与 rever.xsh 中$CHANGELOG_CATEGORIES定义的类别一一对应（Enhancements、Bug fixes、Deprecations、Docs、Other），确保聚合进 CHANGELOG 时分类一致。

文件名规则

原文档规定文件名格式为<issue-number>-<short-slug>，例如16497-qa-snippets。仓库中的真实文件验证了这一约定：

• 15071-env-create-existing-prefix
• 15759-exclude-newer
• 16536-deprecate-get-revision
• 16643-conda-env-config-help-text

AGENTS.md 强调优先使用 issue 编号而非 PR 编号作为文件名前缀。部分早期文件（如7617-config-clear、12008-clarify-repodata-retry）不带.md后缀，但新文件通常带.md后缀（如14142-dev-mode.md），两种形式在聚合时均可被正确处理。

语气：祈使句

原文档要求使用祈使语气（imperative mood）：Add、Fix、Remove、Mark。这是为了让聚合后的 CHANGELOG 呈现"本版本做了什么"的直接陈述风格。仓库中的真实条目例如：

• Add a ``conda config --clear KEY`` option to explicitly set sequence configuration parameters to an empty list.（7617-config-clear）
• Mark passing ``caused_by`` as a positional argument to ``CondaError`` as pending deprecation, to be removed in 27.9.（16537-condaerror-caused-by-keyword-only）
• Fix ``channel_settings`` lookups for channel names and URLs.（16510-robust-channel-name-url-comparison）

一个 PR 可跨多个章节

原文档允许一个 fragment 覆盖多种类型的变更，仓库实例 14142-dev-mode.md 同时填写了 Enhancements、Bug fixes、Deprecations、Docs 四个章节，展示了一个大 PR 如何系统性记录功能调整、缺陷修复、弃用与文档更新。

引用编号与措辞的详细规则

AGENTS.md 补充了原文档未展开的细节规则，直接决定 fragment 能否被发布工具和读者正确理解：

章节归属

• 章节固定为 Enhancements、Bug fixes、Deprecations、Docs、Other 五类；
• 移除（removals）必须放在 Deprecations 章节，而不是 Other。例如 16314-delete-deprecated-disk-linking-code 中删除三个历史 API 的条目即位于 Deprecations 下；
• 一个 fragment 可以横跨多个章节（见上文示例）。

编号引用语法

• 每条 bullet 结尾用圆括号附上 GitHub 引用；
• 有 issue 时优先引用 issue：(#12345)；
• 通过 PR 合入的 issue 用#issue-number via #pr-number语法，例如(#12008 via #16599)、(#14142 via #16571)；
• 多个编号可用逗号分隔写在同一括号内：(#16426, #16427 via #16577)。

弃用与移除的措辞

Deprecations 条目必须与 CHANGELOG.md 中已有的弃用措辞保持风格一致，通常包含：被弃用的完整符号路径、pending deprecation状态、目标移除版本号（如to be removed in 27.9）、可用的替代方案。例如：

* Mark `conda activate --dev`, `conda create --dev`, `conda install --dev`, `conda remove --dev`, `conda.base.context.Context.dev`, and `conda.utils.wrap_subprocess_call(dev_mode)` as pending deprecation, to be removed in 27.9. Conda will stop exporting `_CE_M` and `_CE_CONDA` except when `--dev` is passed; shell expansion of those variables remains. Set `PYTHONPATH` to the conda source root instead. (#14142 via #16571)

空 bullet 处理

未使用章节中的<news item>占位符可以保留也可以删除，两种写法在聚合进 CHANGELOG 后渲染效果一致——rever.xsh 中$CHANGELOG_CATEGORY_TITLE_FORMAT只渲染有内容的类别标题。仓库中 15759-exclude-newer 保留了全部空章节，而 12008-clarify-repodata-retry 只写了有内容的章节，均属合法。

真实 fragment 拆解：三种典型写法

1. 单功能增强类

16354-plugins-info-subcommand 简洁记录新子命令，同时在 Other 章节补充依赖升级：

### Enhancements * Add a `conda plugins info` subcommand for showing installed conda plugin metadata. (#16354) ### Bug fixes * <news item> ### Deprecations * <news item> ### Docs * <news item> ### Other * Require `packaging` 26.3 or newer. (#16354)

2. 跨章节复杂变更类

15759-exclude-newer 用两条 Enhancements 详细说明新功能的配置参数（exclude_newer、exclude_newer_package）与实现位置，为读者提供了可直接查找的入口。

3. 纯文档更新类

16026-update-channels-concept-page 只有 Docs 章节一条记录，验证了"纯文档 PR 也值得记录"的约定。

发布生命周期：fragment 如何变成 CHANGELOG

原文档指出：发布 cut 时，releases/news/下的文件被聚合进 CHANGELOG.md，随后该目录被清空，仅保留TEMPLATE和本README.md。这一点与 AGENTS.md 中"不要直接编辑 CHANGELOG.md，发布时由releases/news/片段汇入"的约定互为印证——对普通贡献者而言，CHANGELOG.md 是只读产物。

RELEASE.md 详细记录了实际执行过程（由发布负责人操作，贡献者无需执行）：

1. 创建版本分支YY.MM.x，拉取 rever.xsh 与 news 模板的最新同步版本；
2. 审查所有 news 片段，确认格式为 Markdown（而非 reStructuredText），并为缺失的重要 PR 补写 fragment（发布人习惯在条目内联 PR 编号，如## Enhancements下* Add ``win-arm64`` as a known platform (subdir). (#11778)）；
3. 运行rever --activities changelog --force <VERSION>，rever 依据 rever.xsh 的配置，将releases/news/下的条目按$CHANGELOG_CATEGORIES顺序聚合到 CHANGELOG 顶部，并生成 Contributors 章节（* @{github}格式）；
4. 最终在发布 PR 合入后，将 CHANGELOG 内容作为发行说明发布。

聚合结果可以从 CHANGELOG.md 头部直接观察到：每个版本按### Enhancements、### Bug fixes、### Contributors等章节组织，条目标题即来自 fragment，例如26.7.2版本中的* Allow individual sharded-repodata package shards up to 64 MiB after decompression. (#16575)与 fragment 16575-shard-size-limit 完全一致。

与 QA 片段的区别

AGENTS.md 描述了与 news fragment 平行、同样在发布后被清空的 releases/qa/ 目录：

• news fragment面向所有用户可见变更，聚合进 CHANGELOG；
• QA 片段仅用于需要人工黑盒测试的变更（用户可见行为、跨平台/shell 行为、外部集成如 canary/proxy/SSL/插件、高风险回归路径、安全敏感路径），使用独立的 TEMPLATE（含 Title / Why / Platforms / Prerequisites / Steps / Pass criteria / Out of scope 七个部分），文件名同样优先用 issue 编号加短 slug（如16497-qa-snippets）；
• 纯文档、纯 CI、内部重构、已有 pytest 全覆盖的改动不需要QA 片段。

提交涉及用户可见变更时，可以同时思考"这条是否也需要一个 QA 片段"。

快速自查清单

写完一个 news fragment 后，对照以下清单检查：

• 是否为面向用户可见的变更（增强、修复、弃用、移除、文档），而非纯 CI/typing/内部改动？
• 是否从 TEMPLATE 复制并只改写了相关章节？
• 文件名是否为<issue-number>-<short-slug>形式，且优先使用 issue 编号？
• 所有 bullet 是否使用祈使句（Add / Fix / Remove / Mark）开头？
• 移除类条目是否放在 Deprecations 而非 Other？
• 每条是否以(#issue)或(#issue via #pr)结尾？
• 弃用条目是否包含完整符号路径、pending deprecation、目标移除版本与替代方案？
• 是否参考了 CHANGELOG.md 中既有条目的措辞风格？

参考资料导航

• 工作流总览：releases/news/README.md
• 模板：releases/news/TEMPLATE
• 详细规则（贡献者与 Agent 约定）：AGENTS.md（"Changelog (releases/news/)"一节）
• 发布与聚合流程：RELEASE.md
• 聚合配置（章节定义、Contributors 格式）：rever.xsh
• 聚合产物示例：CHANGELOG.md
• 真实片段样本：releases/news/ 目录下7617-config-clear、15759-exclude-newer、14142-dev-mode.md、16536-deprecate-get-revision等
• 并行 QA 片段：releases/qa/TEMPLATE 及16643-conda-env-config-help-text等示例

【免费下载链接】condaA system-level, binary package and environment manager running on all major operating systems and platforms.项目地址: https://gitcode.com/GitHub_Trending/co/conda