Usability friction with <featureManager><feature> and Jakarta EE 8 -> 10 upgrade.

[edburns]

Describe the bug

I was requested to upgrade a simple EE 8 liberty app to EE 10 in this issue. Along the way, I ran into a little friction which I think a modest doc improvement could reduce.

I had to iterate through a series of error messages such as

[ERROR] Failed to execute goal io.openliberty.tools:liberty-maven-plugin:3.10:install-feature (package-server) on project javaee-cafe: Error installing features for server defaultServer: CWWKF1299E: The following features could not be obtained: jaxb-4.0 restfulws-3.0 enterprisebeanslite-4.0 cdi-4.0 persistence-3.0 faces-4.0 io.openliberty.emptyHandleListContext-1.0 com.ibm.websphere.appserver.ejbliteJNDI-1.0 com.ibm.websphere.appserver.javaeePlatform7.0-jndi1.0 io.openliberty.ejbliteJPA-2.0 io.openliberty.restfulWS3.0-xmlBinding3.0 com.ibm.websphere.appserver.ejbComponentMetadataDecorator-1.0 com.ibm.websphere.appserver.jakarta-transactionContext-1.0 com.ibm.websphere.appserver.classloaderContext-1.0. Ensure that the features are valid for Open Liberty. -> [Help 1]

[ERROR] Failed to execute goal io.openliberty.tools:liberty-maven-plugin:3.10:install-feature (package-server) on project javaee-cafe: Error installing features for server defaultServer: A feature conflict error occurred while installing features: [restfulws-3.0, xmlbinding-4.0, enterprisebeanslite-4.0, cdi-4.0, persistence-3.0, faces-4.0]: CWWKF1405E: The servlet-5.0 and servlet-6.0 singleton features are incompatible with each other and they cannot be installed at the same time.

[ERROR   ] CWWKF0043E: The configured feature restfulWS-3.0 of Jakarta EE 9 is incompatible with the configured feature xmlBinding-4.0 of Jakarta EE 10.  The configuration includes an incompatible combination of Jakarta EE features that is not supported.  Update the configuration to use compatible versions of the configured features that support the Jakarta EE 9 or Jakarta EE 10 programming models.

To finally arrive at the working set of features:

<featureManager>
    <feature>cdi-4.0</feature>
    <feature>xmlBinding-4.0</feature>
    <feature>faces-4.0</feature>
    <feature>restfulWS-3.1</feature>
    <feature>enterpriseBeansLite-4.0</feature>
    <feature>persistence-3.1</feature>
</featureManager>

All the while, I was looking to this documentation to help me. I judge a well-placed reference to a definitive guide such as "Differences between Jakarta EE N and N-1" would have helped. Here is a suggested placement and text.

Steps to Reproduce

1. Git clone https://github.com/azure-javaee/open-liberty-on-aks.git
2. Check out commit 2c8bf374c473236367beec4165ac8d951494b0e9
3. cd java-app
4. mvn clean install

Expected behavior

The Feature overview page would have helped me answer the question: "I'm using EE 10, what is the exact set of featureName-M.m values I need to move to given the app was at 8 beforehand?"

Diagnostic information:

• OpenLiberty Version: 23.0.0.3
• Affected feature(s) various
• Java Version:

openjdk version "17.0.6" 2023-01-17 LTS
OpenJDK Runtime Environment Microsoft-7209853 (build 17.0.6+10-LTS)
OpenJDK 64-Bit Server VM Microsoft-7209853 (build 17.0.6+10-LTS, mixed mode)

• server.xml configuration (WITHOUT sensitive information like passwords)

https://github.com/Azure-Samples/open-liberty-on-aks/blob/2c8bf374c473236367beec4165ac8d951494b0e9/java-app/src/main/liberty/config/server.xml

[dmuelle]

Thanks for opening this issue @edburns - although our doc isn't set up for the exact solution you've proposed, I've updated the Features overview page to hopefully provide better guidance determining which feature versions are attached to which MP or EE platform spec versions.

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/feature-overview.html#_jakarta_ee_and_microprofile_features

@jhanders34 would you review the updated section?

[dmuelle]

Discussed with Jared via slack and revised per his input- he approved the revision.

Open Liberty features that support the MicroProfile, Jakarta EE, and Java EE specifications are sensitive to the version of whatever platform specification they target. For example, features that support Jakarta EE 10 do not interoperate with features that support Jakarta EE 8. Errors occur if you enable these features in the same server configuration.

To avoid these errors, see the Features that this feature enables section on the MicroProfile, Jakarta EE Platform or Java EE Platform convenience feature pages. You can use this list to determine which individual feature versions align with each platform specification version. Alternatively, to enable all the features that support a particular platform specification version, use the MicroProfile, Jakarta EE, or Java EE convenience features.

For more information about migrating your applications from one version of a MicroProfile or Jakarta EE specification to another, see the relevant Differences between…​ pages in the MicroProfile API and Jakarta EE API sections of the documentation.

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/feature-overview.html#_microprofile_jakarta_ee_and_java_ee_features