[Upgrade Assistant] Add note about compatibility headers

[sabarasaba]

This PR adds a little note in the Overview page as part of the third step to hint users to apply compatibility header to all requests.

[debadair]

I don't think it's a safety net, I think it's an either-or thing: you address the deprecation and test, or you include a compatibility header. If you've made modifications to be compatible with 8.0 and include headers that request 7.x compatibility, I think things will break. AFAIK, you theoretically could choose to fix some things, but not others--it's set on a per-request basis.

There isn't currently a good place to link to--I'll fix that & provide the URL.

Suggested change

	defaultMessage="We advise bringing your log count down to zero to guarantee your upgrade will be free of issues. However, it can be challenging to be certain that all requests have been fixed, and by applying the compatibility header to all requests provides an additional safety net. {learnMoreLink}."
	defaultMessage="We recommend resolving deprecation issues before upgrading. However, if you need to enable an application to continue to function without making changes, you can include API compatibility headers in your requests. Learn more{learnMoreLink}."

[sabarasaba]

Thanks for pointing that out! I've fixed the copy with your suggestion and waiting for your ticket to be merged so I can add the link here.

[cjcenizal]

@debadair The guidance I received from @jakelandis was that we advise users to apply the REST API compatibility header to all API requests, but it’s not guaranteed to address any problems -- it might help, it might not. We advise users to bring their log count down to zero, because that’s the only way to guarantee that their upgrade will be free of issues. However, it can be challenging to be certain that all requests have been fixed, and by applying the compatibility header to all requests users give themselves an additional safety net.

Jake, could you please confirm or clarify?

[jakelandis]

@cjcenizal - confirm. Most importantly "We advise users to bring their log count down to zero, because that’s the only way to guarantee that their upgrade will be free of issues. "

Since compatiblity is only API compatibility and not a pure versioned API there can times when compatiblity if applied may not work. For example, if your request includes a type (as in mapping types) without compatiblity you will get an error, likey a parsing or missing error, but if you use REST API compatiblity it will still allow that request to be processed, but will ignore the requested type since in 8.0 there is no such thing as mapping types. In some other cases compatiblity simply can't be applied and will result in a more friendly error message. REST API compatiblity sweet spot is when the REST API changed in a way where there is a 1:1 replacement of something old to something new... in those cases it map the old -> new pretty easily.

@debadair - I have a todo to kickstart the conversation around the public documentation for this feature. We need to be careful to identify the right balance of documenting the value and caveats of using this.

[sabarasaba]

@elasticmachine merge upstream

[elasticmachine]

Pinging @elastic/kibana-stack-management (Team:Stack Management)

[cjcenizal]

@debadair Could you review again, please? Jake added some additional context above.

[jrodewig]

Thanks for incorporating @debadair's suggestion and adding the doc link.

Overlooked the additional commentary. Doing another review.

Overlooked some additional commentary

[jrodewig]

I commited a copy update. With that, this LGTM.

[cjcenizal]

Thanks for doing this Ignacio! I spotted one missed translation.

[sabarasaba]

@elasticmachine merge upstream

[cjcenizal]

Code LGTM, didn't test locally.

[kibanamachine]

💚 Build Succeeded

• continuous-integration/kibana-ci/pull-request
• Commit: 0bc20f1
• Storybooks Preview

Metrics [docs]

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
upgradeAssistant	210.9KB	212.6KB	+1.7KB

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
core	407.2KB	407.3KB	+83.0B

History

• 💔 Build #154305 failed 151563f
• 💚 Build #154061 succeeded 6a18004
• 💔 Build #154016 failed c89a68a
• 💚 Build #151133 succeeded c3886e3
• 💚 Build #150523 succeeded eef581cd7f62fe63c8b29012c008f3ed5109bb6e

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

cc @sabarasaba