Update guidelins and add kiro steering docs

.gitignore

@@ -30,6 +30,7 @@ target/
 
 # VS Code
 .vscode/*
+bin/
 
 # Other
 .attach_pid*

.kiro/steering/async-programming-guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Asynchronous Programming Guidelines for AWS SDK v2
+inclusion: fileMatch
+fileMatchPattern: "**/*.java"
+---
+
+# Asynchronous Programming Guidelines for AWS SDK v2
+
+For complete guidelines, refer to: #[[file:docs/guidelines/async-programming-guidelines.md]]

.kiro/steering/aws-sdk-java-v2-general.md

@@ -0,0 +1,38 @@
+---
+title: AWS SDK for Java v2 General Guidelines
+inclusion: always
+---
+
+# AWS SDK for Java v2 General Guidelines
+
+## Development Environment
+
+- **Java Version**: Java 8 is the target language version for the AWS SDK for Java v2
+- **Build System**: Maven is used for building and dependency management
+
+## Build Instructions
+
+To check if the SDK compiles properly, follow these steps:
+
+1. **Build with dependencies**: Only need to run once. First run the build command with `--am` (also-make) flag to build all dependencies:
+   ```bash
+   mvn clean install -pl :${module} -P quick --am
+   ```
+   Example for S3 module:
+   ```bash
+   mvn clean install -pl :s3 -P quick --am
+   ```
+
+2. **Build module only**: Then run the build for just the specific module (skips testing and checkstyles):
+   ```bash
+   mvn clean install -pl :${module} -P quick
+   ```
+
+3. **Run tests**: To run tests, use the standard command without the quick profile:
+   ```bash
+   mvn clean install -pl :${module}
+   ```
+
+## Guidelines
+
+All detailed guidelines are in #[[file:docs/guidelines/aws-sdk-java-v2-general.md]]

.kiro/steering/client-configuration-guidelines.md

@@ -0,0 +1,9 @@
+---
+title: "Client Configuration Guidelines for AWS SDK v2"
+inclusion: fileMatch
+fileMatchPattern: "**/*{Config,Configuration,Builder}*.java"
+---
+
+# Client Configuration Guidelines for AWS SDK v2
+
+For complete guidelines, refer to: #[[file:docs/guidelines/ClientConfiguration.md]]

.kiro/steering/code-generation-guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Code Generation Guidelines for AWS SDK v2
+inclusion: fileMatch
+fileMatchPattern: "{codegen/**/*.java,**/poet/**/*.java}"
+---
+
+# Code Generation Guidelines for AWS SDK v2
+
+For complete guidelines, refer to: #[[file:docs/guidelines/code-generation-guidelines.md]]

.kiro/steering/javadoc-guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Javadoc Guidelines for AWS SDK v2
+inclusion: fileMatch
+fileMatchPattern: "{**/src/main/**/*.java}"
+---
+
+# Javadoc Guidelines for AWS SDK v2
+
+For complete guidelines, refer to: #[[file:docs/guidelines/javadoc-guidelines.md]]

.kiro/steering/logging-guidelines.md

@@ -0,0 +1,9 @@
+---
+title: "Logging Guidelines for AWS SDK v2"
+inclusion: fileMatch
+fileMatchPattern: "**/*.java"
+---
+
+# Logging Guidelines for AWS SDK v2
+
+For complete guidelines, refer to: #[[file:docs/guidelines/logging-guidelines.md]]

.kiro/steering/reactive-streams-guidelines.md

@@ -0,0 +1,9 @@
+---
+title: "Reactive Streams Implementation Guidelines"
+inclusion: fileMatch
+fileMatchPattern: '**/*{Publisher,Subscriber}*.java'
+---
+
+# Reactive Streams Implementation Guidelines
+
+See #[[file:docs/guidelines/reactive-streams-guidelines.md]] for detailed implementation guidelines, patterns, and testing requirements.

.kiro/steering/testing-guidelines.md

@@ -0,0 +1,9 @@
+---
+title: Testing Guidelines for AWS SDK v2
+inclusion: fileMatch
+fileMatchPattern: "**/{test,it}/**/*.java"
+---
+
+# Testing Guidelines for AWS SDK v2
+
+For complete guidelines, refer to: #[[file:docs/guidelines/testing-guidelines.md]]

docs/design/ClientConfiguration.md → docs/guidelines/ClientConfiguration.md

@@ -1,10 +1,8 @@
-**Design:** Convention, **Status:** [Accepted](README.md)
-
-## Client Configuration
+# Client Configuration
 
 This page describes the structure and conventions used for client configuration objects. Client configuration objects are any objects used to configure an AWS client builder.
 
-#### Example
+## Example
 
 This section walks through an example configuration class structure and describes each of its components at a high level.
 
@@ -83,7 +81,7 @@ public final class SdkConfiguration // (3)
 11. One "set" method should be created for each option to mutate the value in this builder. This method's name should exactly match the  name of the field it is setting.
 12. Each option should have a bean-style setter to allow configuring the object reflectively using `Inspector`-based frameworks, like spring XML.
 
-#### Configuration Fields
+### Configuration Fields
 
 This section details the semantics of configuration fields.
 

docs/design/FavorStaticFactoryMethods.md → docs/guidelines/FavorStaticFactoryMethods.md

@@ -1,10 +1,10 @@
 **Design:** Convention, **Status:** [Accepted](README.md)
 
-## Favor Static Factory Methods Over Constructors
+# Favor Static Factory Methods Over Constructors
 
 This page describes the structures and conventions used to initialize a class.
 
-### Static Factory Methods vs. Constructors
+## Static Factory Methods vs. Constructors
 Static factory methods are preferable than constructors for the following reasons:
 - Static factory methods provide meaningful names compared with constructors, which improves the readability of the codes by describing the objects being returned.
 ```java
@@ -23,7 +23,7 @@ There are a few disadvantages of static factory methods:
 
 In general, we should favor static factory methods over constructors.
 
-### Example
+## Example
 ```java
 public class DefaultCredentialsProvider implements AwsCredentialsProvider, SdkAutoCloseable {
 
@@ -52,7 +52,7 @@ public class DefaultCredentialsProvider implements AwsCredentialsProvider, SdkAu
 DefaultCredentialsProvider defaultCredentialsProvider1 = DefaultCredentialsProvider.create();
 DefaultCredentialsProvider defaultCredentialsProvider2 = DefaultCredentialsProvider.builder().build;
 ```
-### Naming Conventions
+## Naming Conventions
 The naming conventions for the static factory methods:
 - `create()`, `create(params)` when creating a new instance
 eg: `DynamoDBClient.create()`

docs/design/NamingConventions.md → docs/guidelines/NamingConventions.md

@@ -1,24 +1,22 @@
-**Design:** Convention, **Status:** [Accepted](README.md)
-
-## Naming Conventions
+# Naming Conventions
 
 This page describes the naming conventions, nouns and common terms 
 
-### Class Naming
+## Class Naming
 
-#### General Rules
+### General Rules
 * Prefer singular class names: `SdkSystemSetting`, not `SdkSystemSettings`.
 * Treat acronyms as a single word: `DynamoDbClient`, not `DynamoDBClient`.
 
-#### Classes that instantiate other classes
+### Classes that instantiate other classes
 
 * If the class's primary purpose is to return instances of another class:
   * If the "get" method has no parameters:
     * If the class implements `Supplier`: `{Noun}Supplier` (e.g. `CachedSupplier`)
     * If the class does not implement `Supplier`: `{Noun}Provider` (e.g. `AwsCredentialsProvider`)
   * If the "get" method has parameters: `{Noun}Factory` (e.g. `AwsJsonProtocolFactory`)
 
-#### Service-specific classes
+### Service-specific classes
 
 * If the class makes service calls:
   * If the class can be used to invoke *every* data-plane operation:
@@ -36,6 +34,6 @@ This page describes the naming conventions, nouns and common terms
   * If the class creates presigned URLs: `{ServiceName}Presigner` (e.g. `S3Presigner`)
   * If the class is a collection of various unrelated "helper" methods: `{ServiceName}Utilities` (e.g. `S3Utilities`)
 
-### Tests Naming
+## Tests Naming
 
 Test names SHOULD follow `methodToTest_when_expectedBehavior` (e.g. `close_withCustomExecutor_shouldNotCloseCustomExecutor`, `uploadDirectory_withDelimiter_filesSentCorrectly`)

docs/guidelines/README.md

@@ -0,0 +1,38 @@
+# AWS SDK for Java v2 Development Guidelines
+
+This directory contains comprehensive guidelines for developing with the AWS SDK for Java v2. These guidelines are organized into separate, focused documents to make them more manageable and easier to reference.
+
+## Available Guidelines
+
+### [General Guidelines](aws-sdk-java-v2-general.md)
+Core development principles, code style standards, design patterns, and performance considerations that apply to all AWS SDK Java v2 development. Includes naming conventions, proper use of Optional, object method implementations, and exception handling patterns.
+
+### [Asynchronous Programming Guidelines](async-programming-guidelines.md)
+Best practices for CompletableFuture usage, thread safety considerations, and proper handling of asynchronous operations. Covers cancellation, exception handling, and testing patterns for async code.
+
+### [Reactive Streams Guidelines](reactive-streams-guidelines.md)
+Requirements and patterns for implementing Reactive Streams components. Ensures compliance with the Reactive Streams specification, proper backpressure handling, and mandatory TCK testing for Publisher/Subscriber implementations.
+
+### [Testing Guidelines](testing-guidelines.md)
+Comprehensive testing strategies including unit tests, functional tests, integration tests, and specialized test types like TCK tests for reactive streams. Covers test naming conventions, mocking guidelines, and coverage expectations.
+
+### [Javadoc Guidelines](javadoc-guidelines.md)
+Documentation standards for public APIs including formatting requirements, proper use of Javadoc tags, code snippet guidelines, and examples for different API classifications (public, protected, internal).
+
+### [Logging Guidelines](logging-guidelines.md)
+Logging standards specific to the AWS SDK including proper use of the SDK Logger, log level guidelines, structured logging patterns, and critical rules about avoiding duplicate error reporting when exceptions are thrown.
+
+### [Code Generation Guidelines](code-generation-guidelines.md)
+Patterns and standards for JavaPoet-based code generation including ClassSpec implementations, generator task organization, model processing, and fixture-based testing approaches for generated code validation.
+
+### [Naming Conventions](NamingConventions.md)
+Specific naming patterns for classes, methods, and tests including service client naming, acronym handling, and test naming conventions that clearly describe the method, conditions, and expected behavior.
+
+### [Use of Optional](UseOfOptional.md)
+Guidelines for when and how to use Optional in the SDK, including restrictions on usage in method parameters, member variables, and return types to maintain API clarity and consistency.
+
+### [Static Factory Methods](FavorStaticFactoryMethods.md)
+Patterns for preferring static factory methods over constructors, including naming conventions for factory methods and the benefits of this approach for immutable objects and API design.
+
+### [Client Configuration](ClientConfiguration.md)
+Structural requirements for configuration objects including immutability patterns, builder interfaces, field naming conventions, and proper handling of collection types in configuration APIs.

docs/guidelines/async-programming-guidelines.md

@@ -0,0 +1,91 @@
+# Asynchronous Programming Guidelines for AWS SDK v2
+
+## CompletableFuture Guidelines
+
+### Best Practices for CompletableFuture
+
+- **Read the documentation**: Always read the [CompletionStage Javadocs](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html) to understand the nuances of CompletableFuture
+- **Prefer Non-Blocking Methods for Getting Results**:
+
+```java
+    // Avoid when possible - blocks the current thread
+    String result = future.get();
+
+    // Better - use callbacks
+    future.thenAccept(result -> processResult(result));
+```
+- **Add stacktrace to exceptions**: When using `CompletableFuture#join`, use `CompletableFutureUtils#joinLikeSync` to preserve stacktraces
+- **Don't ignore results**: Never ignore the result of a new `CompletionStage` if the parent stage can fail (unless you're absolutely sure it's safe to)
+- **Don't make thread assumptions**: Never make assumptions about which thread completes the future
+  - CompletableFuture callbacks may execute on:
+    - The thread that completed the future
+    - A thread from the common ForkJoinPool (for async methods without explicit executor)
+    - A thread from a provided executor
+  - Thread behavior can vary based on:
+    - Whether the future is already completed when a callback is added
+    - Whether an async or non-async method is used (e.g., `thenApply` vs `thenApplyAsync`)
+    - The specific JVM implementation and platform
+  - Always ensure thread safety when:
+    - Accessing shared state in callbacks
+    - Modifying UI components (use the appropriate UI thread)
+    - Working with thread-affinity resources like ThreadLocals
+  - Example of incorrect assumption:
+  ```java
+  // INCORRECT: Assuming the callback runs on a specific thread
+  ThreadLocal<Context> contextHolder = new ThreadLocal<>();
+
+  public void processAsync(CompletableFuture<Response> responseFuture) {
+      Context context = new Context();
+      contextHolder.set(context);  // Set in current thread
+
+      responseFuture.thenApply(response -> {
+          // WRONG: Assuming contextHolder still has the context
+          Context ctx = contextHolder.get();  // May be null if running on different thread!
+          return processWithContext(response, ctx);
+      });
+  }
+  ```
+  - Correct approach:
+  ```java
+  // CORRECT: Explicitly passing context to callback
+  public void processAsync(CompletableFuture<Response> responseFuture) {
+      Context context = new Context();
+
+      responseFuture.thenApply(response -> {
+          // Explicitly use the context passed from the outer scope
+          return processWithContext(response, context);
+      });
+  }
+  ```
+- **Always provide custom executors**: Don't use `CompletableFuture#xxAsync` methods (like `runAsync` or `thenComposeAsync`) without providing a custom executor, as the default `ForkJoinPool.commonPool()` behavior can vary by platform
+- **Handle cancellation properly**: CompletableFuture does not support automatic cancellation propagation, so use `CompletableFutureUtils#forwardExceptionTo` to manually propagate cancellation
+- **Avoid chaining multiple API calls**: This can lead to cancellation issues without proper handling
+- **Avoid blocking operations**: Never use `get()` or `join()` inside a CompletableFuture chain as it defeats the purpose of asynchronous execution
+- **Handle exceptions properly**: Always include exception handling with `exceptionally()` or `handle()` methods
+```java
+   CompletableFuture.supplyAsync(() -> fetchData())
+       .exceptionally(ex -> {
+           logger.error("Error processing data", ex);
+           return fallbackData();
+       }, executor);
+```
+- **Use appropriate completion methods**:
+  - whenComplete() - when no transformation is needed, but you need to perform cleanup or side effects with access to both result and exception
+  - handle() - when you need to transform both successful results and exceptions into a new result
+  - exceptionally() - when you only need to handle exceptional cases
+  - thenApply() - when transforming a result
+  - thenAccept() - when consuming a result without returning anything
+  - thenRun() - when executing code regardless of the result
+  - thenCompose() - when the next step returns a CompletableFuture
+- **Test asynchronous code properly**:
+  - Use `CompletableFuture.join()` in tests to wait for completion
+  - Set appropriate timeouts for tests
+
+## Related Guidelines
+
+For reactive streams implementation guidelines, see [Reactive Streams Implementation Guidelines](reactive-streams-guidelines.md).
+
+## References
+
+- [CompletableFuture JavaDoc](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)
+- [CompletionStage JavaDoc](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html)