Improve/disambiguate the documentation for spring.profiles.active

[behrangsa]

According to the documentation:

Sometimes, it is useful to have profile-specific properties that add to the active profiles rather than replace them. The spring.profiles.include property can be used to unconditionally add active profiles.

The example in the documentation shows two included profiles that look to have mutually exclusive properties:

spring.profiles.include:
  - proddb
  - prodmq

As evidenced by this question, and this comment, the documentation is a bit ambiguous.

Let's add this extra information to the documentation:

What happens when the active profile has a property definition that is also defined in one of the included profiles?

application-foo.yaml

myCustomProperty: 10

application-bar.yaml

spring:
  profiles:
    include: foo
myCustomProperty: 20

In this case, foo wins and myCustomProperty = 10.

What happens when the included profiles do not have mutually exclusive property definitions?

application-x.yaml

myCustomProperty: 10

application-y.yaml

myCustomProperty: 20

application-z.yaml

spring:
  profiles:
    include: x, y

myCustomProperty: 30

In this, y wins and myCustomProperty = 20.

---

Also, IMHO, when the included profiles (e.g. x and y in the example above) have shared property definitions, a warning log message should be emitted as I think a situation like this is the sign of a potential misconfiguration by the user.

[mbhave]

Profile includes can get quite tricky depending on the order, which can quickly make the documentation confusing. See this comment. We have a number of open issues around active and included profiles. It will probably lead to a bigger refactor of the profiles code and we can tackle this documentation issue as part of that.

[mbhave]

With the rewrite of config file and profile processing in 2.4.x, profiles can no longer be included in profile specific sub sections. All profiles need to be available before any profile-specific files/documents are loaded. This issue can be closed.