AWS SDK for Java v2 贡献指南从 Bug 报告到本地 CI 验证的完整工作流【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2本文以仓库根目录的 CONTRIBUTING.md 为主体完整梳理向 AWS SDK for Java v2 提交 Bug 报告、功能请求和代码变更的标准流程并结合 scripts/new-change、scripts/run-integ-test 与集成测试基类的源码解释本地运行 CI 检查单元测试、集成测试、Checkstyle、SpotBugs的真实机制与命令细节。读完后你可以独立完成一次规范、可被维护者接受的 Pull Request并知道如何用一条命令跑通本地构建与集成测试。三类社区协作入口Bug、功能请求与代码贡献AWS SDK for Java v2 面向社区开放三种协作方式各自有明确的入口与标签体系Bug Reports通过仓库的 Issue 表单提交使用bug与documentation标签追踪Feature Requests通过独立的 Feature Request 表单提交使用feature-request标签追踪Code Contributions通过 Pull Request 提交最终以 LICENSE.txt 声明的 Apache 2.0 协议发布。提交 Bug 报告前的两个必要检查CONTRIBUTING.md 要求提交者先做两件事检索已有 Issue确认问题未被报告过若已存在用 表情帮助维护者优先排期。升级到最新版本再验证。该 SDK 保持接近每日发布的节奏Bug 很可能已在最新版修复同时 SDK 在补丁版本之间维持较强的向后兼容承诺升级不会破坏现有应用。Bug 报告必须包含的要素一份合格报告应满足以下要求简短且有信息量的标题——仅凭标题其他社区成员就能大致明白问题详尽而精炼的问题描述至少包括SDK 的预期行为与实际表现应用环境细节最低限度必须包含SDK 版本和JRE 版本如适用附上异常堆栈如能构造提供一个可复现问题的最小可运行示例MWE, Minimal Working Example使用 Markdown 排版代码片段与异常堆栈必须放在代码块中。功能请求先讨论后编码功能请求提交前同样要先检索去重如果找到已存在的需求直接 1 即可。文档特别强调一条容易踩坑的规则如果你打算自己实现该功能务必先提交 Feature Request 再动代码。这样 SDK 团队才能与你讨论设计方案是否合理、是否适合纳入 SDK——源码兼容性与二进制兼容性也是决策的重要因素。功能请求的内容要求包括简短描述性标题、带理由的功能详细说明最好附示例代码展示期望的 API 形态、Markdown 排版以及勾选 issue 模板中“I may be able to implement this feature request”选项。代码贡献规则与 Pull Request 就绪清单提交代码前的约定CONTRIBUTING.md 对代码贡献者提出四条硬性约定许可协议SDK 以 Apache 2.0 协议发布你提交的任何代码都将采用该协议贡献大型功能时可能被要求签署 CLA贡献者许可协议。先查 Issues 再动手除极小改动外先在 Issues 页面确认工作未被他人认领。修 Bug 时如已有报告先评论表示你准备修复若确信尚未被报告按 Bug 报告流程新建。新功能则先走 Feature Request 流程征求反馈。必须附带测试所有代码贡献都要包含新增或修改的测试以验证 Bug 已修复或功能按预期工作。构建环境仓库文档 docs/GettingStarted.md 说明了基础环境——SDK 基于Java 8构建使用Maven作为构建与依赖管理系统且绝大多数服务客户端代码由 codegen 代码生成器自动生成。如果你修改的是代码生成器本身必须执行mvn install而非更早的compile/test阶段确保后续构建使用的是包含你改动的 codegen JAR。使用 IntelliJ IDEA 开发时文档建议加载项目内置的版权头、代码风格与检查配置并可为 Checkstyle 插件配置仓库提供的 checkstyle 规则文件以便在 IDE 中实时看到违规项。Pull Request 就绪清单原文档完整继承提交 PR 前CONTRIBUTING.md 给出如下检查清单包含覆盖新行为的测试代码已加文档尤其是公共的、面向用户的 API本地./mvnw packageLinux或./mvnw.cmd packageWindows执行成功Git 提交信息详实包含变更背景若变更关联既有 Bug Report 或 Feature Request需在 PR 中引用对应 issue 编号通过scripts/new-change脚本向 CHANGELOG.md 添加变更条目并把脚本生成的、位于.changes/next-release目录下的新文件一并提交特殊要求Reactive Streams 变更如果变更涉及 Reactive Streams 接口的实现必须同时包含使用 Reactive Streams TCKTechnology Compatibility Kit的验证测试以确保实现符合规范。这是仓库中唯一被单独点名的“额外 PR 要求”。合并流程所有 PR 必须至少获得一名 SDK 团队成员的批准才能合并。文档提醒维护者审查带宽有限大型或复杂的 PR 数天无人审查并不罕见若一周后仍无任何反馈可以主动 成员请求 review。本地运行 CI 检查命令逐项解析CI 会在每个 PR 上运行单元测试、集成测试、Checkstyle 和 SpotBugs。虽然开 PR 前不必全部跑完但本地先行验证能尽早发现问题、加快审查周期。单元测试全量构建与按模块快速迭代全量构建并跑单元测试mvn clean install仓库是多模块 Maven 工程根 pom.xml 聚合了core、http-clients、services、services-custom、test等数百个模块全量构建耗时较长。更快的方式是只构建你正在改的模块及其依赖例如mvn clean install -pl :dynamodb-enhanced -am这里-pl按artifactId选择模块dynamodb-enhanced即 services-custom/pom.xml 中声明的 DynamoDB 增强客户端模块-amalso make会自动把它的依赖模块一并构建。-pl参数也支持逗号分隔的多个模块名可以按同样方式指定任意模块。另外docs/GettingStarted.md 说明 Checkstyle 和 FindBugs即 SpotBugs扫描默认随构建运行且明显拖慢迭代速度快速迭代时可临时关闭mvn install -Dfindbugs.skiptrue -Dcheckstyle.skiptrue集成测试凭据配置与执行命令集成测试会向真实 AWS API 发起调用会产生账号费用文档对此有明确警示。凭据要求是~/.aws/credentials中存在名为aws-test-account的 profile[aws-test-account] aws_access_key_id your-access-key aws_secret_access_key your-secret-key“找不到该 profile 时回退到默认凭据链”这一点可以在测试基类源码中得到印证。test/service-test-utils/src/main/java/software/amazon/awssdk/testutils/service/AwsIntegrationTestBase.java 中所有集成测试基类共享如下凭据解析逻辑private static final String TEST_CREDENTIALS_PROFILE_NAME aws-test-account; public static final AwsCredentialsProviderChain CREDENTIALS_PROVIDER_CHAIN AwsCredentialsProviderChain.of(ProfileCredentialsProvider.builder() .profileName(TEST_CREDENTIALS_PROFILE_NAME) .build(), DefaultCredentialsProvider.create());即先尝试aws-test-accountprofile 的ProfileCredentialsProvider失败则链式回退到DefaultCredentialsProvider.create()SDK 标准默认凭据链。这与 CONTRIBUTING.md 的描述完全一致。执行集成测试的命令文档原文完整保留# 跑全部集成测试 mvn clean install -Dskip.unit.tests -P integration-tests -Dfindbugs.skip -Dcheckstyle.skip # 只跑指定模块 mvn clean install -pl :dynamodb-enhanced -am -Dskip.unit.tests -P integration-tests -Dfindbugs.skip -Dcheckstyle.skip参数含义-Dskip.unit.tests跳过单元测试、-P integration-tests激活集成测试 profile、-Dfindbugs.skip与-Dcheckstyle.skip关闭静态检查以聚焦测试本身。值得注意的一点差异docs/GettingStarted.md 提到更老的凭据放置方式是$HOME/.aws/awsTestAccount.propertieskey 为accessKey/secretKey而当前 CONTRIBUTING.md 与测试基类源码使用的标准方式是~/.aws/credentials中的aws-test-accountprofile。从源码结构看当前仓库实际生效的机制以后者为准新贡献者应按后者配置。更精细的策略按改动范围选择集成测试模块仓库还提供了一个比手动指定-pl更聪明的本地脚本 scripts/run-integ-test它用git diff HEAD^ --name-only取上一笔提交改动的文件按顶层目录推导需要跑集成测试的模块改动落在core/或codegen/→ 运行最小核心服务集s3、dynamodb、sqs分别覆盖 xml、json、query 三种协议改动落在http-clients/→ 按客户端选择对应模块如apache-client对应[s3, apache-client]netty-nio-client对应[kinesis, s3, netty-nio-client]kinesis 用于覆盖 HTTP/2 场景改动落在services/→ 只跑该服务自身。随后先mvn clean install -pl modules -P quick --am构建依赖再mvn verify -pl modules -P integration-tests -Dfailsafe.rerunFailingTestsCount1执行测试并允许失败用例重跑一次。本地提交前运行该脚本可以显著减少不必要的集成测试耗时。CHANGELOG 条目scripts/new-change脚本的机制PR 就绪清单中要求“通过运行scripts/new-change脚本并向.changes/next-release提交新文件”来更新 CHANGELOG.md。阅读 scripts/new-change 源码可知其完整机制脚本基于 Python 3支持交互式编辑通过VISUAL/EDITOR环境变量打开编辑器默认vim或命令行参数直填-t/--type、-c/--category、-u/--contributor、-d/--description两种方式模板包含四个字段type取值限定为feature、bugfix、deprecation、removal、documentation之一脚本会校验非法值category该变更对应的服务市场名如Amazon DynamoDB核心运行时变更则填AWS SDK for Java v2contributor你的 GitHub 用户名不含脚本会自动剥离前缀用于在 CHANGELOG 中署名留空则不署名description变更描述支持 Markdown且描述中出现的#1234形式 issue 编号会被自动替换为指向仓库 issue 的 Markdown 链接文件写入后以{type}-{category纯字母数字摘要}-{内容SHA1前7位}.json的命名规则保存到.changes/next-release/目录并用git add暂存该文件——这正是文档所说“把脚本生成的新文件与你的一起提交”的由来。保存空文件即可取消本次条目创建若必填字段缺失脚本会报错并以非零状态退出。AI 辅助工具的使用规则仓库明确接受并鼓励使用 AI 工具辅助开发但提出了三条纪律所有由 AI 生成的 Issue 或 PR提交前必须经人工审核且内容中须包含类似 “generated by AI tools, and reviewed by person” 的声明提交必须是实质性的改进。对任何修复哪怕很小团队都表示感谢但制造扰人 PR、人为刷提交量的行为不可接受团队有权对违反上述规则或 CODE_OF_CONDUCT.md 中其他规则的行为关闭 Issue/PR甚至限制其与该仓库的交互能力。延伸阅读docs 目录与设计规范CONTRIBUTING.md 指向 docs/README.md 作为补充资源。该目录下沉淀了贡献者需要的深层资料docs/design/核心架构core/、HTTP 客户端http-clients/与服务端services/的设计文档含设计决策与内部架构图示docs/guidelines/编码规范集包括 命名约定、Optional 使用规范、异步编程指南、Javadoc 规范、日志规范、测试规范、Reactive Streams 指南 与 代码生成规范 等。这些文档是判断你的 PR 能否通过审查的隐性标准建议在写代码前先通读与所改模块相关的条目。附一次规范贡献的最小路径总结把 CONTRIBUTING.md 的完整流程压缩成可执行清单确认问题/需求未被报告检索 Issues需要则先提 Bug Report 或 Feature Request在本地分支上实现变更并编写覆盖新行为的测试本地验证mvn clean install -pl :your-module -am必要时-Dfindbugs.skip -Dcheckstyle.skip加速迭代涉及集成行为时按上文配置aws-test-accountprofile 后运行-P integration-tests运行scripts/new-change生成.changes/next-release/*.json条目提交信息写清背景PR 中引用关联 issue 编号AI 辅助生成的内容按规则附加人工审核声明等待 SDK 团队审查超过一周无反馈可主动请求 review。【免费下载链接】aws-sdk-java-v2The official AWS SDK for Java - Version 2项目地址: https://gitcode.com/GitHub_Trending/aw/aws-sdk-java-v2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
