Improve the deprecation messages around include_type_name.

[jtibshirani]

This PR standardizes the message across the different indices APIs and makes
sure to mention that mappings should no longer be nested under the type name.

Thanks @markharwood for this feedback in #37944 (comment).

[elasticmachine]

Pinging @elastic/es-search

[markharwood]

"should not nested"

Worrying, this decline in the be population.

[mayya-sharipova]

"the mapping definition should not nested under the type name"

Thanks Julie, I am ok with this message as well, but may be more explicit instruction what needs to be done could be more clear, e.g using Mark's comment "To be compatible with 7.0, the type must be removed from the usual mapping -> type -> properties hierarchy, and the parameter ..."

[jtibshirani]

Worrying, this decline in the be population.

Indeed!

[markharwood]

Another missing "be".

[markharwood]

Do you think it would be overkill to make a constant for parts of this message?

It may come in handy if we decide to change the message with with another idea I had - at some pointing adding a url e.g. "see http://elastic.co/migrating_types.html for more". We could have JSON examples of the old and new formats there. I found such a warning message pretty useful the other day. I was running an npm install which warned of potential vulnerabilities in code being installed and it included a URL to a page giving useful details behind the particular vulnerability. Way more info than you can pack into a warning message.

[mayya-sharipova]

Thanks Julie!

[mayya-sharipova]

"the mapping definition should not nested under the type name"

Thanks Julie, I am ok with this message as well, but may be more explicit instruction what needs to be done could be more clear, e.g using Mark's comment "To be compatible with 7.0, the type must be removed from the usual mapping -> type -> properties hierarchy, and the parameter ..."

[mayya-sharipova]

index template requests

Shouldn't it be "get mapping requests"?

[jtibshirani]

👍

[jtibshirani]

Thank you both for the review and for catching my typos, I must have been staring at these deprecation messages for too long!

Do you think it would be overkill to make a constant for parts of this message?

I didn't see a huge benefit to doing so in this PR, since there are a small number of uses of each message and it would cause us to diverge from 7.0 more. However, we've discussed doing a better job unifying the messages in general (and maybe pulling them out of the Rest*Action classes), so maybe this would be something to look into on master (with a backport)?

It may come in handy if we decide to change the message with with another idea I had - at some pointing adding a url e.g. "see http://elastic.co/migrating_types.html for more". We could have JSON examples of the old and new formats there.

Just a note that in #38003 we've added high-level examples of the changes users will have to make in 7.0 to the existing 'removal of types' page. Pulling these examples out into their own page like 'migrating types' and expanding on them could be really nice! If we ended up updating the deprecation warnings to refer to the page, I think we would want to do that in a separate PR against master, since it is not just these messages here that would need updating.

the type must be removed from the usual mapping -> type -> properties hierarchy

This is a helpful description, but I didn't think it was quite precise because you don't always have properties in mappings definitions (and in fact the definition could be empty). If it's okay with you, I'll plan to keep this message with the understanding that the user can look at the API documentation if they're confused, or refer to the 'removal of types' page.