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-levelAgent 技能其定义文件位于 .agents/skills/tidb-pr-metadata-guard/SKILL.md。技能文档的 frontmatter 中给出的触发条件是创建或编辑 TiDB 的 pull requestPR 正文更新、从 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]: whats changed*: whats 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节包含三组清单TestsTests !-- At least one of them must be included. --Unit test / Integration test / Manual test / No need to test 四个复选框其中No need to test下有嵌套子项与说明性 HTML 注释Side effectsCPU/内存性能退化、向后兼容性破坏等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 evidenceKeep 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 !-- At least one of them must be included. --这一整行保持不变——模板中它正是以这个形态存在.github/pull_request_template.md 第 31 行注释文案本身承担了至少勾选一项的语义提示No need to test的嵌套块及其 HTML 注释模板中的 - [ ] I checked and no code files have been changed.与 !-- Or your custom No need to test reasons --保持不变不得删除或改写解释 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-issuedo-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 withIssue Number:docs/agents/agents-review-guide.md 的 PR 检查项同样要求该行带close #id或ref #idPR 标题使用模块域 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 代码块存在默认Nonecompatibility 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 !-- At least one of them must be included. --、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 #idorref #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、可验证、可回溯的安全边界内。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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-levelAgent 技能其定义文件位于 .agents/skills/tidb-pr-metadata-guard/SKILL.md。技能文档的 frontmatter 中给出的触发条件是创建或编辑 TiDB 的 pull requestPR 正文更新、从 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]: whats changed*: whats 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节包含三组清单TestsTests !-- At least one of them must be included. --Unit test / Integration test / Manual test / No need to test 四个复选框其中No need to test下有嵌套子项与说明性 HTML 注释Side effectsCPU/内存性能退化、向后兼容性破坏等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 evidenceKeep 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 !-- At least one of them must be included. --这一整行保持不变——模板中它正是以这个形态存在.github/pull_request_template.md 第 31 行注释文案本身承担了至少勾选一项的语义提示No need to test的嵌套块及其 HTML 注释模板中的 - [ ] I checked and no code files have been changed.与 !-- Or your custom No need to test reasons --保持不变不得删除或改写解释 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-issuedo-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 withIssue Number:docs/agents/agents-review-guide.md 的 PR 检查项同样要求该行带close #id或ref #idPR 标题使用模块域 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 代码块存在默认Nonecompatibility 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 !-- At least one of them must be included. --、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 #idorref #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、可验证、可回溯的安全边界内。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考