Fail yaml and doc tests when they receive unexpected Warning header #19793
+347
−57
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
nik9000
added
>enhancement
>docs
| @@ -6,7 +6,7 @@ set of documents. In order to do so, MLT selects a set of representative terms | |||
| of these input documents, forms a query using these terms, executes the query | |||
| and returns the results. The user controls the input documents, how the terms | |||
| should be selected and how the query is formed. `more_like_this` can be | |||
| shortened to `mlt` deprecated[5.0.0,use `more_like_this` instead). | |||
| shortened to `mlt` deprecated[5.0.0,use `more_like_this` instead]. | |||
There was a problem hiding this comment.
I'm not 100% sure how I wandered to this point in the docs and fixed this, but it seems like a good thing anyway.
|
Ping @elastic/es-clients because this introduces |
|
We'll really only get the full benefit from this if we finish #18160, converting all of our snippets to |
|
very nice! shall we document the new warning feature here? |
Yeah! Let me push some docs! |
|
This is awesome @nik9000. A great use of it! |
I pushed the docs. 😤 |
|
thanks @nik9000 LGTM |
Adds `warnings` syntax to the yaml test that allows you to expect
a `Warning` header that looks like:
```
- do:
warnings:
- '[index] is deprecated'
- quotes are not required because yaml
- but this argument is always a list, never a single string
- no matter how many warnings you expect
get:
index: test
type: test
id: 1
```
These are accessible from the docs with:
```
// TEST[warning:some warning]
```
This should help to force you to update the docs if you deprecate
something. You *must* add the warnings marker to the docs or the build
will fail. While you are there you *should* update the docs to add
deprecation warnings visible in the rendered results.
nik9000
force-pushed
the
warn_on_deprecated
branch
from
8f6d4a2 to
1e58740
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Now that using a deprecated feature in Elasticsearch returns a
Warningheader (#17804), we can assert that our yaml tests and the snippets in our docs don't receive unexpected warning headers. This is fairly useful in the yaml tests but it is very useful in the documentation because it immediately shows you any snippets in the documentation[0] that use the deprecated syntax. This should make it much harder to deprecate something and leave examples of it littered throughout the docs.This PR removes most of the deprecated syntax from the snippets, replacing it with the non-deprecated syntax. In the cases where we are explicitly documenting a deprecated feature I simply add the warning to the docs so they pass. This found a few places where we were had examples for deprecated features but haven't marked them as deprecated, so I added that.