Better document new @AutoConfiguration annotation

[xak2000]

After reading the documentation and javadocs for 3.0.x, it's still unclear what the difference between the new @AutoConfiguration annotation and old @Configuration annotation.

It's clear that @AutoConfiguration is meta-annotated with @Configuration(proxyBeanMethods = false). But the question is: was the only reason to have this new @AutoConfiguration annotation is to promote "proxyBeanMethods = false by default" rule? And probably also to mark a class for tooling.. Or there are some other reasons and consequences?

I tried to search, but didn't found any discussions about motivation of introducing this annotation, except this #29870, but it's pretty undetailed.

Basically, will a class annotated with @AutoConfiguration annotation be 100% functionally equivalent to the same class, but directly annotated with @Configuration(proxyBeanMethods = false)?

What if a class, that is listed in the META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file, will be annotated with @Configuration annotation (contrary to documentation)? Will it still be found and properly registered in Spring Boot 3.x? Or will it be ignored?

What if a class, that is annotated with @AutoConfiguration annotation will not be listed in the META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file, but instead will happen to be component-scanned? Will it be registered as a bean (because it is meta-annotated with @Configuration) or will it be specifically filtered out to protect from accidental component-scanning of autoconfigurations? It would be very cool, if yes, or even better to not just filter-it-out, but to force the app startup to fail or at least print a warning, as this situation often leads to very subtle bugs.

The migration guide also states that @AutoConfiguration should be used instead of @Configuration for top-level autoconfiguration classes, but it doesn't explain what if someone doesn't follow this rule and still continues to use @Configuration annotation on a top level autoconfiguration class? It's especially important for libraries (boot-starters) that want to be backward-compatible with both 2.x and 3.x.

Probably, it's worth to mention in both migration-guide and official documentation that @Configuration will still work (if that is true) and also to slightly describe the motivation of introducing @AutoConfiguration annotation. And, if some additional filters/logic/etc is applied only to @AutoConfiguration-annotated classes, but not to @Configuration-directly-annotated classes, then certainly to mention it too.

Also, both documentation and migration guide doesn't describe what will happen in 2.7.x if both spring.factories and META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports files are present and contain the same autoconfiguration class. It would be useful to have this setup for a library (a boot-starter) during migration period because this library could be used from:

• already migrated to 3.x microservices (so, only new file will be read);
• migrated to 2.7 microservices (so, both spring.factories and new file will be read - here is the confusion);
• still-on-2.6 microservies (so, only spring.factories will be read).

It would be possible only if 2.7.x somehow ignores one of 2 declarations. It would be useful to have a description of the behavior for this situation in the 2.7 migration guide (and probably 2.7.x docs).