Skip to content

Document @Conditional gating of nested @Configuration classes#36831

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

Document @Conditional gating of nested @Configuration classes#36831
Dennis-Mircea wants to merge 2 commits 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
@sbrannen sbrannen added type: documentation A documentation task in: core Issues in core modules (aop, beans, core, context, expression) labels May 24, 2026
Copy link
Copy Markdown
Member

@sbrannen sbrannen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR. I've requested a few changes.

Signed-off-by: Dennis-Mircea Ciupitu <dennis.mircea.ciupitu@gmail.com>
@Dennis-Mircea Dennis-Mircea requested a review from sbrannen May 24, 2026 18:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

in: core Issues in core modules (aop, beans, core, context, expression) status: waiting-for-triage An issue we've not yet triaged or decided on type: documentation A documentation task

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants