企业官网建设流程全解析

如何为 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/下不要放入其他隐藏文件。

使用合法的 sections

context/documentation-standards.md 要求先核对片段使用的 section 是否来自changelogs/config.yaml。当前该文件（changelogs/config.yaml）中sections键定义的合法取值及其展示名称为：

片段就是一个以这些键为顶层键的 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 的 bugfix（77691-git-track-submodules-branch.yml）：

bugfixes: - git - use the branch configured in ``.gitmodules`` or the remote HEAD instead of hardcoding ``master`` when ``track_submodules=yes`` (https://github.com/ansible/ansible/issues/77691).

minor change 条目（86319-ssh_askpass_prompt.yml）：

minor_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.yml）：

bugfixes: - 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 -v

changelog 检查的行为（见 changelog.py）：

1. 只拦截changelogs/config.yaml和changelogs/fragments/下的文件（定义于 changelog.json 的prefixes）；
2. 校验扩展名只能是.yml或.yaml，点文件直接报错；
3. 确认changelogs/config.yaml存在，缺失时输出config file does not exist；
4. 对上述片段执行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