企业官网建设流程全解析

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。

它的核心工作原则只有两条：

1. 优先采用用户自己的变更摘要——用户描述是意图的首要来源；
2. 用当前分支的 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] Description

4.1 Type 的选择

根据改动的主导性质选择Type，完整映射如下：

4.2 Module 的选择

根据改动的主导路径选择Module，并可附加SubModule提示：

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 needed

5.2 基于证据写正文

• 描述 diff 的确切范围，避免空泛套话；
• 用户已给出摘要时，以其措辞作为第一节的骨架；用户未给摘要时，从变更文件、增删行和近期提交中推断目的；
• 纯文档改动要说明更新了哪些文档、修正或删除了什么；
• checklist 的意图与仓库模板保持一致，即使个别链接或措辞已变化；
• 默认所有 checkbox 保持未勾选，除非当前证据明确支持勾选。

5.3 Checklist 背后的仓库五件套

Checklist 中最值得展开的是连接器改动那一条，它在仓库中的落点全部真实存在，改动连接器时逐一核对即可：

1. plugin-mapping.properties：位于仓库根目录，是插件名到 artifactId 的映射表，SeaTunnel 据此解析用户配置中模块对应的 Jar 包名；
2. seatunnel-dist/pom.xml：发行包聚合 pom，例如其中同时收录了connector-kafka（第 253 行）与connector-milvus（第 872 行）等全部连接器依赖；
3. .github/workflows/labeler/label-scope-conf.yml：基于变更文件路径自动打 CI label 的配置，几乎为每个连接器定义了独立的 glob 规则（如kafka、jdbc、milvus、cdc等），并配有!seatunnel-connectors-v2/connector-!(xxx)/**的反向排除逻辑，确保 label 精确命中；
4. 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 等场景的.conf）；
5. config/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 仓库既有的自动化体系，理解这条链路有助于在起草时就主动对齐：

1. 自动打标：.github/workflows/labeler/label-scope-conf.yml 根据 diff 路径自动为 PR 打上模块级 label（如Zeta、api、core、connectors-v2、transform-v2以及各连接器名），与正文 Module 推断互为印证；相关触发器位于 .github/workflows/add-label.yml；
2. CI 检查：.github/workflows/backend.yml 等流水线会执行构建与测试，这与本地./mvnw验证基线对应；
3. 合并队列：.github/workflows/merge_queue.yml 定义了merge_group触发的 Merge Queue 构建任务，合并前会再次执行完整校验；
4. 文档与兼容性要求：正文 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