Feature request / Enhancement

Background

When configuring maximum retry attempts in Spring Framework (RetryPolicy, RetryTemplate), the maxAttempts parameter is currently documented and implemented as the "total number of executions (including the first attempt)". This is supposed to match the definition in spring-retry, but the way it is explained in spring-retry is more direct and user-friendly. Furthermore, in recent @spring-projects/spring-framework tests, its behavior appears inconsistent with the documentation and with spring-retry itself.

How it works in spring-retry

MaxAttemptsRetryPolicy:

"Includes the initial attempt before the retries begin so, generally, will be >= 1. For example setting this property to 3 means 3 attempts total (initial + 2 retries)."

Javadoc and parameter descriptions for maxAttempts in spring-retry make it clear: setting to 3 means 3 total attempts (1 initial + 2 retries). This is incredibly clear for users ('don't make me think').

How it's defined and tested in spring-framework

Documentation Reference:
The docs in Spring Framework 7.0 clearly state that the initial attempt plus maxAttempts - 1 retries is the intended behavior:

framework-docs/modules/ROOT/pages/core/resilience.adoc

• spring-core/src/main/java/org/springframework/core/retry/RetryPolicy.java
• spring-core/src/test/java/org/springframework/core/retry/RetryTemplateTests.java

Recent tests (see link above) indicate the initial call is not counted towards maxAttempts—meaning that if you set maxAttempts = 3, you may get the initial attempt + 3 more as retries (total of 4). This is not consistent with the spring-retry definition and can lead to off-by-one confusion for users.

Proposal

• Goal: Unify semantics so that the initial attempt IS INCLUDED in maxAttempts for both modules—so a value of N means N total tries (the initial attempt + N-1 retries).
• Update docs, javadocs, examples, and definition so that it matches the more user-friendly approach of spring-retry.
• Review and (if needed) update tests and implementation to avoid confusion and ensure the initial call is counted as one of the maxAttempts.
• Add code comments and examples highlighting this for future contributors.

References

• Spring Retry: MaxAttemptsRetryPolicy, SimpleRetryPolicy
• Spring Framework: RetryPolicy.java, RetryTemplateTests.java

If possible, please harmonize the documentation, implementation, and user experience between Spring Framework retry and spring-retry. The initial attempt should count towards maxAttempts (as in spring-retry), making it easier for users and developers to reason about behavior.