New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add deprecations page to docs #22849

Closed
rjernst opened this Issue Jan 28, 2017 · 7 comments

Comments

Projects
None yet
3 participants
@rjernst
Member

rjernst commented Jan 28, 2017

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?

@rjernst rjernst added the discuss label Jan 28, 2017

@dadoonet

This comment has been minimized.

Member

dadoonet commented Jan 30, 2017

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

This comment has been minimized.

Member

clintongormley commented Jan 30, 2017

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

This comment has been minimized.

Member

rjernst commented Jan 30, 2017

@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

This comment has been minimized.

Member

clintongormley commented Jan 31, 2017

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

This comment has been minimized.

Member

dadoonet commented Jan 31, 2017

@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

This comment has been minimized.

Member

clintongormley commented Feb 7, 2017

@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 added a commit to rjernst/elasticsearch that referenced this issue Feb 13, 2017

Improve setting deprecation message
This change modifies the deprecation log message emitted when a setting
is found which is deprecated. The new message indicates docs for the
deprecated settings can be found in the breaking changes docs for the
next major version.

closes elastic#22849
@rjernst

This comment has been minimized.

Member

rjernst commented Feb 13, 2017

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.

rjernst added a commit that referenced this issue Feb 15, 2017

Improve setting deprecation message (#23156)
This change modifies the deprecation log message emitted when a setting
is found which is deprecated. The new message indicates docs for the
deprecated settings can be found in the breaking changes docs for the
next major version.

closes #22849

rjernst added a commit that referenced this issue Feb 15, 2017

Improve setting deprecation message (#23156)
This change modifies the deprecation log message emitted when a setting
is found which is deprecated. The new message indicates docs for the
deprecated settings can be found in the breaking changes docs for the
next major version.

closes #22849

rjernst added a commit that referenced this issue Feb 15, 2017

Improve setting deprecation message (#23156)
This change modifies the deprecation log message emitted when a setting
is found which is deprecated. The new message indicates docs for the
deprecated settings can be found in the breaking changes docs for the
next major version.

closes #22849

dadoonet added a commit to dadoonet/elasticsearch that referenced this issue Feb 20, 2017

Deprecate global `repositories.azure` settings
Today we have multiple ways to define settings when a user needs to create a repository:

* in `elasticsearch.yml` file using `repositories.azure` prefix
* when creating the repository itself with `PUT _snaphot/repo`

The plan is to:

* Deprecate `repositories.azure` settings in 5.x (this PR)
* Remove in 6.x (master branch)

Related to elastic#22800

Also adds a `deprecated` section in our docs as per elastic#22849.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment