edits for mp ee feature compatibility

#7227

modules/reference/pages/feature/feature-overview.adoc

@@ -50,6 +50,46 @@ For details about the server configuration, see the xref:config/server-configura
 
 Occasionally, Liberty features that are not listed in the `server.xml` file are enabled automatically by other features. To confirm whether a particular feature is enabled in a Liberty server, inspect the `CWWKF0012I` message in the `console.log`, `messages.log`, or `trace.log` from the Liberty server. This message provides a comprehensive list of all the features that are installed and running on the Liberty server.
 
+== Feature combinations and compatibility
+Not all Open Liberty features and feature versions are interoperable and some combinations might result in compatibility errors if they are enabled in the same server configuration.
+
+=== Singleton features and feature versions
+
+A singleton feature is a feature that you can configure only one version of per server. Most Open Liberty features are singleton features. If your server configuration includes multiple versions of the same singleton feature, either through direct configuration in the `server.xml` file or through feature dependencies, an error occurs and neither version of that feature is loaded.
+
+To resolve this problem, ensure that the configured features all specify, or tolerate, the same version of that singleton feature.
+If you have hard requirements on both feature versions, you must move some of your applications to a different server.
+
+=== Jakarta EE and MicroProfile features
+Open Liberty features that support the Jakarta EE and MicroProfile specifications are sensitive to the version of each specification that they target. For example, some features that support the Jakarta EE 10 specification might not interoperate with other features that support the Jakarta EE 8 specification and an error might occur if you configure them in the same server.
+
+To avoid these errors, choose versions of features that target specification version, or use <<#conv,convenience features>> to automatically enable MicroProfile and Jakarta EE features from the same specification version instead of enabling them individually. For more information about the specific feature versions that align with specification versions, see the feature:microprofile[display=MicroProfile] and feature:jakartaee[display=Jakarta EE] convenience feature pages. For more information about moving from one version of a MicroProfile or Jakarta EE specification to another, see the relevant "Differences between" pages in the xref:javadoc/microprofile-api.adoc[MicroProfile API] and xref:javadoc/jakartaee.adoc[Jakarta EE API] sections of the documentation.
+
+=== Java EE 7 and Java EE 8 feature combinations
+Open Liberty doesn't support combining features from both Java EE 7 and Java EE 8, except when the Java EE 7 and Java EE 8 specifications share a component specification version.
+If you combine Java EE 7 and Java EE 8 features in a server configuration, the server reports errors at startup.
+
+The following features are included in both Java EE 7 and Java EE 8:
+
+* feature:appClientSupport-1.0[display="Application Client Support for Server 1.0"]
+* feature:batch-1.0[display="Batch API 1.0"]
+* feature:concurrent-1.0[display="Concurrency Utilities for Java EE 1.0"]
+* feature:ejb-3.2[display="Enterprise JavaBeans 3.2"]
+* feature:j2eeManagement-1.1[display="J2EE Management 1.1"]
+* feature:jacc-1.5[display="Java Authorization Contract for Containers 1.5"]
+* feature:jca-1.7[display="Java Connector Architecture 1.7"]
+* feature:jcaInboundSecurity-1.0[display="Java Connector Architecture Security Inflow 1.0"]
+* feature:jdbc-4.2[display="Java Database Connectivity 4.2"]
+* feature:jdbc-4.3[display="Java Database Connectivity 4.3"]
+* feature:jms-2.0[display="Java Message Service 2.0"]
+* feature:jaxws-2.2[display="Java Web Services 2.2"]
+* feature:wasJmsClient-2.0[display="JMS 2.0 Client for Message Server"]
+* feature:wasJmsServer-1.0[display="Message Server 1.0"]
+* feature:wasJmsSecurity-1.0[display="Message Server Security 1.0"]
+
+For a complete list of features that support Java EE 7, see the feature:javaee-7.0[display="Java EE Full Platform 7.0"] feature.
+For a complete list of features that support Java EE 8, see the feature:javaee-8.0[display="Java EE Full Platform 8.0"] feature.
+
 [#conv]
 === Convenience features
 You can enable a whole set of features all at once by specifying one of the convenience features. Convenience features automatically enable all the individual Open Liberty features that are associated with a particular platform or functional area.
@@ -82,40 +122,6 @@ These versioned features continue to be supported across Open Liberty updates.
 If you continue to use the same feature version, you never need to migrate your application.
 For more information about zero migration with Open Liberty, see xref:ROOT:zero-migration-architecture.adoc[Zero-migration architecture].
 
-== Combining features
-If you try to configure a server to have different versions of a feature, an error is reported because Open Liberty doesn't support combining different versions of the same feature.
-This means that most Open Liberty features are singleton features.
-A singleton feature is a feature for which you can configure only one version for use in a server.
-
-If you have applications that need different versions of the singleton feature, you must deploy them in different servers.
-If your server configuration includes multiple versions of a singleton feature, either through direct configuration in the `server.xml` file, or through feature dependencies, that configuration is in error and neither version of that feature is loaded.
-To resolve this problem, ensure that the configured features all specify, or tolerate, the same version of that singleton feature.
-If you have hard requirements on both feature versions, you must move some of your applications to a different server.
-
-Open Liberty doesn't support combining features from both Java EE 7 and Java EE 8, except when the Java EE 7 and Java EE 8 specifications share a component specification version.
-If you combine Java EE 7 and Java EE 8 features in a server configuration, the server reports errors at startup.
-
-The following features are included in both Java EE 7 and Java EE 8:
-
-* feature:appClientSupport-1.0[display="Application Client Support for Server 1.0"]
-* feature:batch-1.0[display="Batch API 1.0"]
-* feature:concurrent-1.0[display="Concurrency Utilities for Java EE 1.0"]
-* feature:ejb-3.2[display="Enterprise JavaBeans 3.2"]
-* feature:j2eeManagement-1.1[display="J2EE Management 1.1"]
-* feature:jacc-1.5[display="Java Authorization Contract for Containers 1.5"]
-* feature:jca-1.7[display="Java Connector Architecture 1.7"]
-* feature:jcaInboundSecurity-1.0[display="Java Connector Architecture Security Inflow 1.0"]
-* feature:jdbc-4.2[display="Java Database Connectivity 4.2"]
-* feature:jdbc-4.3[display="Java Database Connectivity 4.3"]
-* feature:jms-2.0[display="Java Message Service 2.0"]
-* feature:jaxws-2.2[display="Java Web Services 2.2"]
-* feature:wasJmsClient-2.0[display="JMS 2.0 Client for Message Server"]
-* feature:wasJmsServer-1.0[display="Message Server 1.0"]
-* feature:wasJmsSecurity-1.0[display="Message Server Security 1.0"]
-
-For a complete list of features that support Java EE 7, see the feature:javaee-7.0[display="Java EE Full Platform 7.0"] feature.
-For a complete list of features that support Java EE 8, see the feature:javaee-8.0[display="Java EE Full Platform 8.0"] feature.
-
 == Superseded features
 If a feature is superseded, a new feature or a combination of features might provide an advantage over the superseded feature.
 The new feature or features might not completely replace the function of the superseded feature, so you must consider your scenario before you decide whether to change your configuration.