Add Kibana upgrade notes page

[florent-leborgne]

Summary

This PR:

• adds a page that is a compiled list of all breaking changes and deprecations introduced since the last major version. I slightly edited some bits to align the wording and add version information to each item, and took a bit of freedom (not too much!) to ignore items that shouldn't be identified as deprecations or breaking changes, or to move them to the appropriate section in this page.
• adds a link to the new page from the Upgrade Kibana page.

I'm wondering if we should leave this uncategorized or at least identify which items are specific to a solution. It also doesn't make much sense that we have Obs here while we don't have Security. Let's think about a consistent way to do it.

Note: In this PR, the page is initially added under the Release notes section. I'll need to make sure that this does not interfere with the release notes automation.

Note 2: If we move forward with this proposal, we'll need update the release notes internal docs to add the relevant information to this page with each minor release, or find a way to automate.

Closes: https://github.com/elastic/kibana-team/issues/1075

[elasticmachine]

Pinging @elastic/kibana-docs (Team:Docs)

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[sophiec20]

Overall, the page looks good and as expected. Thank you. In the short term, we will have a burden on manual updates, and agree we should look for ways to improve with automation and find-ability of this content. This first version gives visibility for early planning, so I'm glad we are doing this sooner.

I'm wondering if we should leave this uncategorized or at least identify which items are specific to a solution. It also doesn't make much sense that we have Obs here while we don't have Security. Let's think about a consistent way to do it.

At some point, it makes sense to categorize this list, and this can be driven by the Obs team priorities. Let's start with improving visibility of the information for upgrade planning and publishing what is already in the release notes in an easier-to-view location.

[lukeelmers]

This seems like a great first iteration, thank you! I'm wondering how these are being manually compiled. Are we going back to the raw release note labels on PRs to find things that are labeled as breaking, using the release notes tool? Or are we combing through the existing release note docs and just copying things that are already labeled as breaking there?

I'm trying to understand how we have o11y but not security coverage here... I'm guessing there's part of the release notes prep process that I'm unfamiliar with.

[florent-leborgne]

@lukeelmers For this one I went manually over the Kibana asciidoc files and extracted what seemed relevant + slightly rewrote them to make the items more parallel/easier to read. The content is mirroring what we're doing on the release notes side: Kibana RNs include Obs, but Security has its own. I'm hoping that following this first iteration we can:

• investigate automation for this doc as part of the release notes generation.
• investigate how we can improve the quality of the content initially gathered by the release notes tool in original PRs (correct PR labels, and good titles/descriptions)
• investigate how to present/include solution content consistently

I also just got started with Kibana so I'm not familiar with everything yet either

[jloleysens]

Not sure if in the scope of this PR, for 9.0 devs should make (relatively short) migration guides users can follow while upgrading. We want to (deep)link to a specific migration guide from Kibana’s upgrade assistant.

I think UA can help refine this experience nicely by surfacing relevant deprecations as an upgrade checklist (i.e. ones that Kibana can see in the users stack). Can this support some kind of deep linking? Kibana core is hoping to create steps for Kibana devs to follow when deprecating, for example, an HTTP API and one of the steps would be “create a guide in docs/upgrade-notes”.

Then in Kibana we would link from upgrade assistant to that specific guide using something like: https://www.elastic.co/guide/kibana/upgrade-notes/8.last#my-api-deprecation

[lcawl]

Added some minor suggestions, otherwise LGTM

[lukeelmers]

This looks great! I'd like to echo @jloleysens suggestion for these items to be something we can deeplink to from upgrade assistant.

My other suggestion would be to do some sort of grouping similar to what we do in release notes to help people understand what areas of Kibana some of these breaking changes relate to (eg platform, visualizations, observability...). This helps folks understand what they might be able to ignore and what's relevant to them. I could see this either being categories that changes are listed under, or "tags" that are added at the beginning of each change description.

[florent-leborgne]

@lukeelmers @jloleysens I have removed ids from specific items to not cause id conflicts with the traditional, per minor, release notes (in those ones breaking changes & deprecations have IDs). Would the need here be to link to items individually from the Upgrade Assistant, or to categories?

I also wondered about categories and tried several things on my local, it makes the file much harder to read when there are many more sections with sometimes 1 item in it, so I went with chronological order, also because there aren't so many items. Maybe tags would be more helpful, or at least more explicitly call out which area of the product each item applies to in its title. Happy to collect more opinions on that.

[jloleysens]

Would the need here be to link to items individually from the Upgrade Assistant, or to categories?

I would say individual items. E.g.

(1) saved object HTTP API deprecations - may be a slightly longer guide/entry
(2) legacy response ops' rules endpoints going away
...

Linking to each of those from UA would awesome. I can imagine cases where linking to a category might be useful, but mostly linking to a specific actionable thing would be best.

[florent-leborgne]

Re: categorizing, actually we may have more items than I initially included in there because I didn't add the changes from the RCs, Beta, and Alpha of v8, so it would make sense to have a 2 levels of sorting:

1/ Per area
2/ Inside of each area, per minor

For example, this page categorizes the breaking changes. WDYT?

I'll also re-add IDs for each item in that new page. So that we can link individually to them.

[florent-leborgne]

I'm in the process of adding some items I initially missed, and testing various ways to organize the page. Will update when ready to share

[KOTungseth]

Tiny tweaks, otherwise this is amazing. Thank you!

[lukeelmers]

Caught a few typos & had a few corrections, otherwise this looks great!

[jloleysens]

This is a great first step. The template and approach look good to me! Gives us both place to write guides and a way to link to them! Nice work!

[jloleysens]

Not 100% I follow what codeId is

[florent-leborgne]

That's the ID assigned to the link in the doc link service file, that can be called in the code instead of hardcoding the link. I slightly edited the template and added a link to a small doc explaining the docs link service, hopefully this will be clearer.

[kibanamachine]

Starting backport for target branches: 8.x

https://github.com/elastic/kibana/actions/runs/11213022409

[kibanamachine]

💚 All backports created successfully

Status	Branch	Result
✅	8.x

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation