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或风格调整。文档给出了这样做的两个具体理由增加 diff 体积会掩盖关键改动让 reviewer 更难识别真正重要的部分无关的风格性改动会引发不必要的来回讨论围绕风格与个人偏好的争论。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 和 PRUse GitHub templates when creating issues/PRs (.github/ISSUE_TEMPLATE/and.github/PULL_REQUEST_TEMPLATE/).仓库中这两组模板都是真实存在、可直接查看的Issue 模板.github/ISSUE_TEMPLATE/模板文件用途bug_report.yml缺陷报告结构化表单feature_request.yml功能请求documentation_report.yml文档问题internal_issue.md内部 Issuepre_release.yml预发布相关config.yml模板选择器全局配置其中 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通用 PR 模板Bug fix.md缺陷修复 PRDocumentation change.md文档修改 PRNew feature.md新功能 PRTests.md测试 PRUnclear purpose or motivation.md用途不明确 PR用于评审拦截通用模板 PULL_REQUEST_TEMPLATE.md 的结构是##### SUMMARY改动描述、理由与设计决策要求附Fixes #1234或复现步骤##### ISSUE TYPE四选一Bugfix / Docs / Feature / Test Pull Request。2.3 规则三与规则四模板字段的填写约定贡献规范对模板内关键字段给出了两条具体约定1Issuecomponent字段填写“相对项目根目录的文件路径”。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。2PR按模板列出的类型调整 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 修复Bug fixes仅回移到最新稳定版latest stable only关键 Bug 修复Critical bug fixes回移到最新稳定版 上一稳定版latest and previous stableBug fixes: backported to latest stable only. Critical bug fixes: backported to latest and previous stable.仓库中有两处证据印证这套机制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 更新”是一条被工具化支撑的实际工作流。.github/SECURITY.md声明 Ansible 的安全修复遵循“3-versions-back”支持政策。这解释了为什么关键修复回移范围是“最新 上一稳定版”两个版本——回移深度与官方支持窗口对齐超出窗口的旧版本不再接受修复。2.6 规则八安全问题走私密渠道不走 GitHubSecurity issues: contact securityansible.com privately, not via GitHub.安全漏洞不得通过 GitHub Issue/PR 公开渠道报告必须私下邮件 securityansible.com。这一条在仓库中形成闭环.github/SECURITY.md 是官方的安全政策入口说明支持版本范围与负责任披露responsible disclosure要求config.yml 的模板选择器里第一个联系项就是 “Security bug report”明确写有 “For all security related bugs, email securityansible.com instead of using this issue tracker”把试图在 Issue 区报告安全问题的用户第一时间导向正确渠道。三、提交改动前的自检清单将 contributing.md 的全部规则浓缩为提交前的 checklist改动是否只包含解决当前问题所必需的部分无夹带的格式化/重构/风格调整PR 目标分支是否为devel是否使用了 GitHub 模板Issue 走 .github/ISSUE_TEMPLATE/PR 走 .github/PULL_REQUEST_TEMPLATE/Issue 的component字段是否为相对项目根的路径PR 的 issue type 是否已收敛为单一类型Bugfix/Docs/Feature/Test若针对稳定版报 Bug是否已确认devel上未修复修复的归属层级是否判断正确普通 Bug → 仅最新稳定版Critical Bug → 最新 上一稳定版是否安全漏洞是则立即停止公开报告改发邮件 securityansible.com是否附带了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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考