如何为 Ansible PR 编写合规的 changelog 片段？命名规则、sections 校验与格式约定

如何为 Ansible PR 编写合规的 changelog 片段命名规则、sections 校验与格式约定【免费下载链接】ansibleAnsible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.项目地址: https://gitcode.com/GitHub_Trending/ans/ansible向 Ansible 提交 PR 时除了代码改动本身还必须在changelogs/fragments/目录下新增一个 changelog 片段fragment文件。发布流程会从该目录的片段生成版本对应的CHANGELOG-vX.Y.rst而devel分支上只有片段、没有生成好的 changelog见 changelogs/README.md。本文说明如何命名和编写片段使其满足changelogs/config.yaml的 sections 约束并通过ansible-test sanity的 changelog 检查。何时必须新增片段context/documentation-standards.md 给出的 changelog 要求是改动需要在changelogs/fragments/中以 YAML 文件形式记录每个 PR 创建一个新的片段文件绝不复用已有片段以避免合并冲突片段结构遵循 changelogs/config.yaml 中sections键定义的分区提交前核对片段使用的 section 是否合法。context/contributing.md 同时要求所有 PR 都面向devel分支提交片段应随 PR 一起进入devel。文件命名规则命名约定来自 context/documentation-standards.md有关联 issue 时{issue_number}-{short-description}.yml例如86319-ssh_askpass_prompt.yml没有 issue 时{component}-{description}.yml例如 alpine_user_mod.yml。sanity 检查器实际接受的扩展名是.yml和.yaml两种见 changelog.py 中allowed_extensions (.yml, .yaml)仓库中也存在v2.22.0-initial-commit.yaml这样的.yaml片段。另外检查器禁止片段文件为点文件仅有.keep和.gitkeep例外所以在changelogs/fragments/下不要放入其他隐藏文件。使用合法的 sectionscontext/documentation-standards.md 要求先核对片段使用的 section 是否来自changelogs/config.yaml。当前该文件changelogs/config.yaml中sections键定义的合法取值及其展示名称为section 键展示名称major_changesMajor Changesminor_changesMinor Changesbreaking_changesBreaking Changes / Porting Guidedeprecated_featuresDeprecated Featuresremoved_featuresRemoved Features (previously deprecated)security_fixesSecurity FixesbugfixesBugfixesknown_issuesKnown Issues片段就是一个以这些键为顶层键的 YAML 文件值是该 section 下的条目列表。配置中keep_fragments: true意味着发布后片段会被保留notesdir: fragments指定了片段目录。条目格式约定条目格式来自 context/documentation-standards.md- {component} - {description} ({optional URL to GH issue})即以组件名开头破折号后是改动描述括号内是可选的 GitHub issue URL。条目内容支持 Sphinx 标记代码引用使用双反引号code。context/coding-style.md 还要求 docstring、注释和 changelog 片段尽量一行一句话避免超长行。仓库中现成的片段示例可以直接参照。带 issue URL 的 bugfix77691-git-track-submodules-branch.ymlbugfixes: - git - use the branch configured in .gitmodules or the remote HEAD instead of hardcoding master when track_submodulesyes (https://github.com/ansible/ansible/issues/77691).minor change 条目86319-ssh_askpass_prompt.ymlminor_changes: - ssh connection plugin - inspect SSH_ASKPASS_PROMPT in SSH_ASKPASS script for reliability (https://github.com/ansible/ansible/issues/86319)不带 issue URL 的条目sort_obfuscation.ymlbugfixes: - module_utils sanitize_keys and remove_value functions now sort their input to ensure matching subsets are always obscured.按自己的改动选择对应 section套用以上结构即可完成片段。用 ansible-test sanity 验证context/running-tests.md 说明 sanity 测试不需要--docker且应对整个变更集而不只是正在编辑的文件跑 sanity。与 changelog 相关的命令# 对单个片段路径运行 sanity路径相对仓库根目录 ansible-test sanity -v changelogs/fragments/86319-ssh_askpass_prompt.yml # 只运行名为 changelog 的 sanity 测试 ansible-test sanity -v --test changelog # 查看全部 sanity 结果 ansible-test sanity -vchangelog 检查的行为见 changelog.py只拦截changelogs/config.yaml和changelogs/fragments/下的文件定义于 changelog.json 的prefixes校验扩展名只能是.yml或.yaml点文件直接报错确认changelogs/config.yaml存在缺失时输出config file does not exist对上述片段执行python -m antsibull_changelog lint由 antsibull-changelog 工具检查片段内容与 sections 的匹配性。检查通过即无对应报错输出出现类似file must not be a dotfile、extension must be one of: .yml, .yaml的提示时说明文件命名不合规而 lint 阶段的报错则指向片段内容如使用了config.yaml中不存在的 section 键。限制与说明devel分支不生成 changelog只有片段CHANGELOG-vX.Y.rst是在发布流程中从片段生成的changelogs/README.md。片段文件不要复用或改名已有片段一个 PR 对应一个新文件这是为了避免合并冲突context/documentation-standards.md。配置中release_tag_re、prelude_section_name: release_summary等键面向 changelog 生成流程编写片段时无需修改config.yaml本身只需让自己的 section 键与其中的sections列表一致。【免费下载链接】ansibleAnsible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.项目地址: https://gitcode.com/GitHub_Trending/ans/ansible创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考