GH-3706: Align RetryTopicConfigurationBuilder default with @RetryableTopic

spring-kafka-docs/src/main/antora/modules/ROOT/pages/retrytopic/topic-naming.adoc

@@ -9,8 +9,7 @@ Examples:
 
 "my-other-topic" -> "my-topic-myRetrySuffix-1000", "my-topic-myRetrySuffix-2000", ..., "my-topic-myDltSuffix"
 
-NOTE: The default behavior is to create separate retry topics for each attempt, appended with an index value: retry-0, retry-1, ..., retry-n.
-Therefore, by default the number of retry topics is the configured `maxAttempts` minus 1.
+NOTE: Starting with version 4.0, the default behavior is to reuse a single retry topic for the same delay intervals. To create separate retry topics for each attempt, set `sameIntervalTopicReuseStrategy` to `MULTIPLE_TOPICS`.
 
 You can xref:retrytopic/topic-naming.adoc#retry-topics-and-dlt-suffixes[configure the suffixes], choose whether to append xref:retrytopic/topic-naming.adoc#append-index-or-delay[the attempt index or delay], use a xref:retrytopic/topic-naming.adoc#single-topic-fixed-delay[single retry topic when using fixed backoff], and use a xref:retrytopic/topic-naming.adoc#single-topic-maxinterval-delay[single retry topic for the attempts with the maxInterval] when using exponential backoffs.
 
@@ -99,7 +98,7 @@ public RetryTopicConfiguration myRetryTopic(KafkaTemplate<String, MyPojo> templa
 }
 ----
 
-NOTE: The default behavior is creating separate retry topics for each attempt, appended with their index values: retry-0, retry-1, ...
+NOTE: Starting with version 4.0, the default behavior is to use a single topic for fixed delay retries. To use multiple topics, set `sameIntervalTopicReuseStrategy` to `MULTIPLE_TOPICS`.
 
 
 [[single-topic-maxinterval-delay]]

spring-kafka-docs/src/main/antora/modules/ROOT/pages/whats-new.adoc

@@ -45,6 +45,26 @@ New methods from the Kafka Producer interface have been implemented:
 * `registerMetricForSubscription`
 * `unregisterMetricFromSubscription`
 
+[[x40-retry-topic-builder-default]]
+=== RetryTopicConfigurationBuilder Default Strategy Change
+
+The default value of `sameIntervalTopicReuseStrategy` in `RetryTopicConfigurationBuilder` has been changed from `MULTIPLE_TOPICS` to `SINGLE_TOPIC` to align with the `@RetryableTopic` annotation default behavior.
+
+This means that, by default, a single retry topic will be used for the same delay intervals instead of creating separate topics for each attempt.
+
+To restore the previous behavior, explicitly set the strategy:
+
+[source,java]
+----
+@Bean
+public RetryTopicConfiguration myRetryTopic(KafkaTemplate<String, MyPojo> template) {
+    return RetryTopicConfigurationBuilder
+            .newInstance()
+            .sameIntervalTopicReuseStrategy(SameIntervalTopicReuseStrategy.MULTIPLE_TOPICS)
+            .create(template);
+}
+----
+
 [[x40-removed-deprecated-functionality]]
 === Removed Deprecated Functionality
 

spring-kafka/src/main/java/org/springframework/kafka/retrytopic/RetryTopicConfigurationBuilder.java

@@ -93,7 +93,7 @@ public class RetryTopicConfigurationBuilder {
 
 	private TopicSuffixingStrategy topicSuffixingStrategy = TopicSuffixingStrategy.SUFFIX_WITH_DELAY_VALUE;
 
-	private SameIntervalTopicReuseStrategy sameIntervalTopicReuseStrategy = SameIntervalTopicReuseStrategy.MULTIPLE_TOPICS;
+	private SameIntervalTopicReuseStrategy sameIntervalTopicReuseStrategy = SameIntervalTopicReuseStrategy.SINGLE_TOPIC;
 
 	@Nullable
 	private Boolean autoStartDltHandler;

spring-kafka/src/test/java/org/springframework/kafka/retrytopic/RetryTopicConfigurationBuilderTests.java

@@ -73,7 +73,8 @@ void shouldSetFixedBackOffPolicy() {
 
 		// setup
 		RetryTopicConfigurationBuilder builder = new RetryTopicConfigurationBuilder();
-		builder.fixedBackOff(1000);
+		builder.fixedBackOff(1000)
+				.sameIntervalTopicReuseStrategy(SameIntervalTopicReuseStrategy.MULTIPLE_TOPICS);
 
 		//when
 		RetryTopicConfiguration configuration = builder.create(kafkaOperations);
@@ -91,7 +92,8 @@ void shouldSetNoBackoffPolicy() {
 
 		// setup
 		RetryTopicConfigurationBuilder builder = new RetryTopicConfigurationBuilder();
-		builder.noBackoff();
+		builder.noBackoff()
+				.sameIntervalTopicReuseStrategy(SameIntervalTopicReuseStrategy.MULTIPLE_TOPICS);
 
 		//when
 		RetryTopicConfiguration configuration = builder.create(kafkaOperations);
@@ -201,6 +203,7 @@ void shouldSetDltRoutingRules() {
 
 		//when
 		RetryTopicConfiguration configuration = builder
+			.sameIntervalTopicReuseStrategy(SameIntervalTopicReuseStrategy.MULTIPLE_TOPICS)
 			.dltRoutingRules(Map.of("-deserialization", Set.of(DeserializationException.class)))
 			.create(kafkaOperations);