Apache SeaTunnel 提交 PR 全指南：标题规范、正文模板与全自动化检查链路

Apache SeaTunnel 提交 PR 全指南标题规范、正文模板与全自动化检查链路【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel导读Apache SeaTunnel 是一个多模态、高性能、分布式的海量数据集成工具社区协作高度依赖规范的 Pull Request 流程。仓库内提供了一份面向贡献者包括人类开发者和 AI Agent的可执行技能文档 .skills/seatunnel-pr-submit/SKILL.md用于从当前分支或 diff 起草并提交符合仓库规范的 PR。读完本文你将掌握 SeaTunnel PR 标题的[Type][Module][SubModule]推断规则、与官方模板逐节对齐的正文写法、checklist 中连接器五件套的落地细节以及如何在提交前诚实、可复现地完成本地验证。一、技能文档定位一份可执行的 PR 提交规范seatunnel-pr-submit是一个面向 Agent 的技能skill其description明确说明了适用场景当需要从当前分支或 diff 准备 PR 时推断合规的[Type][Module][SubModule] Description标题、按仓库要求填写 PR 模板、根据 git 历史或文件 diff 描述改动并在用户提供或省略变更摘要后打开 PR。它的核心工作原则只有两条优先采用用户自己的变更摘要——用户描述是意图的首要来源用当前分支的 diff 进行核实与补全——diff 只用于校正措辞、确认正确模块、捕捉明显不匹配。这决定了整个工作流的顺序先收集上下文 → 采纳用户摘要 → 推断标题 → 编写正文 → 诚实声明测试 → 提交 PR。二、第一步收集 PR 上下文动笔之前必须先检查当前的变更集。技能文档规定当分支已经领先于基线分支时优先使用已提交的分支变更如果用户是在提交前准备 PR则检查暂存区staged和未暂存unstaged的改动并在草稿中说明草稿反映的是工作区状态。推荐的命令全部为非交互式 git 命令可在任何终端直接执行git branch --show-current git status --short git diff --stat git diff --name-only git diff --cached --stat git log --oneline -5 sed -n 1,220p .github/PULL_REQUEST_TEMPLATE.md其中读取 .github/PULL_REQUEST_TEMPLATE.md 非常关键——正文必须与仓库当前模板的章节和 checklist 措辞保持一致而模板会随社区演进所以每次起草前都应重新读取而不是依赖记忆。如果存在 upstream 分支还应检查分支级的变更集精确定位本次 PR 相对基线的完整范围git log --oneline {upstream}..HEAD git diff --stat {upstream}...HEAD git diff --name-only {upstream}...HEAD三、第二步优先采用用户的摘要用户的描述是说明意图的主要依据diff 仅用于三件事润色措辞、确认正确的模块、捕捉明显的错误。如果用户的摘要与 diff实质性冲突技能文档要求暂停并指出不匹配而不是擅自提交 PR。这条规则防止 Agent 在信息矛盾时盲目猜测一个错误标题。四、第三步推断 PR 标题标题必须使用英文并采用以下两种格式之一[Type][Module] Description[Type][Module][SubModule] Description4.1 Type 的选择根据改动的主导性质选择Type完整映射如下SignalType新行为、新选项、新能力FeatureBug 修复或修正Fix优化、清理或不破坏兼容的精炼Improve紧急 CI、依赖或发版阻塞修复Hotfix仅文档改动Docs仅测试改动Test构建、工具链或维护工作Chore4.2 Module 的选择根据改动的主导路径选择Module并可附加SubModule提示Path patternModuleSubModule hintseatunnel-connectors-v2/...Connector-V2连接器名称seatunnel-transforms-v2/...Transform-V2Transform 名称seatunnel-engine/...Zeta引擎区域若明确seatunnel-core/...Core不需要时可省略seatunnel-api/...API不需要时可省略seatunnel-e2e/...E2E套件或连接器名称.github/...、CI 工作流文件CI工作流或 job 名称bin/...、shell 脚本Shell脚本名称tools/...Tools工具名称仅docs/...Docs通常省略子模块4.3 应用规则优先选取单一主导模块而不是罗列所有涉及的区域仅当某一个连接器、Transform 或区域在 diff 中明显占主导时才添加SubModule描述保持简洁、面向动作描述的是实际改动而不是开发过程标题中不得出现中文。技能文档给出的标准示例[Fix][Connector-V2][Milvus] Fix partition creation[Feature][Transform-V2] Support AES_GCM algorithm in FieldEncrypt[Improve][Zeta] Optimize multiple table job config parsing[Docs] Remove redundant lines from transform docs这与 .github/PULL_REQUEST_TEMPLATE.md 第 10-12 行注释中的要求一脉相承Name the pull request in the form [Feature] [component] Title of the pull request并补充了Hotfix、Bug等可替换的 Type 以及[hotfix] [docs] Fix typo in README.md doc这类小修复命名模式。也就是说SKILL.md 是把模板注释中的命名约定升级为了一套完整的表格化决策规则。五、第四步编写 PR 正文正文必须镜像 .github/PULL_REQUEST_TEMPLATE.md 的章节与 checklist 结构全文使用英文且以仓库模板为唯一事实来源——模板措辞未来变化时以模板为准。5.1 仓库模板的真实结构当前仓库模板的核心章节如下含模板注释中的编写指引### Purpose of this pull request !-- 描述 PR 目的例如 This pull request adds checkstyle plugin. -- ### Does this PR introduce _any_ user-facing change? !-- 注意此处指*任何*面向用户的改动包括文档修复等所有方面。 如果是请说明改动前后的行为差异尽可能提供控制台输出、描述或示例。 如果否写 No。 -- ### How was this patch tested? !-- 如果添加了测试请说明建议添加覆盖正反两种情况的测试用例。 如果测试方式不同于常规单元测试请逐步说明如何测试便于其他 reviewer 复现。 如果未添加测试请说明原因。 -- ### Check list * [ ] 新增 Jar 依赖时按 New License Guide 添加 License Notice * [ ] 必要时更新 docs 文档以描述新特性 * [ ] 必要时更新 incompatible-changes.md 说明不兼容改动 * [ ] 连接器代码贡献需检查以下文件是否更新 1. plugin-mapping.properties 2. seatunnel-dist 的 pom 文件 3. .github/workflows/labeler/label-scope-conf.yml 中的 ci label 4. seatunnel-e2e 中的 e2e 测试用例 5. config/plugin_config --SKILL.md 将其浓缩为四段式最小骨架### Purpose of this pull request 说明改了什么以及为什么。优先用 1 个短段落或 2 条平铺 bullet。提及实际改动的文件、模块或行为。 ### Does this PR introduce _any_ user-facing change? 如果用户能感知行为差异则写出差异纯文档或纯内部改动写 No。 ### How was this patch tested? 列出真实执行过的验证。绝不声称未运行过的测试。若尚未运行写 Not run yet.。 ### Check list - [ ] New dependency is documented under the New License Guide - [ ] Documentation is updated if needed - [ ] incompatible-changes.md is updated if needed - [ ] Connector changes include plugin-mapping.properties, seatunnel-dist pom, CI label, E2E, and plugin_config updates if needed5.2 基于证据写正文描述 diff 的确切范围避免空泛套话用户已给出摘要时以其措辞作为第一节的骨架用户未给摘要时从变更文件、增删行和近期提交中推断目的纯文档改动要说明更新了哪些文档、修正或删除了什么checklist 的意图与仓库模板保持一致即使个别链接或措辞已变化默认所有 checkbox 保持未勾选除非当前证据明确支持勾选。5.3 Checklist 背后的仓库五件套Checklist 中最值得展开的是连接器改动那一条它在仓库中的落点全部真实存在改动连接器时逐一核对即可plugin-mapping.properties位于仓库根目录是插件名到 artifactId 的映射表SeaTunnel 据此解析用户配置中模块对应的 Jar 包名seatunnel-dist/pom.xml发行包聚合 pom例如其中同时收录了connector-kafka第 253 行与connector-milvus第 872 行等全部连接器依赖.github/workflows/labeler/label-scope-conf.yml基于变更文件路径自动打 CI label 的配置几乎为每个连接器定义了独立的 glob 规则如kafka、jdbc、milvus、cdc等并配有!seatunnel-connectors-v2/connector-!(xxx)/**的反向排除逻辑确保 label 精确命中E2E 测试用例位于 seatunnel-e2e/seatunnel-connector-v2-e2e/ 下各连接器的 e2e 模块例如 connector-cdc-mysql-e2e/src/test/resources/mysqlcdc_to_mysql.conf 就是模板注释中推荐的 E2E 配置示例同一目录下还有数十个覆盖 GTID 偏移、多表模式、schema change、exactly-once 等场景的.confconfig/plugin_config通过--connectors-v2--分隔符枚举默认打包的插件清单新增连接器时需在此追加条目。六、第五步诚实地处理测试技能文档强调声称 PR 就绪之前应优先运行与改动范围匹配的仓库级验证。SeaTunnel 的常见基线命令是./mvnw spotless:apply ./mvnw -q -DskipTests verify ./mvnw test./mvnw spotless:apply应用代码格式化保证通过 CI 的格式检查./mvnw -q -DskipTests verify跳过测试完成构建与校验快速暴露编译/打包问题./mvnw test运行单元测试。当改动局部且用户希望缩小检查范围时可以运行更窄的验证但绝不虚构测试覆盖。如果验证尚未发生必须在 PR 正文中直接说明并在打开 PR 前推荐相应的验证命令。这条诚实原则与模板注释中If tests were not added, please describe why的要求完全一致。七、第六步提交 PR当用户要求打开 PR 时先准备好最终标题和正文再通过非交互式流程创建 PR。优先使用可用的 GitHub 集成如果回退到gh使用非交互式命令gh pr create --title ...[Type][Module][SubModule] Description... --body-file ...提交时需始终遵守以下约束严格遵守仓库的标题格式PR 正文保持英文只描述当前分支的变更集标题和正文中不提及任何其他助手或工具品牌不声称未发生的测试、文档或兼容性工作。八、输出格式草稿的标准交付形态当用户请求草稿时技能文档要求按如下格式返回便于直接评审或后续转交Title: [Type][Module][SubModule] Description Body: ### Purpose of this pull request ... ### Does this PR introduce _any_ user-facing change? ... ### How was this patch tested? ... ### Check list - [ ] ...如果用户同时提供了手动摘要则先整合摘要再用 diff 细化标题、补全缺失事实。这一输出格式与仓库模板章节一一对应确保了草稿在任何评审人人或机器面前都是一致的、可机读的结构。九、仓库侧的自动化支撑链路一份合规的 PR 提交后会进入 SeaTunnel 仓库既有的自动化体系理解这条链路有助于在起草时就主动对齐自动打标.github/workflows/labeler/label-scope-conf.yml 根据 diff 路径自动为 PR 打上模块级 label如Zeta、api、core、connectors-v2、transform-v2以及各连接器名与正文 Module 推断互为印证相关触发器位于 .github/workflows/add-label.ymlCI 检查.github/workflows/backend.yml 等流水线会执行构建与测试这与本地./mvnw验证基线对应合并队列.github/workflows/merge_queue.yml 定义了merge_group触发的 Merge Queue 构建任务合并前会再次执行完整校验文档与兼容性要求正文 checklist 指向的 docs/en/developer/new-license.md新依赖 License 指南与 docs/en/introduction/concepts/incompatible-changes.md不兼容变更登记都是合并前必须确认的环节。结语seatunnel-pr-submit技能的价值在于把 SeaTunnel 社区多年沉淀的 PR 规范固化成了一套确定性流程用 git 收集证据、以用户摘要为骨、按表格推断标题、以官方模板为准组织正文、诚实声明测试、非交互式提交。无论你是第一次向 SeaTunnel 提交 PR 的贡献者还是需要为 Agent 配置 PR 起草能力的维护者都可以把本文的标题规则、正文骨架、checklist 五件套与验证命令直接作为可复用的操作清单。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考