Can we add a note similar to the following at the start of the upgrade doc and OperatorHub info/detail page?

Since 1.8 release, the Operator only supports v1beta2 custom resources, so you must use the API conversion tool before upgrading (requires Java 11). We suggest to upgrade to 1.7 first, do the conversion steps (convert-resource first and then crd-upgrade) and finally upgrade to the target release.

Most of the customers use the stable channel with automatic upgrades and we are seeing a lot of cases with a pending upgrade due to missing conversion steps.

In addition to that, it would be good to avoid the upgrade process to start in the first place when there are beraking changes to the API. This is something that the OLM should take care of.

Reproducer

Install AMQ Streams 1.7 channel using the OperatorHub, then change the Subscription to stable and after few seconds you get the pending upgrade.

Recovery

First, download the API conversion tool:

https://access.redhat.com/jbossnetwork/restricted/softwareDetail.html?softwareId=100961&product=jboss.amq.streams&version=1.8.0&downloadType=distributions

Then, make sure to apply the conversion steps in this exact order:

# step 0: convert the format of custom resources
bin/api-conversion.sh convert-resource -a

# step 1: upgrade CRDs to v1beta2
bin/api-conversion.sh crd-upgrade

Finally, uninstall all Streams operators from the web UI and reinstall 1.8 (this will cause a rolling update after the new operator starts).