Skip to content

Document @Conditional gating of nested @Configuration classes#36831

Open
Dennis-Mircea wants to merge 1 commit into
spring-projects:mainfrom
Dennis-Mircea:docs-nested-conditional-inheritance
Open

Document @Conditional gating of nested @Configuration classes#36831
Dennis-Mircea wants to merge 1 commit into
spring-projects:mainfrom
Dennis-Mircea:docs-nested-conditional-inheritance

Conversation

@Dennis-Mircea
Copy link
Copy Markdown

Summary

The "With nested @Configuration classes" section of the @Configuration Javadoc previously mentioned @Profile working with nested classes but was silent on how @Conditional interacts with them. The corresponding reference-doc section ("Conditionally Include @Configuration Classes or @Bean Methods" in composing-configuration-classes.adoc) was similarly silent.

In practice, whether an enclosing class's @Conditional gates a nested @Configuration depends on how the nested class is discovered. Nested classes reached through parser recursion from their enclosing class or via @Import inherit the enclosing's conditions through the existing importedBy mechanism (ConfigurationClassBeanDefinitionReader.TrackedConditionEvaluator.shouldSkip). Nested classes discovered independently (via @ComponentScan or by directly registering them) are processed using only their own conditions. The rule is real, long-standing, and currently undocumented.

This PR adds a paragraph to the @Configuration Javadoc and a [NOTE] admonition to the reference-doc page documenting that rule and recommending the redeclare-or-meta-annotation workaround when the same gating is intended on independent discovery paths.

See also #36820 for a separate proposal to close the discovery-path asymmetry at the framework level. This PR is independent of that proposal; it documents current behavior.

Test plan

  • ./gradlew :spring-context:check (includes javadoc with -Werror, checkstyle, runtime-hints, tests), all green
  • ./gradlew :framework-docs:antora, all green
  • Locally rendered Antora site verified, admonition renders correctly under "Conditionally Include @Configuration Classes or @Bean Methods"
  • Locally rendered Javadoc for @Configuration verified, new paragraph reads cleanly and {@link} references resolve

Signed-off-by: Dennis-Mircea Ciupitu <dennis.mircea.ciupitu@gmail.com>
@spring-projects-issues spring-projects-issues added the status: waiting-for-triage An issue we've not yet triaged or decided on label May 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: waiting-for-triage An issue we've not yet triaged or decided on

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants