Merge branch '2.1.x' into 2.2.x

Closes gh-19152

Author: wilkinsona

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -103,8 +103,9 @@ It is therefore possible to get the location of the file from the environment.
 The preceding example adds the `custom-resource` property source at the end of the list so that a key defined in any of the usual other locations takes precedence.
 A custom implementation may define another order.
 
-CAUTION: While using `@PropertySource` on your `@SpringBootApplication` may seem to be a convenient and easy way to load a custom resource in the `Environment`, we do not recommend it, because Spring Boot prepares the `Environment` before the `ApplicationContext` is refreshed.
-Any key defined with `@PropertySource` is loaded too late to have any effect on auto-configuration.
+CAUTION: While using `@PropertySource` on your `@SpringBootApplication` may seem to be a convenient way to load a custom resource in the `Environment`, we do not recommend it.
+Such property sources are not added to the `Environment` until the application context is being refreshed.
+This is too late to configure certain properties such as `logging.*` and `spring.main.*` which are read before refresh begins.
 
 
 

spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -369,7 +369,9 @@ Properties are considered in the following order:
 . <<boot-features-external-config-profile-specific-properties,Profile-specific application properties>> packaged inside your jar (`application-\{profile}.properties` and YAML variants).
 . Application properties outside of your packaged jar (`application.properties` and YAML variants).
 . Application properties packaged inside your jar (`application.properties` and YAML variants).
-. {spring-framework-api}/context/annotation/PropertySource.html[`@PropertySource`] annotations on your `@Configuration` classes (these are added late to the `Environment` and will not have any effect on anything that reads properties from the `Environment` before the `ApplicationContext` is refreshed, such as logging configuration and auto-configuration).
+. {spring-framework-api}/context/annotation/PropertySource.html[`@PropertySource`] annotations on your `@Configuration` classes.
+  Please note that such property sources are not added to the `Environment` until the application context is being refreshed.
+  This is too late to configure certain properties such as `logging.*` and `spring.main.*` which are read before refresh begins.
 . Default properties (specified by setting `SpringApplication.setDefaultProperties`).
 
 To provide a concrete example, suppose you develop a `@Component` that uses a `name` property, as shown in the following example: