企业官网建设流程全解析

Ansible ansible-core 贡献指南：devel 分支流程、Issue/PR 模板与 Backport 政策

【免费下载链接】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-core 仓库中的 贡献规范 展开，系统讲解向该项目提交代码时必须遵循的两条核心规则——保持改动聚焦与分支/发布管理。读完本文，你将明确所有 PR 应指向哪个分支、如何正确填写仓库自带的 Issue/PR 模板（含component字段的填写约定）、Bug 修复应按什么层级回移（backport）到稳定分支，以及安全漏洞的私密报告渠道，并了解这些规则在仓库中对应的真实模板文件与工具脚本。

一、核心原则：保持改动聚焦（Keep changes focused）

贡献规范 开宗明义地提出了第一条规则：

每次改动应仅限于解决当前问题所必需的范围。避免在同一次改动中夹带无关的重排版（reformatting）、重构（refactoring）或风格调整。

文档给出了这样做的两个具体理由：

1. 增加 diff 体积会掩盖关键改动，让 reviewer 更难识别真正重要的部分；
2. 无关的风格性改动会引发不必要的来回讨论（围绕风格与个人偏好的争论）。

1.1 这条规则在仓库中的落点

从源码结构看，这条“聚焦”原则直接对应 ansible-core 的评审基础设施：

• 改动必须附带 changelog 片段：仓库 changelogs/fragments/ 目录下存放了大量形如87180-crypt-fixes.yml、86656-fix-step-in-free-strat.yml的片段文件，文件名惯例为“Issue/PR 编号-简短描述.yml”。也就是说，每个聚焦的最小改动单元对应一个最小 changelog 片段，二者在粒度上天然匹配——如果你在一次 PR 里混入了多个不相关改动，就无法用一个片段准确描述它。
• changelogs/README.md 说明：发布时版本特定的CHANGELOG-vX.Y.rst是由fragments目录生成的；devel分支本身没有生成好的 changelog，只有片段。
• changelogs/config.yaml 定义了片段归类的 section 结构：major_changes、minor_changes、breaking_changes、deprecated_features、removed_features、security_fixes、bugfixes、known_issues等，且配置中keep_fragments: true（片段在生成后保留）、always_refresh: true。这要求每个改动都能清晰归入其中一类，进一步倒逼改动本身保持单一主题。

1.2 配套的开发规范文档

仓库 context/ 目录专门存放“供人类与 AI Agent 共同使用”的 ansible-core 开发上下文文档。除了本文解读的 contributing.md 外，与“保持改动聚焦”直接相关的还有：

• coding-style.md —— Python 版本、依赖、代码格式化与语法约定（避免风格争议的直接依据）；
• writing-tests.md —— 对 pull request 的测试要求（改动必须可测试、范围可控）；
• deprecation.md —— 向后兼容与弃用流程（重构/破坏性改动必须走弃用周期，不能顺手夹带）；
• running-tests.md 与 ci.md —— 如何用ansible-test跑测试及 CI 要求。

这些文档共同划定了“一次合格 PR”的边界：只做问题本身，风格遵守既有约定，测试与 changelog 片段齐全。

二、分支与发布管理（Branch and release management）

这是 contributing.md 的核心章节，规定了 7 条硬性规则。下面逐条展开，并给出仓库中的对应证据。

2.1 规则一：所有 PR 一律指向devel分支

All PRs target thedevelbranch.

所有 Pull Request 的目标分支都是devel，而不是任何稳定版本分支。稳定分支上的代码变化只能通过回移（backport）流程产生，这保证了：

• 新功能与重构只在devel上累积；
• 稳定分支的 diff 永远是devel中已验证改动的子集，便于审计。

2.2 规则二：必须使用 GitHub 模板创建 Issue 和 PR

Use GitHub templates when creating issues/PRs (.github/ISSUE_TEMPLATE/and.github/PULL_REQUEST_TEMPLATE/).

仓库中这两组模板都是真实存在、可直接查看的：

Issue 模板.github/ISSUE_TEMPLATE/：

其中 config.yml 设置了blank_issues_enabled: false（禁止空白 Issue，所有反馈必须套用模板或联系链接），并在contact_links中把安全类问题直接导向安全报告流程（见 2.5 节）。

以 bug_report.yml 为例，表单强制要求填写：

• Summary（问题简述，必填）；
• Component Name（组件名，必填，见 2.3 节）；
• Ansible Version（粘贴ansible --version原文输出）；
• Configuration（粘贴ansible-config dump --only-changed -t all输出，并提示用 grep 过滤 token/password 等机密值）；
• OS / Environment、Steps to Reproduce（最小复现用例，鼓励给出 playbook 原文）、Expected Results、Actual Results（建议加-vvvv详细级别运行后粘贴原文输出）；
• 末尾有 Code of Conduct 勾选框。

表单开头还特别提醒：提交前先在 GitHub 搜索是否已有同类报告，并“同时测试最新 release 与 devel 分支是否受影响”——这正是下一条规则的前置动作。

PR 模板.github/PULL_REQUEST_TEMPLATE/：

通用模板 PULL_REQUEST_TEMPLATE.md 的结构是：##### SUMMARY（改动描述、理由与设计决策，要求附Fixes #1234或复现步骤）+##### ISSUE TYPE（四选一：Bugfix / Docs / Feature / Test Pull Request）。

2.3 规则三与规则四：模板字段的填写约定

贡献规范对模板内关键字段给出了两条具体约定：

（1）Issue：component字段填写“相对项目根目录的文件路径”。

For issues: fill out thecomponentfield with project root relative file path.

对应到 bug_report.yml 中的Component Name字段（描述为“写下 rst 文件、模块、插件、task 或功能的短名，不确定就用最合理的猜测”，占位示例为dnf, apt, pip, user etc.）。按贡献规范，这里应填相对仓库根的路径，例如模块位于lib/ansible/modules/dnf.py、插件位于lib/ansible/plugins/connection/之下——这样机器人和 reviewer 可以直接定位到出问题的源码文件。该字段的说明还特别提醒：如果报告的功能/模块不在本仓库（很可能来自社区维护的 Collection），应到对应 Collection 的项目下另开 Issue。

（2）PR：按模板列出的类型调整 issue type。

For PRs: adjust the issue type in the template as listed in.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md.

即从 PULL_REQUEST_TEMPLATE.md 的ISSUE TYPE中删除其余选项、只保留一项。目录中按类型拆分出的独立模板（如 Bug fix.md 已预置- Bugfix Pull Request、Documentation change.md 预置- Docs Pull Request）就是“调整后的成品”，与“改动聚焦”原则呼应——PR 类型必须单一，混合类型意味着改动不聚焦，应拆分。

2.4 规则五：报 Bug 前先验证devel上是否已修复

Validate issues are fixed indevelbefore reporting against stable releases.

对稳定版本报告问题之前，必须先确认devel分支上该问题是否已经修复。bug_report.yml 开头的提示“Also test if the latest release and devel branch are affected too.”正是这一要求的操作化：只报稳定版、而devel已修好的问题属于无效反馈，会被驳回。

2.5 规则六与七：两级 Backport 策略

贡献规范按问题严重程度定义了两个不同的回移层级：

Bug fixes: backported to latest stable only. Critical bug fixes: backported to latest and previous stable.

仓库中有两处证据印证这套机制：

1. hacking/backport/目录提供回移维护脚本。backport_of_line_adder.py 用于向新的 backport PR 自动添加Backport of ...引用行，用法为./backport_of_line_adder.py <backport> <original PR>，第二参数传auto时脚本会尝试自动推断原始 PR；它依赖pygithub且要求设置GITHUB_TOKEN环境变量。这说明“PR 只进devel，稳定分支靠带引用的 backport PR 更新”是一条被工具化支撑的实际工作流。
2. .github/SECURITY.md声明 Ansible 的安全修复遵循“3-versions-back”支持政策。这解释了为什么关键修复回移范围是“最新 + 上一稳定版”两个版本——回移深度与官方支持窗口对齐，超出窗口的旧版本不再接受修复。

2.6 规则八：安全问题走私密渠道，不走 GitHub

Security issues: contact security@ansible.com privately, not via GitHub.

安全漏洞不得通过 GitHub Issue/PR 公开渠道报告，必须私下邮件 security@ansible.com。这一条在仓库中形成闭环：

• .github/SECURITY.md 是官方的安全政策入口，说明支持版本范围与负责任披露（responsible disclosure）要求；
• config.yml 的模板选择器里第一个联系项就是 “Security bug report”，明确写有 “For all security related bugs, email security@ansible.com instead of using this issue tracker”，把试图在 Issue 区报告安全问题的用户第一时间导向正确渠道。

三、提交改动前的自检清单

将 contributing.md 的全部规则浓缩为提交前的 checklist：

1. 改动是否只包含解决当前问题所必需的部分？无夹带的格式化/重构/风格调整？
2. PR 目标分支是否为devel？
3. 是否使用了 GitHub 模板？Issue 走 .github/ISSUE_TEMPLATE/，PR 走 .github/PULL_REQUEST_TEMPLATE/；
4. Issue 的component字段是否为相对项目根的路径？
5. PR 的 issue type 是否已收敛为单一类型（Bugfix/Docs/Feature/Test）？
6. 若针对稳定版报 Bug，是否已确认devel上未修复？
7. 修复的归属层级是否判断正确？普通 Bug → 仅最新稳定版；Critical Bug → 最新 + 上一稳定版；
8. 是否安全漏洞？是则立即停止公开报告，改发邮件 security@ansible.com；
9. 是否附带了changelogs/fragments/下的 changelog 片段，并能归入 config.yaml 定义的某一 section？

四、适用前提与边界说明

• 本文所有规则以当前仓库 context/contributing.md 的文本为准，适用于向 ansible-core 主仓库提交代码与报告问题；
• context/README.md 明确：该目录不是Ansible 使用文档，也不是模块/插件/Collection 开发指南——如果你要开发的是 Collection 内容而非 ansible-core 本身，应遵循对应的 Community/Collections 流程（bug_report.yml 的提示中也给出了相同分流建议）；
• Backport 脚本（hacking/backport/README.md）依赖pygithub与GITHUB_TOKEN，属于维护者工具，普通贡献者只需了解 backport PR 的Backport of ...引用惯例即可。

【免费下载链接】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