Documented Jetty versions and compatibilities, and code deprecation policy.

Signed-off-by: Simone Bordet <[email protected]>

Author: sbordet

documentation/jetty/modules/ROOT/pages/index.adoc

@@ -13,12 +13,34 @@
 
 = Eclipse Jetty {page-version}
 
-This section of the site contains the documentation for {page-component-title} {page-version}.
+This is the main documentation page for the Eclipse Jetty Project.
+
+Jetty provides a highly scalable and memory-efficient web server and Servlet container, supporting web protocols such as HTTP/1.1, HTTP/2, HTTP/3 and WebSocket.
+Furthermore, Jetty offers integrations with many other technologies, such as OSGi, JMX, JNDI, JAAS, CDI, etc. and with the relevant Jakarta EE technologies.
+
+Jetty is open source and are freely available for commercial use and distribution under either the link:https://www.eclipse.org/legal/epl-2.0/[Eclipse Public License v2] or the link:https://www.apache.org/licenses/LICENSE-2.0[Apache License v2].
+
+Jetty can either be used as a standalone server to deploy web applications, or as a library that can be used in your code as a dependency.
+
+.Jetty Versions and Compatibilities
+[cols="1a,1a,1a,1a", options="header"]
+|===
+| Jetty Version | Required Java Version | Jakarta EE Version | Status
+| Jetty 12.1.x | Java 17 | Jakarta EE11, EE10, EE9, EE8 | Development
+
+| Jetty 12.0.x | Java 17 | Jakarta EE10, EE9, EE8 | Stable
+
+| Jetty 11.0.x | Java 11 | Jakarta EE9 | EOL (see link:https://github.com/jetty/jetty.project/issues/10485[#10485])
+
+| Jetty 10.0.x | Java 11 | Jakarta EE8 | EOL (see link:https://github.com/jetty/jetty.project/issues/10485[#10485])
+
+| Jetty 9.4.x | Java 8 | Jakarta EE7 | EOL (see link:https://github.com/jetty/jetty.project/issues/7958[#7958])
+|===
 
 == xref:operations-guide:index.adoc[]
 
-The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications.
+The Operations Guide targets sysops, devops, and developers who want to install Jetty as a standalone server to deploy web applications.
 
 == xref:programming-guide:index.adoc[]
 
-The Eclipse Jetty Programming Guide targets developers who want to use the Eclipse Jetty libraries in their applications, and advanced sysops/devops that want to customize the deployment of web applications.
+The Programming Guide targets developers who want to use the Jetty libraries in their applications, and advanced sysops/devops that want to customize the deployment of web applications.

documentation/jetty/modules/programming-guide/pages/index.adoc

@@ -23,3 +23,24 @@ You may use the xref:client/index.adoc[Jetty client-side library] in your applic
 Likewise, you may use the xref:server/index.adoc[Jetty server-side library] to quickly create an HTTP or REST service without having to create a web application archive file (a `+*.war+` file) and without having to deploy it to a Jetty standalone server that you would have to download and install.
 
 This guide will walk you through the design of the Jetty libraries and how to use its classes to write your applications.
+
+== Code Deprecation Policy
+
+As the Jetty code evolves, classes and/or methods are deprecated using the `@Deprecated` annotation and will be removed in a future Jetty release.
+
+The Jetty release numbering follows this scheme: `<major>.<minor>.<micro>`. For example, 12.0.5 has `major=12`, `minor=0` and `micro=5`.
+
+As much as possible, deprecated code is not removed in micro releases.
+Deprecated code may be removed in major releases.
+Deprecated code may be removed in minor releases, but only if it has been deprecated for at least 6 micro releases.
+
+For example, let's assume that Jetty 12.1.0 (a new minor release) is released after the release of Jetty 12.0.11.
+
+Then, code that was deprecated in Jetty 12.0.5 or earlier may be removed from Jetty 12.1.0 (because it has been deprecated for more than 6 micro releases).
+
+On the other hand, code that was deprecated in Jetty 12.0.8 may be removed in Jetty 12.1.3 (because it has been deprecated for 3 micro releases in Jetty 12.0.x, and for 3 micro releases in Jetty 12.1.x -- 12.1.0, 12.1.1 and 12.1.2).
+
+[NOTE]
+====
+There could be rare cases where code (possibly not even deprecated) must be removed earlier than specified above to address security vulnerabilities.
+====