[Core deprecations service] Markdown support

[alisonelizabeth]

It'd be helpful if the core deprecations service supported markdown when defining a deprecation's message and manual steps. This would improve the UX in Upgrade Assistant, by allowing deprecations to render with bold and code formatting, as well as active links.

Example:

[elasticmachine]

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

[pgayvallet]

Don't know about the manual steps, but at least the message is not meant to exclusively be used/displayed in UA, right? For this reason, I don't think we could allow markdown in the existing fields?

A option would be to add optional markDownMessage and markDownManualSteps (or to create subfields under message and manualSteps). That way the current properties remain usable anywhere, and the UI could use the optional fields if present?

Wonder if it's worth the complexity though?

[Bamieh]

@pgayvallet I'm afraid if we add markdown* fields we might be increasing the surface area for inconsistent messaging between plain and markdown texts.

Creating subfields might be a more flexible here as maybe not all steps need to be in markdown hence we dont need to duplicate steps between fields:

type DeprecationText = string | { plain: string; markdown?: string };
..

message: DeprecationText;
markDownManualSteps: DeprecationText[];

My personal suggestion is to think about introducing a markdown function that takes a text and allows only a subset of markdown to be used (bold, underline, hyperlinks, italic). Basic markdown can be easily stripped back into plain text if needed.

message: string; // might be a small set of markdown or plain text.
markDownManualSteps: string[];

console.log(textTool.display(message, 'plainText'));

Just psuedo code but i'm sure there are some functions that already exist in the wild for this that we can adopt or just introducing our own. This tool might get adoption by other services (notification center comes to mind)

[simitt]

It would be great if Links to other apps within Kibana would be supported in the manual instructions. APM is planning on registering a deprecation pointing to a UI flow within the APM app for fixing the deprecation.

[sorenlouv]

fyi: This is needed for #113567 scheduled for 7.16

[lukeelmers]

Thanks for the heads up @sqren. We don't know for sure yet if we'll be able to get this feature in for 7.16, so I'd recommend merging your deprecation without a link as the first step.

Edit: Ah, I see this is your plan anyway 🙂

[pgayvallet]

My personal suggestion is to think about introducing a markdown function that takes a text and allows only a subset of markdown to be used

What if the deprecation owner uses markdown syntax outside of this subset? We keep it unchanged? We strip it to plain text?

but i'm sure there are some functions that already exist in the wild for this that we can adopt

Yea, I think most markdown libraries supports passing an allowlist of syntax nodes.

console.log(textTool.display(message, 'plainText'));

If this markdown subset officially becomes a supported feature of the deprecations api, we'll probably want something integrated in a more elegant way. We'd probably want the deprecation client's getAllDeprecations to return more than just DomainDeprecationDetails, with direct methods to render markdown-able fields.

e.g

const [deprecation] = await client.getAllDeprecations();
deprecation.title // error - private
deprecation.getTitle('plainText');
deprecation.getTitle('markdown');

[lukeelmers]

@cjcenizal As we were not able to get this enhancement in for 7.16 FF, do you think we should still keep it open as a future enhancement for Upgrade Assistant? Or do you think we will want to solve the problem differently for the next release?

[cjcenizal]

@lukeelmers Can we keep this open for now, until we've had a cycle to think through the functionality we need for UA post-7.16? I expect we'll reconsider this proposed functionality and decide whether or not we need it.

[stuartnelson3]

Just wanted to check in, is this something that might be done for 8.0 FF?

[pgayvallet]

Just wanted to check in, is this something that might be done for 8.0 FF?

8.0 is already past FF, so no.

[pgayvallet]

No activity on the issue for years, and knowing that this was initially meant for 8.0, I'll assume we don't need it anymore and will close.