AGENTS.md

This is the AWS SDK for Java 2.x: service clients generated at build time from AWS service models, plus the hand-written core runtime, HTTP clients, and high-level libraries they run on. The files under docs/guidelines/ add depth, and each section says when to read one.

Build and test commands

The Maven reactor has about 500 modules. Run Maven through ./mvnw from the repository root, scoped with -pl to the modules you changed.

• <changed modules> is a comma-separated list of every module you edited, including upstream ones such as utils or core/sdk-core, because the dependency build skips their checks and tests. After a utils or core/* change, also add the modules that call the changed code.
• The final check runs all of the module's unit tests, not just the class you iterated on, so it catches failures in other test classes that your change affects. It also runs Checkstyle, dependency analysis, japicmp, and SpotBugs where the build enables it.
• On JDK 17 the build skips SpotBugs because it is slow there. To check it before opening a pull request, run ./mvnw -pl <module> -Dspotbugs.skip=false process-classes.
• Use -P quick only to build dependencies, never to verify a change: it skips unit tests, Checkstyle, SpotBugs, and japicmp and still reports BUILD SUCCESS. Do not run install or test from the root without -pl.
• Build with install, not compile or test: modules depend on shaded jars that exist only after package.
• If the single-class run or the final check cannot resolve bom-internal, run the dependency build with -pl bom-internal first.
• If the build fails with Attempted to clobber existing file, a target/ directory holds stale generated sources, for example after switching branches. Add clean before install and rerun.
• The final check and the single-class run on services/*, services-custom/*, and test/* build clients that need a region and credentials. Nothing calls AWS, so placeholders work: prefix the command with AWS_REGION=us-west-2 AWS_ACCESS_KEY_ID=akid AWS_SECRET_ACCESS_KEY=skid. Leave the two credential variables off any run that includes core/auth, whose tests expect them unset; run core/auth in its own final check.
• The commands in README.md and CONTRIBUTING.md build the whole tree, skip checks with -P quick, or use mvn instead of ./mvnw. Use the ones in this section.

Generated code

Files under any target/generated-sources/ directory are regenerated by every build, so an edit there is lost. Never edit them. Change what generates them:

• Service clients and models: the generator in codegen/ turns each services/<service> module's src/main/resources/codegen-resources/ files into its target/generated-sources/sdk. Do not edit any file in those service codegen-resources/ directories except customization.config: release automation replaces the others with each service's published model.
• customization.config is maintained by hand and is the place to adjust one service's generated code. The options it can set are the fields of codegen/src/main/java/software/amazon/awssdk/codegen/model/config/customization/CustomizationConfig.java.
• Hand-written code that a generated client calls, such as the execution interceptors listed under interceptors in customization.config, lives in the module's src/main/java, usually in an internal package. Edit it directly.
• core/regions and core/aws-core: the generators in codegen-lite/. Their inputs core/regions/src/main/resources/software/amazon/awssdk/regions/internal/region/endpoints.json and core/aws-core/src/main/resources/software/amazon/awssdk/awscore/internal/defaults/sdk-default-configuration.json are replaced by release automation; do not edit them.
• core/sdk-core: the VersionInfo.java.vm template in that module.

Code generator

A change in codegen/ changes every service client. To fix code that every service generates, change the generator rather than one service. Before changing codegen/, read docs/guidelines/code-generation-guidelines.md.

• JavaPoet specs are under codegen/src/main/java/software/amazon/awssdk/codegen/poet/. A new generated class gets @Generated from PoetUtils.generatedAnnotation().
• Test the behavior of generated clients with a functional test in test/codegen-generated-classes-test, which generates clients from the test models in its src/main/resources/codegen-resources/. Those models are maintained by hand, so edit or add them as the test needs. Marshalling tests for each protocol live in test/protocol-tests.
• To verify a change, run the dependency build for one affected services/<service> module and test/codegen-generated-classes-test, which installs your codegen change for the code generator plugin, then the final check on codegen, that service module, and test/codegen-generated-classes-test with the placeholder region and credentials above. When generated output changes on purpose, update the expected-output fixtures that the codegen tests compare against.

Code conventions

• Put new types in an internal package and annotate them @SdkInternalApi, and make a fix in internal code when it can live there. Add @SdkPublicApi or @SdkProtectedApi types only when the change cannot be made without them.
• Use the SDK's utilities instead of a new dependency or a hand-written version: JsonNodeParser (core/json-utils) for JSON, Lazy and CachedSupplier (utils) for lazy and TTL-cached values, Validate for argument checks, and ToString for toString().
• Argument and configuration checks use Validate, which throws IllegalArgumentException or NullPointerException. Failures at request time throw SdkClientException or another SdkException subtype. Do not throw checked exceptions from public APIs, and do not catch an exception only to rethrow the same type. Messages say what went wrong and how to fix it. Before adding or changing exception handling or a public value class, read docs/guidelines/aws-sdk-java-v2-general.md.
• Log through software.amazon.awssdk.utils.Logger (private static final Logger logger = Logger.loggerFor(MyClass.class);), not SLF4J directly, unless Checkstyle bans it in that module; then use the logger that neighboring code uses. Do not log at WARN or ERROR an error that is also thrown to the caller. Before adding or changing a log statement, read docs/guidelines/logging-guidelines.md.
• Do not use Optional for parameters, fields, values that are never null, or getters on generated model classes. Return it only when a caller could not otherwise tell that the result may be absent.
• Public value classes implement equals, hashCode, and toString over all fields and have an EqualsVerifier test.
• CompletableFuture: never drop a future that can fail, and handle its failure with exceptionally, handle, or whenComplete. Do not call join() or get() inside a future chain. Pass an executor to every *Async method. Propagate cancellation with CompletableFutureUtils.forwardExceptionTo, and where a sync path must wait, use CompletableFutureUtils.joinLikeSync. Before changing code that uses CompletableFuture, read docs/guidelines/async-programming-guidelines.md.
• Reactive Streams: build on SimplePublisher, ByteBufferStoringSubscriber, and SdkPublisher instead of writing a Publisher or Subscriber from scratch. A change to any Publisher or Subscriber implementation needs a Reactive Streams TCK test named <ClassName>TckTest in the same package, like utils/src/test/java/software/amazon/awssdk/utils/async/SimplePublisherTckTest.java. Before changing a Publisher or Subscriber, read docs/guidelines/reactive-streams-guidelines.md.
• Use code comments sparingly. Add one only for a reason the code cannot show, such as a hidden constraint, a subtle invariant, or a workaround for a specific bug, and never to restate what the code does. Javadoc on public API is separate and follows the next rule.
• Every public API has Javadoc: a one-sentence summary first, in third person ("Returns the..."), and <p> with no closing tag at the start of each later paragraph. Before adding or changing public or protected API, read docs/guidelines/javadoc-guidelines.md.

API compatibility

• Never remove, rename, or narrow a public or protected member, or change its signature. Add the new form, keep the old one, and mark it @Deprecated with a @deprecated Javadoc tag that links the replacement. On install, japicmp fails the build for binary-incompatible or source-incompatible changes in the modules it checks; *.internal.* packages are exempt.
• Older generated clients call @SdkProtectedApi members, so keep them as backward compatible as public API even though customers do not call them directly.

Testing instructions

• Every behavior change comes with a new or updated unit test in the changed module's src/test/java. Before adding or changing a test, read docs/guidelines/testing-guidelines.md.
• Use JUnit 5 with AssertJ and Mockito, and WireMock to stub HTTP responses, as services-custom/s3-transfer-manager/src/test/java/software/amazon/awssdk/transfer/s3/internal/DownloadDirectoryRefusedKeyWireMockTest.java does.
• Name test methods methodToTest_when_expectedBehavior, for example close_withCustomExecutor_shouldNotCloseCustomExecutor, and name a class that tests one class <ClassName>Test.
• On an error path, assert the exception type and part of its message.
• Keep test-only constructors and methods package-private, and annotate them @SdkTestInternalApi (core/annotations).
• Prefer unit and functional tests that mock dependencies with Mockito or stub HTTP responses with WireMock over integration tests (src/it/java, *IntegrationTest), which call real AWS services.
• Check that each test of new behavior fails without your change.

Security considerations

• Never log, or put in toString() or an exception message, credentials, HTTP header values, or members modeled as sensitive.
• Tests use placeholder credentials such as akid and skid. Never put real credentials in tests or test resources.

Pull request instructions

• Before opening a pull request, run the final check on every module you changed.
• A pull request sourced by AI tools must be reviewed by a person before it is opened.
• Do not write the pull request description. The person opening the pull request writes it from .github/PULL_REQUEST_TEMPLATE.md.
• Work on a branch named <alias>/<short-kebab-slug>, where the slug describes the change rather than a ticket, and never commit the change to master. External contributors push the branch to their own fork.
• Write commit messages as Conventional Commits, <type>: <description> or <type>(<scope>): <description>, with a type such as fix, feat, docs, refactor, test, or chore, and a subject of 50 characters or fewer in the imperative mood with no trailing period. Add a body only when the reason for the change is not obvious from the diff: wrap it at 72 characters and explain the context behind the change. In the rare case that maintainers approve a breaking change, mark it with a BREAKING CHANGE: footer. Pull requests are squash-merged with the title as the commit subject, so the title follows the same format.
• Add a changelog entry, as described next.

Changelog entry

Every change customers can observe needs an entry in .changes/next-release/, including a change made only in customization.config. CI enforces this for non-test Java files. Create the entry with scripts/new-change, which writes the JSON file and stages it with git add. Choose the values first:

• -c (category): the changed component's own category, as existing entries in .changes/ name it. Use the library name for a library, such as S3 Transfer Manager, Amazon DynamoDB Enhanced Client, Netty NIO HTTP Client, Apache HTTP Client, or AWS CRT HTTP Client; the service name for a service module, such as Amazon S3 or Amazon DynamoDB; and AWS SDK for Java v2 only for core, utils, and codegen changes.
• -t (type): one of bugfix, feature, perf-improvement, deprecation, removal, documentation.
• -d (description): the user-visible behavior change, with no ticket numbers or internal references.

EDITOR=true python3 scripts/new-change -t <type> -c "<category>" -d "<description>"

SDK maintainers leave -u out. An external contributor may pass their own GitHub username with -u; never guess one. Without -u the script opens an editor, and EDITOR=true makes that a no-op. The script reads VISUAL before EDITOR, so if VISUAL is set, unset it or set it to true as well.

Guideline files