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/condanews fragment 是 conda 项目中每项面向用户的重要变更对应的一篇小型 Markdown 文档统一存放在releases/news/目录发布时由工具自动聚合进 CHANGELOG.md。本文以 releases/news/README.md 为核心骨架结合 AGENTS.md、RELEASE.md、rever.xsh 与仓库内数十篇真实 fragment完整讲解何时写、怎么写、如何随发布生命周期流转帮助贡献者一次通过变更日志审查。什么是 news fragmentnews 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 updatesAGENTS.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-prefix15759-exclude-newer16536-deprecate-get-revision16643-conda-env-config-help-textAGENTS.md 强调优先使用 issue 编号而非 PR 编号作为文件名前缀。部分早期文件如7617-config-clear、12008-clarify-repodata-retry不带.md后缀但新文件通常带.md后缀如14142-dev-mode.md两种形式在聚合时均可被正确处理。语气祈使句原文档要求使用祈使语气imperative moodAdd、Fix、Remove、Mark。这是为了让聚合后的 CHANGELOG 呈现本版本做了什么的直接陈述风格。仓库中的真实条目例如Add a conda config --clear KEY option to explicitly set sequence configuration parameters to an empty list.7617-config-clearMark passing caused_by as a positional argument to CondaError as pending deprecation, to be removed in 27.9.16537-condaerror-caused-by-keyword-onlyFix 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 详细记录了实际执行过程由发布负责人操作贡献者无需执行创建版本分支YY.MM.x拉取 rever.xsh 与 news 模板的最新同步版本审查所有 news 片段确认格式为 Markdown而非 reStructuredText并为缺失的重要 PR 补写 fragment发布人习惯在条目内联 PR 编号如## Enhancements下* Add win-arm64 as a known platform (subdir). (#11778)运行rever --activities changelog --force VERSIONrever 依据 rever.xsh 的配置将releases/news/下的条目按$CHANGELOG_CATEGORIES顺序聚合到 CHANGELOG 顶部并生成 Contributors 章节* {github}格式最终在发布 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面向所有用户可见变更聚合进 CHANGELOGQA 片段仅用于需要人工黑盒测试的变更用户可见行为、跨平台/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.mdChangelog (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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 conda 变更日志片段（news fragment）贡献指南：releases/news/ 工作流深度解析
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/condanews fragment 是 conda 项目中每项面向用户的重要变更对应的一篇小型 Markdown 文档统一存放在releases/news/目录发布时由工具自动聚合进 CHANGELOG.md。本文以 releases/news/README.md 为核心骨架结合 AGENTS.md、RELEASE.md、rever.xsh 与仓库内数十篇真实 fragment完整讲解何时写、怎么写、如何随发布生命周期流转帮助贡献者一次通过变更日志审查。什么是 news fragmentnews 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 updatesAGENTS.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-prefix15759-exclude-newer16536-deprecate-get-revision16643-conda-env-config-help-textAGENTS.md 强调优先使用 issue 编号而非 PR 编号作为文件名前缀。部分早期文件如7617-config-clear、12008-clarify-repodata-retry不带.md后缀但新文件通常带.md后缀如14142-dev-mode.md两种形式在聚合时均可被正确处理。语气祈使句原文档要求使用祈使语气imperative moodAdd、Fix、Remove、Mark。这是为了让聚合后的 CHANGELOG 呈现本版本做了什么的直接陈述风格。仓库中的真实条目例如Add a conda config --clear KEY option to explicitly set sequence configuration parameters to an empty list.7617-config-clearMark passing caused_by as a positional argument to CondaError as pending deprecation, to be removed in 27.9.16537-condaerror-caused-by-keyword-onlyFix 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 详细记录了实际执行过程由发布负责人操作贡献者无需执行创建版本分支YY.MM.x拉取 rever.xsh 与 news 模板的最新同步版本审查所有 news 片段确认格式为 Markdown而非 reStructuredText并为缺失的重要 PR 补写 fragment发布人习惯在条目内联 PR 编号如## Enhancements下* Add win-arm64 as a known platform (subdir). (#11778)运行rever --activities changelog --force VERSIONrever 依据 rever.xsh 的配置将releases/news/下的条目按$CHANGELOG_CATEGORIES顺序聚合到 CHANGELOG 顶部并生成 Contributors 章节* {github}格式最终在发布 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面向所有用户可见变更聚合进 CHANGELOGQA 片段仅用于需要人工黑盒测试的变更用户可见行为、跨平台/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.mdChangelog (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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考