Improve docs for unknown saved object types #125253

rudolf · 2022-02-10T15:07:49Z

Summary

Expand 8.0 docs to explain the new behaviour from #118300

Checklist

Delete any items that are not applicable to this PR.

Any text added follows EUI's writing guidelines, uses sentence case text and includes i18n support
Documentation was added for features that require explanation or tutorials
Unit or functional tests were updated or added to match the most common scenarios
Any UI touched in this PR is usable by keyboard only (learn more about keyboard accessibility)
Any UI touched in this PR does not create any new axe failures (run axe in browser: FF, Chrome)
If a plugin configuration key changed, check if it needs to be allowlisted in the cloud and added to the docker list
This renders correctly on smaller devices using a responsive layout. (You can test this in your browser)
This was checked for cross-browser compatibility

Risk Matrix

Delete this section if it is not applicable to this PR.

Before closing this PR, invite QA, stakeholders, and other developers to identify risks that should be tested prior to the change/feature release.

When forming the risk matrix, consider some of the following examples and how they may potentially impact the change:

Risk	Probability	Severity	Mitigation/Notes
Multiple Spaces—unexpected behavior in non-default Kibana Space.	Low	High	Integration tests will verify that all features are still supported in non-default Kibana Space and when user switches between spaces.
Multiple nodes—Elasticsearch polling might have race conditions when multiple Kibana nodes are polling for the same tasks.	High	Low	Tasks are idempotent, so executing them multiple times will not result in logical error, but will degrade performance. To test for this case we add plenty of unit tests around this logic and document manual testing procedure.
Code should gracefully handle cases when feature X or plugin Y are disabled.	Medium	High	Unit tests will verify that any feature flag or plugin combination still results in our service operational.
See more potential risk examples

For maintainers

This was checked for breaking API changes and was labeled appropriately

…ved object types"" This reverts commit 580d61d.

into unknown-so-types-docs

kibana-ci · 2022-02-10T15:54:30Z

💚 Build Succeeded

Buildkite Build
Commit: 03c762c

History

💚 Build #23165 succeeded 4306e7f
💚 Build #23161 succeeded 7568d4b

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

elasticmachine · 2022-02-10T16:00:41Z

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

gchaps · 2022-02-10T17:00:52Z

docs/setup/upgrade/upgrade-migrations.asciidoc

@@ -4,8 +4,8 @@

 Each time you upgrade {kib}, an upgrade migration is performed to ensure that all <<managing-saved-objects,saved objects>> are compatible with the new version.

-NOTE: To help you prepare for the upgrade to 7.0.0, 6.7.0 includes an https://www.elastic.co/guide/en/kibana/6.7/upgrade-assistant.html[*Upgrade Assistant*]. 
-To access the assistant, go to *Management > 7.0 Upgrade Assistant*.
+NOTE: To help you prepare for the upgrade to 8.0.0, 7.17.0 includes an https://www.elastic.co/guide/en/kibana/7.17/upgrade-assistant.html[*Upgrade Assistant*]. 


Is this note needed? Given the edits, it says the same thing as the first paragraph of the file. Instead, you could put the link to Upgrade Assistant in the first paragraph.

docs/setup/upgrade/upgrade-migrations.asciidoc

gchaps · 2022-02-10T17:11:24Z

docs/setup/upgrade/upgrade-standard.asciidoc

@@ -1,8 +1,8 @@
 [[upgrade-standard]]
 === Standard upgrade


This content is no long in the doc.

You might also want to look at Upgrade Kibana in the Installation and Upgrade Guide. This doc contains a note about saved object migrations.

As discussed offline there's a discrepancy in our docs between 7.x and 8.x and the structure isn't optimal for 8.x but I will address that in a follow-up

@rudolf @gchaps and I restructured the docs in #125288.

docs/setup/upgrade/upgrade-migrations.asciidoc

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Christiane (Tina) Heiligers <christiane.heiligers@elastic.co>

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

kibana-ci · 2022-02-10T20:32:56Z

💚 Build Succeeded

Buildkite Build
Commit: 24e2fc9

History

💚 Build #23270 succeeded 0b1fe7e
💚 Build #23198 succeeded 03c762c
💚 Build #23190 succeeded be39cb4
💚 Build #23182 succeeded 03c762c
💚 Build #23165 succeeded 4306e7f
💚 Build #23161 succeeded 7568d4b

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

* Revert "Revert "Docs for preventing migrations failing for unknown saved object types"" This reverts commit 580d61d. * Fix links and versions for note to use UA * Migration docs: remove content related to 6.x versions * Upgrade docs, remove content for upgrading from v4/v5 * Link to 7.17 upgrade assistant * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Christiane (Tina) Heiligers <christiane.heiligers@elastic.co> * Update docs/setup/upgrade/upgrade-migrations.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Christiane (Tina) Heiligers <christiane.heiligers@elastic.co> (cherry picked from commit f3b01b6)

kibanamachine · 2022-02-10T20:46:18Z

💚 All backports created successfully

Status	Branch	Result
✅	8.0
✅	8.1

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

Questions ?

Please refer to the Backport tool documentation

* Revert "Revert "Docs for preventing migrations failing for unknown saved object types"" This reverts commit 580d61d. * Fix links and versions for note to use UA * Migration docs: remove content related to 6.x versions * Upgrade docs, remove content for upgrading from v4/v5 * Link to 7.17 upgrade assistant * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Christiane (Tina) Heiligers <christiane.heiligers@elastic.co> * Update docs/setup/upgrade/upgrade-migrations.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Christiane (Tina) Heiligers <christiane.heiligers@elastic.co> (cherry picked from commit f3b01b6) Co-authored-by: Rudolf Meijering <skaapgif@gmail.com>

rudolf added 4 commits February 10, 2022 14:20

Revert "Revert "Docs for preventing migrations failing for unknown sa…

f30f768

…ved object types"" This reverts commit 580d61d.

Fix links and versions for note to use UA

63bb500

Migration docs: remove content related to 6.x versions

9935388

Upgrade docs, remove content for upgrading from v4/v5

7568d4b

rudolf added v8.0.0 v8.1.0 v8.2.0 auto-backport Deprecated - use backport:version if exact versions are needed Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc labels Feb 10, 2022

rudolf added 3 commits February 10, 2022 16:16

Merge branch 'main' into unknown-so-types-docs

4306e7f

Link to 7.17 upgrade assistant

8ae5cdb

Merge branch 'unknown-so-types-docs' of https://github.com/rudolf/kibana

03c762c

into unknown-so-types-docs

rudolf marked this pull request as ready for review February 10, 2022 16:00

rudolf added the release_note:skip Skip the PR/issue when compiling release notes label Feb 10, 2022

rudolf force-pushed the unknown-so-types-docs branch from be39cb4 to 03c762c Compare February 10, 2022 16:27

Bamieh approved these changes Feb 10, 2022

View reviewed changes

gchaps reviewed Feb 10, 2022

View reviewed changes

TinaHeiligers reviewed Feb 10, 2022

View reviewed changes

docs/setup/upgrade/upgrade-migrations.asciidoc Outdated Show resolved Hide resolved

TinaHeiligers approved these changes Feb 10, 2022

View reviewed changes

rudolf commented Feb 10, 2022

View reviewed changes

docs/setup/upgrade/upgrade-migrations.asciidoc Outdated Show resolved Hide resolved

rudolf and others added 2 commits February 10, 2022 21:28

Apply suggestions from code review

0b1fe7e

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Christiane (Tina) Heiligers <christiane.heiligers@elastic.co>

Update docs/setup/upgrade/upgrade-migrations.asciidoc

24e2fc9

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

rudolf enabled auto-merge (squash) February 10, 2022 20:32

rudolf merged commit f3b01b6 into elastic:main Feb 10, 2022

kibanamachine mentioned this pull request Feb 10, 2022

[8.0] Improve docs for unknown saved object types (#125253) #125309

Merged

kibanamachine mentioned this pull request Feb 10, 2022

[8.1] Improve docs for unknown saved object types (#125253) #125310

Merged

rudolf deleted the unknown-so-types-docs branch February 11, 2022 09:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve docs for unknown saved object types #125253

Improve docs for unknown saved object types #125253

rudolf commented Feb 10, 2022 •

edited

Loading

kibana-ci commented Feb 10, 2022

elasticmachine commented Feb 10, 2022

gchaps Feb 10, 2022

gchaps Feb 10, 2022

rudolf Feb 10, 2022

TinaHeiligers Feb 10, 2022

kibana-ci commented Feb 10, 2022

kibanamachine commented Feb 10, 2022

Improve docs for unknown saved object types #125253

Improve docs for unknown saved object types #125253

Conversation

rudolf commented Feb 10, 2022 • edited Loading

Summary

Checklist

Risk Matrix

For maintainers

kibana-ci commented Feb 10, 2022

💚 Build Succeeded

History

elasticmachine commented Feb 10, 2022

gchaps Feb 10, 2022

Choose a reason for hiding this comment

gchaps Feb 10, 2022

Choose a reason for hiding this comment

rudolf Feb 10, 2022

Choose a reason for hiding this comment

TinaHeiligers Feb 10, 2022

Choose a reason for hiding this comment

kibana-ci commented Feb 10, 2022

💚 Build Succeeded

History

kibanamachine commented Feb 10, 2022

💚 All backports created successfully

Questions ?

rudolf commented Feb 10, 2022 •

edited

Loading