Add deprecations page to docs

[rjernst]

When adding the deprecated property to Settings, we get automatic deprecation logging when the setting is used. The message states:

[xxx] setting was deprecated in Elasticsearch and it will be removed in a future release!
See the breaking changes lists in the documentation for details.

However, the breaking changes are not added until the feature is actually removed in the next major release, so a user seeing this message in 5.3 would have nowhere to see information about what should be used in place of the deprecated setting in that release, since 6.0 is not even released yet. Perhaps we could have a deprecation page per minor release?

[dadoonet]

Big +1. I'm working ATM on deprecating repositories.azure.* global settings and I'm missing that part of the documentation.
I will add it as part of my PR.

[clintongormley]

We do have a deprecations section per minor release, in the release notes, eg: https://www.elastic.co/guide/en/elasticsearch/reference/5.2/release-notes-5.2.0.html#deprecation-5.2.0

So perhaps we should just change the wording to "See the release notes in the documentation for details"

[rjernst]

@clintongormley Those are generated based on the deprecation label in github right? IMO that is error prone. If we don't correctly label things, and we release, then there is nowhere to update/correct the missing deprecation documentation. It is also harder for a user to have to click through PRs and read through possibly long comments there to figure out the proposed alternative.

[clintongormley]

What would be nice is to have a single page in the docs for ALL deprecations in a major version, so that the user doesn't need to page through minor versions.

[dadoonet]

@clintongormley Agreed. Wondering if after all the same should apply to breaking changes. Like 5.3 BC contains also 5.2, 5.1 and 5.0 BC in a single page? I mean that it should not be difficult to include that.

I can rework this https://github.com/elastic/elasticsearch/pull/22856/files#diff-d36a4cd7a0ae09762fe9163c590a1cdc and make your suggestion about deprecation happen like what I proposed above: one deprecation file per version but one deprecation centralised html page which includes all of them?

[clintongormley]

@jpountz pointed out that we already have a list in one place: the breaking changes docs for the next major version. So perhaps all we need to do is to change the text to the following:

[xxx] setting was deprecated in Elasticsearch and it will be removed in a future release!
See the breaking changes documentation for the next major version.

[rjernst]

the breaking changes docs for the next major version

I did not realize the unreleased branches had published docs. That seems fine to me. I've opened #23156.