Flink CDC 贡献指南从环境搭建到代码评审的完整开发者手册【免费下载链接】flink-cdcFlink CDC is a streaming data integration tool项目地址: https://gitcode.com/GitHub_Trending/flin/flink-cdcFlink CDC 是一个由开放社区共同维护的流式数据集成工具本文基于官方文档 contribute-to-flink-cdc.md 及其配套的仓库工程实践AGENTS.md、根 pom.xml、.github/PULL_REQUEST_TEMPLATE.md 与 CI 工作流系统讲解向 Flink CDC 贡献代码的完整路径如何搭建 JDK 11 开发环境、按什么流程提交 PR、CI 会检查哪些内容以及社区评审一个 Pull Request 时的三大检查维度帮助你在提交第一个 PR 前建立准确、可执行的认知。贡献 Flink CDC 的四种方式官方文档开篇明确贡献 Flink CDC 远不止写代码社区欢迎任何人以任何形式参与。文档中给出了四类参与方向的对照表方向说明Report Bug报告缺陷在 Flink JIRA 中创建 issue 并在Component/s中选择Flink CDC附上尽可能详细的问题描述和复现步骤Contribute Code贡献代码按照文档中的 Code Contribution Guide 执行Code Reviews代码评审按照文档中的 Code Review Guide 参与评审Support Users支持用户在 Flink 用户邮件列表中回答用户问题并关注 JIRA 中实为用户提问的工单文档同时建议如果不确定问题归属可以直接向 Dev 邮件列表求助。对于代码贡献者而言后文两节——代码贡献指南与代码评审指南——是核心操作依据而评审指南对贡献者同样重要因为它等于“CI 人工评审”的检查清单提前自查可以显著减少来回修改。开发环境JDK 11 基线与构建命令JDK 11 基线文档明确指出Flink CDC 以 JDK 11 作为基础版本baseline要求开发者确认开发环境正确配置。这一说法与根 pom.xml 完全一致java.version11/java.version source.java.version11/source.java.version target.java.version11/target.java.version同时 pom 中还定义了java-17-target等 profilejava.version17/java.version即 17 是可选的交叉编译目标而 11 是所有代码必须能编译和运行的下限。从 AGENTS.md 的前置条件看完整开发环境还需要Maven 3.8.6 或更高版本Git以及 Unix-like 环境Linux、macOS、WSLDocker运行集成测试与 e2e 测试必需。Flink 版本双轨制flink2 profile值得注意的是当前仓库同时维护两套 Flink 运行时版本这直接决定了你的构建参数。根 pom.xml 中定义flink.1.x.version1.20.3/flink.1.x.version flink.2.x.version2.2.0/flink.2.x.version flink.version${flink.1.x.version}/flink.version默认 profile 使用 Flink 1.20.3加上-Pflink2则切换到 Flink 2.2.0。这一设计也体现在模块结构上flink-cdc-flink1-compat 与 flink-cdc-flink2-compat 分别是对应的兼容层。因此贡献代码时改动如果触碰 Flink API需要在两个 profile 下都验证。常用构建与测试命令AGENTS.md 给出了一组可直接复制的命令覆盖了从快速开发构建到单测、单方法测试的常见场景# 快速开发构建跳过测试与格式检查 mvn clean install -DskipTests -Dspotless.check.skiptrue -Dcheckstyle.skiptrue # 完整构建默认面向 Flink 1.x mvn clean package -DskipTests # 完整构建面向 Flink 2.x mvn clean package -DskipTests -Pflink2 # 单模块构建例如 flink-cdc-common-am 表示同时构建其依赖模块 mvn clean package -DskipTests -pl flink-cdc-common -am # 模块级全部测试 / 单测类 / 单测方法 mvn verify -pl flink-cdc-common mvn -pl flink-cdc-common -DtestMyTest test mvn -pl flink-cdc-common -DtestMyTest#myMethod test代码风格方面提交前必须执行mvn spotless:apply # 自动格式化 mvn spotless:check # 校验CI 实际会检查什么文档第 4 步要求“确认 CI 通过”而 .github/workflows/flink_cdc_ci.yml 定义了 CI 的真实组成可作为本地自测的对照清单License Check先mvn package -DskipTests编译出 jar再运行 tools/ci/license_check.rb 检查第三方依赖许可Common 单元测试核心模块core在 JDK 11 下运行并额外有一组-Pflink2的 2.x 测试Pipeline / Source 连接器单元测试覆盖 doris、kafka、mysql-pipeline、postgres-pipeline 等全部 pipeline 连接器以及 mysql-source、oracle、sqlserver 等 source 连接器同样双 Flink 版本各跑一遍E2E 测试pipeline_e2e与source_e2e分别在 Flink 1.20.3 与 2.2.0 下、以并行度 1 和 4 两个矩阵运行对应 flink-cdc-e2e-tests 下的 source 与 pipeline 两套 e2e 模块。也就是说一个合格的 PR 至少要保证格式通过 spotless、checkstyle 无违规配置在 tools/maven/checkstyle.xml在validate阶段强制执行failOnViolationtrue、单元测试与 e2e 测试在两套 Flink 版本下均通过。代码贡献五步流程文档的 Code Contribution Guide 给出了标准化的贡献流程原文为英文此处完整翻译并结合仓库细节扩充在目标 issue 下留言。最好解释你对该 issue 的理解和你的设计方案如果可能附上你的 POC概念验证代码等 issue 分配给你之后再开始实现。提交信息必须遵循格式[FLINK-xxx][xxx] xxxxxxx其中xxx是 JIRA 工单号与受影响组件名向 Flink CDC 仓库创建 PR注意请在你的 fork 仓库上启用 GitHub Actions否则 CI 不会在你的 PR 上运行找一位评审人 Review 你的 PR并确保 CI 通过Flink CDC 的 committer 检查贡献是否满足要求并合并代码到主干。提交信息格式的仓库级印证AGENTS.md 对文档中的[FLINK-xxx][xxx] xxxxxxx格式做了更细的补充常规提交[FLINK-XXXX][component] Descriptioncomponent为受影响区域例如connect/mysql、pipeline-connector/kafka、docs、runtime无 JIRA 工单的小修[hotfix][component] ...或[docs][component] ...纯 CI 变更[ci] DescriptionPR 标题格式与提交信息一致非琐碎变更必须有对应 JIRA 工单。PR 模板与 AI 工具披露提交 PR 时需完整填写 .github/PULL_REQUEST_TEMPLATE.md模板包含四个必填部分What is the purpose简述 PR 解决的问题或引入的功能尽可能关联 Flink JIRA 工单Brief change log列出关键变更Verifying this change说明验证方式新增/更新的单元或集成测试位置或手动测试方法Documentation是否引入新功能、功能如何文档化。此外模板末尾新增了生成式 AI 工具披露要求若使用了 AI 工具协作开发需勾选复选框、填写工具名与版本并保留Generated-by: [Tool Name and Version]注释行遵循 Apache 基金会的生成式工具指导。AGENTS.md 还特别强调不要为 AI 代理添加Co-Authored-By应使用Generated-by字段。代码评审指南三个必查维度文档的 Code Review Guide 规定每次评审都需要检查以下三个方面贡献者可以把它当作提交前自查清单1. 这个 PR 是否有清晰的描述检查 PR 是否描述充分、足以支撑一次好的评审。对于琐碎的修改和修复不要求长篇描述。这正对应 PR 模板中的 purpose 与 change log 两节。2. 整体代码质量是否达到社区维护标准文档列出了具体检查项每一条都有仓库内的制度或工具对应代码是否遵循正确的软件工程实践是否正确、健壮、可维护、可测试变更是否性能敏感修改性能关键路径时是否对性能影响有考量测试覆盖是否充分测试执行是否够快从 AGENTS.md 的测试规范看社区要求新行为覆盖成功、失败与边界用例单元测试命名为*Test.java依赖 Docker 或真实数据库的集成测试命名为*ITCase.java修复 bug 时应先验证“新测试在不带修复时失败、带上修复后通过”。依赖变更时NOTICE 文件是否更新这与 CI 中的 License Checktools/ci/license_check.rb相呼应——依赖许可变化必须同步更新 NOTICE 与许可证声明。提交信息是否遵循要求的格式即前文所述的[FLINK-XXXX][component] ...。从源码结构看代码质量检查还落在更细的编码规范上AGENTS.md 与 tools/maven/checkstyle.xml导入顺序为org.apache.flink.cdc→org.apache.flink→ 其他第三方 →javax→java静态导入最后禁止星号导入测试代码必须使用 JUnit 5Jupiter与 AssertJ禁用 JUnit 4、org.junit.jupiter.api.Assertions与 Hamcrest禁止直接引入 Guava应使用flink-shaded-guava日志必须用 SLF4J 参数化占位符而非字符串拼接if/for/while等控制块必须写大括号注释使用英文且保持精简所有新增文件必须带 Apache License 2.0 头部——文档中示例的每个源文件开头的 ASF 许可注释块即为此要求。3. 文档是否同步更新文档明确要求如果 PR 引入了新功能该功能必须被文档化。具体到本仓库AGENTS.md 指出文档站基于 Hugo英文内容在docs/content/、中文内容在docs/content.zh/新增功能时需要同时更新中英文两份文档。此外纯文档变更不会影响代码 CI.github/workflows/flink_cdc_ci.yml 的paths-ignore明确忽略了docs/**与README.md而文档站点由独立的build_docs.yml工作流构建。贡献者边界先问再做的变更类型除了评审清单AGENTS.md 还界定了哪些变更属于“先与社区讨论再动手”的范畴对避免返工非常实用新增或修改Public/PublicEvolving注解这是对用户的 API 稳定性承诺引入新依赖跨模块的大规模重构改变序列化格式或 checkpoint 行为修改热路径单条记录处理、状态访问可能影响性能的代码。API 稳定性注解体系本身也值得贡献者了解Public跨大版本稳定、PublicEvolving可能在小版本变化、Experimental随时可变、Internal无稳定性承诺用户不应依赖。小结向 Flink CDC 贡献代码的路径可以浓缩为一句话JDK 11 Maven 环境下按[FLINK-XXXX][component]格式提交PR 前跑通 spotless、checkstyle 与双 Flink 版本的测试并按“描述清晰、质量达标、文档同步”三维度自查。文档本身docs/content/docs/developer-guide/contribute-to-flink-cdc.md定义了流程与评审标准而 AGENTS.md、.github/PULL_REQUEST_TEMPLATE.md、.github/workflows/flink_cdc_ci.yml 与 pom.xml 则给出了可直接执行的工程细节两者对照阅读即可覆盖从 fork、开发、测试到 PR 合并的完整闭环。【免费下载链接】flink-cdcFlink CDC is a streaming data integration tool项目地址: https://gitcode.com/GitHub_Trending/flin/flink-cdc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考