Track deprecated Core API

[mshustov]

Kibana Core and Core-team-owned plugins provide API that can be leveraged by other Kibana plugins to build functionality on top of it.
Currently, the Core team doesn't have any deprecation policy for such program API. While plugin API is not subject to semver, we still provide some time for plugin authors to migrate from the obsolete API to an alternative version. To avoid the accumulation of technical debt due to deprecated API support over a long time, we should track such deprecated API along with some additional data:

• Kibana version in which API has been deprecated.
• (if possible) Kibana version in which deprecated API is going to be removed
• Documentation for developers with migration examples.
• Link to a meta issue to remove deprecated API from Elastic plugins

As I can see, the new dev docs already collect the list of Kibana plugin deprecated API: https://docs.elastic.dev/kibana-dev-docs/deprecated-api-list-by-plugin. But it doesn't seem to cover the whole Core API surface. We need to add support for the new documentation system to Kibana Core to leverage this functionality.
Also, I don't believe the new docs system tracks a Kibana version in which an API has been deprecated nor enforces docs with migration examples. @stacey-gammon do you think it's something we might be interested to add to the new doc system?

Note: this issue doesn't cover the public API of Kibana (such as config settings, HTTP endpoints) as they might have a different deprecation policy defined by the product requirements.

[elasticmachine]

Pinging @elastic/kibana-core (Team:Core)

[mshustov]

@tsullivan raised a valid concern that it's not clear when the Core team is going to remove deprecated API: #107254
#107255

[pgayvallet]

(if possible) Kibana version in which deprecated API is going to be removed

Imho having visibility on the removal version is crucial for the other teams

[stacey-gammon]

it doesn't seem to cover the whole Core API surface.

What's missing? I can look into that. I'm not aware of any public APIs that aren't being tracked (aside from packages).

I don't believe the new docs system tracks a Kibana version in which an API has been deprecated nor enforces docs with migration examples. @stacey-gammon do you think it's something we might be interested to add to the new doc system

Right, it only supports @removeBy currently. I could easily add support for a new manual tag like @deprecatedIn {version} but automatically tracking that might be tough. Same with enforcing migration examples, though I could capture text written after @deprecated Follow the instructions at [...] to migrate?

[mshustov]

Imho having visibility on the removal version is crucial for the other teams

@pgayvallet I tend to agree, but it's not always possible to know in advance. If you search for @deprecated tag in Core public API, you will find out that none of them have @removeBy tag. There are at least two reasons: the Core team didn't plan the roadmap for v8.x releases and there is no v8.x release schedule. Considering this, I don't think we have enough information to define a precise version when a deprecated API is going to be removed.

What's missing? I can look into that.

https://docs.elastic.dev/kibana-dev-docs/deprecated-api-list-by-plugin and https://docs.elastic.dev/kibana-dev-docs/deprecated-api-list-by-api don't contain any Core API besides LegacyRequest type.
A few examples of deprecated Core API, not an exhaustive list:

kibana/src/core/public/application/types.ts

Line 456 in 909d39b

appBasePath: string;

kibana/src/core/public/application/types.ts

Line 491 in 909d39b

onAppLeave: (handler: AppLeaveHandler) => void;

kibana/src/core/public/application/types.ts

Line 537 in 909d39b

export type AppLeaveHandler = (

kibana/src/core/server/elasticsearch/types.ts

Line 68 in 909d39b

readonly config$: Observable<ElasticsearchConfig>;

kibana/x-pack/plugins/licensing/public/types.ts

Lines 19 to 24 in 909d39b

	license$: Observable<ILicense>;
	/**
	* Triggers licensing information re-fetch.
	* @deprecated in favour of the counterpart provided from start contract
	*/
	refresh(): Promise<ILicense>;

@stacey-gammon I'm not sure the new docs system processes Core types. Does it?

I could easily add support for a new manual tag like @deprecatedIn {version} but automatically tracking that might be tough.

Having it in the docs might be already a good start to spot API deprecated for too long.

Same with enforcing migration examples, though I could capture text written after

Maybe we can require the @example tag for the deprecated API should contain a migration example?

[stacey-gammon]

I'm not sure the new docs system processes Core types. Does it?

Yes, it does/should. There is a bug where API declarations are not being collected recursively. I'm looking into a fix!

[lukeelmers]

I could easily add support for a new manual tag like @deprecatedIn {version} but automatically tracking that might be tough.

Having it in the docs might be already a good start to spot API deprecated for too long.

Same with enforcing migration examples, though I could capture text written after

Maybe we can require the @example tag for the deprecated API should contain a migration example?

++ To both of these ideas. Even though we aren't currently considering the Plugin APIs as subject to semver, it would be nice to move toward a more formal deprecation strategy for these things. A combination of @deprecatedIn and @example feels like good place to start. And if we had a dedicated section of the docs for these, it would be something we could easily surface for other teams (like in newsletters to kibana-contributors).

[stacey-gammon]

@mshustov - the bug should be fixed now and all deprecated types should show up here: https://docs.elastic.dev/kibana-dev-docs/deprecated-api-list-by-api#referenced-deprecated-apis. Let me know if any are missing.

[mshustov]

@stacey-gammon, I can confirm it's fixed. Should I create a dedicated issue to enforce @deprecatedIn and @example tags for the deprecated API? What team should I label there?

[stacey-gammon]

Similar to how I emailed a proposal for @removeBy, I think we should send one out for @deprecatedIn and @example (although I actually prefer @learnmore {link} ), then if no objections, create an issue and add Ops team and APIDocs label and I will see when I can get around to it.

[TinaHeiligers]

closing as done