TiDB PR 元数据守护指南：基于 tidb-pr-metadata-guard 保障标题范围、模板字段与 Bot 校验清单不破损-平芜编程栈

TiDB PR 元数据守护指南：基于 tidb-pr-metadata-guard 保障标题范围、模板字段与 Bot 校验清单不破损

【免费下载链接】tidbTiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.项目地址: https://gitcode.com/GitHub_Trending/ti/tidb

在 TiDB 这类大规模分布式数据库仓库中，Pull Request 不只是代码差异的载体，其标题、正文、隐藏 HTML 注释和测试清单都会被 Bot 自动解析，直接决定 PR 能否顺利合入。本文以仓库中仓库级技能文档 tidb-pr-metadata-guard 为主体，完整展开其工作流、可修改字段边界、隐藏注释保护规则和标签排障方法，并结合 PR 模板、AGENTS.md 与 issue-metadata-guard 技能等仓库真实文件，讲清楚"在创建或编辑 TiDB PR 时，哪些内容绝不能动、哪些字段可以安全修改、出了问题如何按 Bot 标签回溯排查"。

一、技能定位与触发场景

tidb-pr-metadata-guard是 TiDB 仓库.agents/skills目录下的一个仓库级（repo-level）Agent 技能，其定义文件位于 .agents/skills/tidb-pr-metadata-guard/SKILL.md。技能文档的 frontmatter 中给出的触发条件是：

创建或编辑 TiDB 的 pull request；
PR 正文更新、从 PR 关联 issue、测试清单（checklist）更新；
调查do-not-merge/needs-tests-checked之类的 Bot 标签。

技能的核心目标在 Overview 一节说得非常直接：在保持仓库要求的 PR 结构的前提下，只编辑可变动（mutable）字段。它要求在执行任何 PR 正文修改之前，先阅读 .github/pull_request_template.md——这是 TiDB PR 元数据正确性的"源头契约"。

这一技能在仓库整体 Agent 政策中的位置也有明确依据：AGENTS.md 的 Quick Decision Matrix 中规定"Creating a PR or editing PR metadata" 时 SHOULD 使用.agents/skills/tidb-pr-metadata-guard，以保护 PR 模板、标题 scope 和 Bot 解析的清单节；.agents/skills/README.md 也将其列为当前的 operational workflow skills 之一。

二、前置契约：TiDB PR 模板的真实结构

技能反复强调"以模板为起点"，因此在动手前先看清模板长什么样。.github/pull_request_template.md 的关键结构如下：

文件顶部隐藏注释（）：声明了 PR 标题格式——
- pkg [, pkg2, pkg3]: what's changed
- *: what's changed
### What problem does this PR solve?节：要求先建 issue，且"必须有一行以Issue Number:开头"，通过close或ref关联相关 issue；模板中的占位行为Issue Number: close #xxx和Problem Summary:。
### What changed and how does it work?节：描述改动内容与工作原理。
### Check List节，包含三组清单：
- Tests（Tests ）：Unit test / Integration test / Manual test / No need to test 四个复选框，其中No need to test下有嵌套子项与说明性 HTML 注释；
- Side effects：CPU/内存性能退化、向后兼容性破坏等；
- Documentation：用户行为、语法、变量、实验特性、MySQL 兼容性等影响面。
### Release note节：以```release-note ```代码块承载发布说明，默认值为None，并附注 compatibility change、improvement、bugfix、new feature 需要 release note。

这些结构不是装饰：模板中的Tests行注释、Issue Number:行、release-note块都是 Bot 与 reviewer 解析的锚点，这正是技能要守护的对象。

三、七步工作流详解

技能文档的 Workflow 一节给出了 7 条步骤，以下逐一展开并结合仓库文件说明其约束依据。

3.1 使用英文撰写 PR 标题与描述

第 1 步要求 PR 标题和描述一律用英文。这与 AGENTS.md 中"Leave verifiable evidence""Keep diffs minimal"的整体协作纪律一致——统一的英文元数据保证 Bot 解析规则（基于英文标题格式、英文清单文案）可稳定匹配。

3.2 新 PR：以模板为起点，而不是从零写正文

第 2 步包含四个要点：

标题格式：pkg [, pkg2, pkg3]: what is changed或*: what is changed。这里的pkg指的是TiDB 模块域（module area），而不是字面的 Go 包路径。技能文档给出明确示例：pkg/planner/core下的改动通常应映射为planner，而非pkg/planner/core。结合 AGENTS.md 的 Repository Map（/pkg/planner/、/pkg/executor/、/pkg/session/、/pkg/ddl/等模块入口划分），可以推断模块域名称就是按pkg/下的一级目录语义抽象出来的（如planner、executor、ddl）。
使用gh pr create -T .github/pull_request_template.md：-T参数直接以仓库模板初始化 PR 正文，从机制上杜绝"手打正文漏字段"。
先在本地 Markdown 文件中填好模板再提交：技能第 6 步（file-based edits）进一步强化了这一做法——先把目标正文落到本地文件，与模板逐节比对后，再调用gh。这与 issue-metadata-guard 第 6 步"materialize the intended body into a local Markdown file, review against template before callinggh" 是同构的策略：GitHub 元数据编辑被规范化为"本地文件化 → 模板比对 → 提交"三步，把易错的网络 API 编辑变成可 diff、可复查的文件编辑。

3.3 已有 PR：只更新可变动小节

第 3 步划定了"安全修改目标（Safe targets）"白名单：

Issue Number:行；
Problem Summary:行；
### What changed and how does it work?标题之下的内容；
测试复选框的勾选状态与具体命令；
release-note代码块。

同时给出三条禁令：不要重命名标题（headings）、不要重排清单小节顺序、不要整体重写模板。对照 .github/pull_request_template.md，这些"禁改项"恰好就是 Bot 解析所依赖的结构锚点：### Check List下的Tests、Side effects、Documentation小节名和顺序、### Release note标题都是模板的固定骨架。白名单 + 禁令的组合，把"编辑 PR 正文"约束成了对模板的"填槽操作"，从结构上保证任何一次编辑后正文仍能被按模板假设来解析。

3.4 逐字保留隐藏 HTML 注释

第 4 步是全文最严格的约束：hidden HTML comments exactly（逐字保留）。具体包括：

Tests 这一整行保持不变——模板中它正是以这个形态存在（.github/pull_request_template.md 第 31 行），注释文案本身承担了"至少勾选一项"的语义提示；
No need to test的嵌套块及其 HTML 注释（模板中的> - [ ] I checked and no code files have been changed.与> ）保持不变；
不得删除或改写解释 issue 关联、release-note 行为的模板注释（即### What problem does this PR solve?下解释Issue Number:要求的注释块，以及### Release note下"compatibility change, improvement, bugfix, and new feature need a release note"的注释）。

从模板结构可以推断，这些注释之所以需要"逐字"保留，是因为 Markdown 渲染后它们不可见、人在 PR 页面容易忽略，而某些解析逻辑仍以其文本形态作为识别锚点；一旦被 Markdown 编辑器"顺手清理"，Bot 侧就可能无法按预期解析。

3.5 需要新关联 issue 时：先走 issue 守护流程

第 5 步规定：如果 PR 需要新的关联 issue，先用 tidb-issue-metadata-guard 创建或确认 issue，然后只修补 PR 正文中的Issue Number:一行。这条规则把"元数据链条"分成两段独立守护：issue 侧由 issue 守护技能保证模板与标签卫生（如component/*标签、severity 规则），PR 侧只负责把close #<id>/ref #<id>填进Issue Number:行，避免一次编辑同时破坏两边契约。

3.6 文件化编辑 GitHub 元数据

第 6 步（前文 3.2 已述）：把目标 issue 正文或 PR 正文物化为本地 Markdown 文件，调用gh之前先与模板比对。这条在自动化 Agent 场景下价值尤高——Agent 可以直接对本地文件做精确的字符串级修改与 diff，而不是通过 API 整段覆写正文。

3.7 更新后回读 PR 并核对 Bot 门控标签

第 7 步要求任何 PR 正文更新后重新读取 PR，检查 Bot 门控标签是否如预期变化，点名两个标签：

do-not-merge/needs-linked-issue
do-not-merge/needs-tests-checked

并给出排障动作：如果标签出乎意料地残留，先把当前正文与 .github/pull_request_template.md 做 diff，再考虑其他修改。这一顺序很重要：残留标签几乎总是"正文相对模板发生了结构性偏移"（Issue Number:行缺失、Tests注释被改写、复选框全部未勾），先 diff 能直接定位偏移点，而不是盲目改正文碰运气。

四、快速自检清单（Quick Checks）

技能文档末尾给出 4 条可机械执行的自检项，适合作为提交或改完 PR 元数据后的最终核对表：

自检项	校验要点	模板/技能依据
`Issue Number:`行存在	该行可用完整关键字法引用一个或多个 issue，如`close #<id>`、`ref #<id>`	.github/pull_request_template.md 要求"MUST be one line starting with`Issue Number:`"；docs/agents/agents-review-guide.md 的 PR 检查项同样要求该行带`close #<id>`或`ref #<id>`
PR 标题使用模块域 scope	形如`planner`、`executor`或`*:`，而非`pkg/planner/core`这类原始 Go 包路径	技能 Workflow 第 2 步与 Quick Checks 第 2 条
`Tests`行含模板 HTML 注释原文	`Tests <!-- At least one of them must be included. -->`逐字存在	技能 Workflow 第 4 步
测试清单至少勾选一项	勾 Unit / Integration / Manual test 之一；或勾选`No need to test`并给出理由	模板注释 "At least one of them must be included"

其中 release note 一侧也值得注意：模板的### Release note节要求 release-note 代码块存在（默认None），compatibility change、improvement、bugfix 与新特性都需要撰写说明——这与技能把release-note块列入"安全修改目标"相呼应：它是允许编辑的，但编辑只发生在代码块内部。

五、一个可复制的最小操作流程

综合以上规则，创建或更新 TiDB PR 元数据的最小合规流程如下（所有路径均相对仓库根目录）：

# 0. 阅读模板，建立结构基线（只读） cat .github/pull_request_template.md # 1. 新建 PR：以模板初始化，标题采用模块域 scope # 示例：planner: fix join order when ... 或 *: ... gh pr create -T .github/pull_request_template.md \ --title "planner: <what is changed>" \ --body-file ./pr_body.md # pr_body.md 为本地填好的模板副本

对已有 PR 的更新：

拉取当前 PR 正文，落到本地文件；
仅对Issue Number:、Problem Summary:、### What changed and how does it work?内容、测试复选框与release-note块做修改；
修改前确认Tests 、No need to test嵌套块及模板注释均逐字保留（可直接与 .github/pull_request_template.md diff 核对）；
更新后回读 PR，核对do-not-merge/needs-linked-issue与do-not-merge/needs-tests-checked是否按预期变化；若残留，先 diff 正文与模板。

六、与周边机制的衔接

从源码结构看，这个技能并非孤立存在，而是嵌在仓库的 Agent 协作体系里：

与 AGENTS.md 的政策层衔接：AGENTS.md 声明"Policy belongs inAGENTS.md; detailed command playbooks SHOULD live indocs/agents/*, and skills SHOULD provide entrypoint workflows that reference those playbooks"，.agents/skills/README.md则统一索引各操作型技能，避免多份文档清单漂移。
与 issue 侧技能成对：PR 的Issue Number:行指向的 issue，其创建与标签规范由 tidb-issue-metadata-guard 守护（模板选择、component/*标签、severity 规则、/label回退手段），两者共同构成"issue → PR"元数据链。
与评审自检衔接：docs/agents/agents-review-guide.md 的清单中同样出现 "PR requirements include theIssue Number:line withclose #<id>orref #<id>" 与 "PR description still requires.github/pull_request_template.md" 检查项，说明 PR 元数据约束同时服务于 Agent 自检与人工评审两条路径。

七、小结

tidb-pr-metadata-guard给出的是一套"契约式"的 PR 元数据操作规范：以 .github/pull_request_template.md 为不可破坏的结构基线，用模块域 scope 标题（planner: .../*: ...）、Issue Number: close #<id>关键字法、逐字保留的TestsHTML 注释和至少勾选一项的测试清单，保证 Bot 门控标签（do-not-merge/needs-linked-issue、do-not-merge/needs-tests-checked）能按预期解析；对已有 PR 则严格限定可改字段白名单，禁止重命名标题、重排清单或整体重写。掌握这套规则后，无论是人工提交还是 Agent 批量更新 TiDB 的 issue 与 PR，都能把元数据编辑控制在"可 diff、可验证、可回溯"的安全边界内。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考