[HTTP/OAS] Support a discontinued field to declare when a deprecation is to be removed #192292
Labels
Feature:http
Feature:OAS
Work or issues related to Core-provided mechanisms for generating OAS
Team:Core
Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc
Comments
TinaHeiligers
added
Feature:http
Feature:OAS
|
Pinging @elastic/kibana-core (Team:Core) |
|
cc @lcawl Can. you help with contacting the Bump.sh folks please? |
|
Do you have a preference for "x-remove-by: x.y.z" or "x-discontinued: x.y.z"? It ultimately won't matter since we can amend the way it's displayed in the output tool. I just like the symmetry of "deprecated" and "x-discontinued". |
"discontinued" is generally accepted by the dev community, as is "end of life" and "removed". These terms imply the past tense to me. It feels a bit odd using any of them for a future date or version but I don't have a better term either. I'll go with your suggestion and see what reviewers think. |
TinaHeiligers
changed the title
TinaHeiligers
changed the title
|
cc @jloleysens for insights |
kibanamachine
pushed a commit
to kibanamachine/kibana
that referenced
this issue
Sep 13, 2024
## Summary In this PR, we add support for a discontinued field to our router conversion logic at the operation level. `discontinued` indicates the version or date when the deprecation will be removed, as a string. Closes elastic#192292 --------- Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com> Co-authored-by: Jean-Louis Leysens <jloleysens@gmail.com> (cherry picked from commit 303d8f2)
kibanamachine
referenced
this issue
Sep 13, 2024
# Backport This will backport the following commits from `main` to `8.x`: - [Adds 'discontinued' to OAS meta (#192331)](#192331) <!--- Backport version: 9.4.3 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Christiane (Tina) Heiligers","email":"christiane.heiligers@elastic.co"},"sourceCommit":{"committedDate":"2024-09-13T00:06:41Z","message":"Adds 'discontinued' to OAS meta (#192331)\n\n## Summary\r\n\r\nIn this PR, we add support for a discontinued field to our router\r\nconversion logic at the operation level. `discontinued` indicates the\r\nversion or date when the deprecation will be removed, as a string.\r\n\r\nCloses https://github.com/elastic/kibana/issues/192292\r\n\r\n---------\r\n\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: Jean-Louis Leysens <jloleysens@gmail.com>","sha":"303d8f27e4c8cdfd541e7e6b27548cbffaf454fd","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Feature:http","Team:Core","release_note:skip","v9.0.0","Feature:OAS","v8.16.0"],"title":"Adds 'discontinued' to OAS meta","number":192331,"url":"https://github.com/elastic/kibana/pull/192331","mergeCommit":{"message":"Adds 'discontinued' to OAS meta (#192331)\n\n## Summary\r\n\r\nIn this PR, we add support for a discontinued field to our router\r\nconversion logic at the operation level. `discontinued` indicates the\r\nversion or date when the deprecation will be removed, as a string.\r\n\r\nCloses https://github.com/elastic/kibana/issues/192292\r\n\r\n---------\r\n\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: Jean-Louis Leysens <jloleysens@gmail.com>","sha":"303d8f27e4c8cdfd541e7e6b27548cbffaf454fd"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/192331","number":192331,"mergeCommit":{"message":"Adds 'discontinued' to OAS meta (#192331)\n\n## Summary\r\n\r\nIn this PR, we add support for a discontinued field to our router\r\nconversion logic at the operation level. `discontinued` indicates the\r\nversion or date when the deprecation will be removed, as a string.\r\n\r\nCloses https://github.com/elastic/kibana/issues/192292\r\n\r\n---------\r\n\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: Jean-Louis Leysens <jloleysens@gmail.com>","sha":"303d8f27e4c8cdfd541e7e6b27548cbffaf454fd"}},{"branch":"8.x","label":"v8.16.0","branchLabelMappingKey":"^v8.16.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT--> Co-authored-by: Christiane (Tina) Heiligers <christiane.heiligers@elastic.co> Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
The
deprecatedfield, added in #181240, did not include a way to specify the removal period and we need to add one.In an ideal world, we'd have a way to specify up front when a deprecation will be removed when the deprecation is introduced. While
config-schemasupports conditional schema declarations, OAS3 unfortunately does not. OAS3 also doesn't support additional fields in the schema. We have to be creative in our handlingATM, the advice is to introduce an optional field and describe it as
incompletewithout the parent field.The
discontinuedtag is slightly nuanced in that the tag value will be the version or date given. We could:discontinued.Nice to have:
Ensure a value for discontinued can only be provided if deprecated is true, thereby catching any non-public APIs marked for deletion without first having been deprecated.
The text was updated successfully, but these errors were encountered: