Improvements to the contribution guide.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>

CONTRIBUTING.md

@@ -1,21 +1,19 @@
-Contributing to Jetty
-=====================
+# Contributing to Jetty
 
 Contributions are always welcome!
-Please see our [Contribution Guide](https://eclipse.dev/jetty/documentation/jetty-12/contribution-guide/index.html) for instructions on how to set up your development environment, as well as information on our processes and coding standards.
+Please see our [Contribution Guide](https://eclipse.dev/jetty/documentation/contribution-guide/index.html) for instructions on how to set up your development environment, as well as information on our processes and coding standards.
 
 Here are some quick links to other useful resources:
 
 * [**Source code.**](https://github.com/eclipse/jetty.project) Jetty's canonical git repository is located on GitHub at https://github.com/eclipse/jetty.project.
 
-* [**Mailing list.**](https://dev.eclipse.org/mailman/listinfo/jetty-dev) The [` jetty-dev@eclipse.org`](https://dev.eclipse.org/mailman/listinfo/jetty-dev) mailing list is a forum for technical discussion.
+* [**Mailing list.**](https://accounts.eclipse.org/mailing-list/jetty-users) The [`jetty-users@eclipse.org`](mailto:jetty-users@eclipse.org) mailing list is a forum for technical discussion.
 
 * [**Issue tracking.**](https://github.com/eclipse/jetty.project/issues) We use [GitHub Issues](https://github.com/eclipse/jetty.project/issues) to track ongoing development and issues.
 
 
+## Eclipse Contributor Agreement
 
-Eclipse Contributor Agreement
-------------------------------
 Before we can accept your contributions to the Jetty project, you will need to create and electronically sign a [Eclipse Contributor Agreement (ECA)](http://www.eclipse.org/legal/ecafaq.php):
 
 1. Create an account on the [Eclipse foundation website](https://accounts.eclipse.org/user/login/) if you have not already done so.
@@ -24,8 +22,8 @@ Before we can accept your contributions to the Jetty project, you will need to c
 Be sure to use the same email address in your Eclipse account that you intend to use when you commit to GitHub.
 
 
-Reporting Security Issues
--------------------------
+## Reporting Security Issues
+
 Jetty is actively developed by the team at [Webtide](https://webtide.com/), and the most direct method for reporting security issues is to mail [security@webtide.com](mailto:security@webtide.com).
 
 We are flexible in how we work with reporters of security issues; however, we reserve the right to act in the interests of the Jetty project in all circumstances.

README.md

@@ -1,46 +1,51 @@
-Eclipse Jetty
-=============
+# Eclipse Jetty
 
 Eclipse Jetty is a lightweight, highly scalable, Java-based web server and Servlet engine.
 Jetty's goal is to support web protocols (HTTP/1, HTTP/2, HTTP/3, WebSocket, etc.) in a high volume low latency way that provides maximum performance while retaining the ease of use and compatibility with years of Servlet development.
 Jetty is a modern fully asynchronous web server that has a long history as a component oriented technology, and can be easily embedded into applications while still offering a solid traditional distribution for webapp deployment.
 
-- [https://projects.eclipse.org/projects/rt.jetty](https://projects.eclipse.org/projects/rt.jetty)
+- https://eclipse.dev/jetty/
+- https://projects.eclipse.org/projects/rt.jetty
 
-Webapp Example
---------------
+## Webapp Example
 
 ```shell
-$ mkdir base && cd base
+$ mkdir jetty-base && cd jetty-base
 $ java -jar $JETTY_HOME/start.jar --add-modules=http,ee10-deploy
 $ cp ~/src/myproj/target/mywebapp.war webapps
 $ java -jar $JETTY_HOME/start.jar 
 ```
 
-Multiple Versions Webapp Example
---------------------------------
+## Multiple Versions Webapp Example
 
 ```shell
-$ mkdir base && cd base
+$ mkdir jetty-base && cd jetty-base
 $ java -jar $JETTY_HOME/start.jar --add-modules=http,ee10-deploy,ee8-deploy
 $ cp ~/src/myproj/target/mywebapp10.war webapps
 $ cp ~/src/myproj/target/mywebapp8.war webapps
-$ echo environment: ee8 > webapps/mywebapp8.properties
+$ echo "environment: ee8" > webapps/mywebapp8.properties
 $ java -jar $JETTY_HOME/start.jar 
 ```
 
-Embedded Example
-----------------
+## Embedded Jetty Example
 
 ```java
 Server server = new Server(port);
-ServletContextHandler context = new ServletContextHandler(server, "/");
+server.setHandler(new MyHandler());
+server.start();
+```
+
+## Embedded Servlet Example
+
+```java
+Server server = new Server(port);
+ServletContextHandler context = new ServletContextHandler("/");
 context.addServlet(MyServlet.class, "/*");
+server.setHandler(context);
 server.start();
 ```
 
-Documentation
-=============
+# Documentation
 
 [Jetty's documentation](https://eclipse.dev/jetty/documentation) is available on the Eclipse Jetty website.
 
@@ -53,6 +58,6 @@ The documentation is divided into three guides, based on use case:
 * The [Contribution Guide](https://eclipse.dev/jetty/documentation/jetty-11/contribution-guide/index.html) targets developers that wish to contribute to the Jetty Project with code patches or documentation improvements.
 
 
-Commercial Support
-==================
+# Commercial Support
+
 Expert advice and production support of Jetty are provided by [Webtide](https://webtide.com).

documentation/jetty-documentation/src/main/asciidoc/contribution-guide/.asciidoctorconfig

@@ -0,0 +1,5 @@
+:ee-all: ee{8,9,10}
+:ee-current: ee10
+:ee-current-caps: EE 10
+:experimental:
+:imagesdir: images

documentation/jetty-documentation/src/main/asciidoc/contribution-guide/1-introduction.adoc

@@ -16,7 +16,7 @@
 
 The Eclipse Jetty Contribution Guide targets developers and writers who want to make contributions to the Jetty project by contributing code, writing documentation, or engaging in the larger community.
 
-[[cg-mailing-lists]]
+[[cg-intro-mailing-lists]]
 === Mailing Lists
 
 One of the easiest ways to get involved is via our mailing lists:
@@ -26,30 +26,31 @@ One of the easiest ways to get involved is via our mailing lists:
 * *Jetty Announcements* (https://accounts.eclipse.org/mailing-list/jetty-announce[jetty-announce], https://www.eclipse.org/lists/jetty-announce[archives]) is for announcements about new releases and other updates from the project's maintainers.
 
 
-[[cg-stack-overflow]]
+[[cg-intro-stack-overflow]]
 === Stack Overflow
 
 Another great resource, both for Jetty novices who need help and Jetty experts who want to contribute, is http://stackoverflow.com[StackOverflow].
 In particular, the https://stackoverflow.com/questions/tagged/jetty[`jetty`] and https://stackoverflow.com/questions/tagged/embedded-jetty[`embedded-jetty`] tags see regular traffic.
 
 
-[[cg-filing-issues]]
+[[cg-intro-filing-issues]]
 === Filing Issues
 
 You can flag potential bugs or suggest new Jetty features on our https://github.com/eclipse/jetty.project/issues[issue tracker].
 
-:icons: font
-[WARNING]
-====
-Note that the issue tracker is **not** meant as a standard support channel.
-For individualized help, you'll have more success on the <<cg-mailing-lists,mailing lists>> or posting your question to <<cg-stack-overflow,Stack Overflow>>.
-====
-
 Before filing a new issue, https://github.com/eclipse/jetty.project/issues[check the tracker] to see if it's already been filed by someone else.
 If you do file an issue, make sure to label it appropriately, as this will help the development team (and other users) find it more easily.
 
 
-[[cg-help-wanted]]
+[[cg-intro-help-wanted]]
 === Help Wanted
 If you want to contribute to Jetty but don't have a specific task or goal in mind, consider looking through our https://github.com/eclipse/jetty.project/issues?q=is%3Aopen+is%3Aissue+label%3A%22Help+Wanted%22["Help Wanted" issue backlog].
 These tasks range from the simple to the complex, but they're all ones we've identified as being particularly well-suited for new contributors to tackle.
+
+
+[[cg-intro-commercial-support]]
+=== Commercial Support
+link:https://webtide.com[Webtide] is the company behind Jetty that provides services and support for the Jetty Project.
+
+mailto:sales@webtide.com[Contact Webtide].
+

documentation/jetty-documentation/src/main/asciidoc/contribution-guide/2-eca.adoc

@@ -27,4 +27,4 @@ The email address you use to sign the ECA **must be the same** as the email you
 ====
 
 Jetty's build process has a git hook that verifies each incoming pull request is signed with an email address with an active ECA.
-If the git hook cannot verify your email, the Jetty committers **cannot do anything** to accept your commit**.
+If the git hook cannot verify your email, the Jetty committers **cannot do anything** to accept your commit.

documentation/jetty-documentation/src/main/asciidoc/contribution-guide/3-source.adoc

@@ -11,45 +11,39 @@
 // ========================================================================
 //
 
-[[cg-getting-source]]
+[[cg-source]]
 == Getting the source code
 
 Jetty's source is maintained on GitHub at https://github.com/eclipse/jetty.project, where it is managed by the http://github.com/eclipse/[Eclipse Foundation].
 
 You can clone a copy of the Jetty repo onto your local machine by running:
 
-[source, shell]
 ----
 git clone https://github.com/eclipse/jetty.project.git
 ----
 
-[[cg-repositories]]
-=== Secondary repositories
+[[cg-source-repositories]]
+=== Related repositories
 
-In addition to the https://github.com/eclipse/jetty.project[primary Jetty code repository], we maintain a number of secondary repos for project-related code and metadata:
+In addition to the https://github.com/eclipse/jetty.project[Jetty code repository], we maintain a number of related repositories:
 
-Administrative pom.xml file:: https://github.com/eclipse/jetty.parent
-Build toolchain artifacts:: https://github.com/eclipse/jetty.toolchain
-Development files/configuration:: https://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git
+Non-Eclipse Jetty Repositories:: https://github.com/jetty-project
+Build Toolchain:: https://github.com/eclipse/jetty.toolchain
 
-[[cg-version-branches]]
+[[cg-source-branches]]
 === Version branches
 If you plan to work on a specific issue within Jetty, make sure to target the correct branch for your pull request.
 
-.Active and inactive Jetty branches
+.Active Jetty branches
 [cols="4"]
 |===
 | https://github.com/eclipse/jetty.project/tree/jetty-12.0.x[jetty-12.0.x] | Development (default branch) | Servlet 6.0 | Java 17+
 | https://github.com/eclipse/jetty.project/tree/jetty-11.0.x[jetty-11.0.x] | Maintenance | Servlet 5.0 | Java 11+
 | https://github.com/eclipse/jetty.project/tree/jetty-10.0.x[jetty-10.0.x] | Maintenance | Servlet 4.0 | Java 11+
-| https://github.com/eclipse/jetty.project/tree/jetty-9.4.x[jetty-9.4.x] | End of Community Support | Servlet 3.1 | Java 8
-| https://github.com/eclipse/jetty.project/tree/jetty-9.3.x[jetty-9.3.x] | End of Life | Servlet 3.1 | Java 8
-| jetty-8 | Historical | Servlet 3.1 | Java 6
-| jetty-7 | Mythical | Servlet 2.5 | Java 5
+| https://github.com/eclipse/jetty.project/tree/jetty-9.4.x[jetty-9.4.x] | link:https://github.com/eclipse/jetty.project/issues/7958[End of Community Support] | Servlet 3.1 | Java 8+
 |===
 
-Maintenance branches are periodically merged wholesale into active development branches.
-As such, *changes to maintenance branches should typically be forward compatible* with later releases.
+Maintenance branches are periodically merged into active development branches.
 
 Older branches are only updated if they get specifically targeted by a pull request.
 Also, changes to older branches aren't regularly merged forward -- although an individual change may be cherry-picked forward, depending on the nature of the fix.

documentation/jetty-documentation/src/main/asciidoc/contribution-guide/4-build.adoc

@@ -11,28 +11,29 @@
 // ========================================================================
 //
 
-[[cg-building-jetty]]
+[[cg-build]]
 == Building Jetty
 
 Jetty's uses http://maven.apache.org/[Apache Maven] for builds.
 To successfully build the project, you will also need a recent version of the https://www.oracle.com/java/technologies/downloads/[Java Development Kit (JDK)].
 
-[[cg-maven-jdk-requirements]]
+[[cg-build-requirements]]
 === Maven and JDK requirements
 
 Here are the minimum Maven and JDK version build requirements for each actively maintained branch.
 
 .Build versioning requirements by branch
-[cols="4"]
 |===
-| Branch | Maven Version | Minimum JDK | Recommended JDK
+| Branch | Maven Version | Minimum JDK
 
-| jetty-10.0.x | Maven 3.8.6+  | OpenJDK 11  | OpenJDK 17 (for optional virtual threads and HTTP/3 support)
-| jetty-11.0.x | Maven 3.8.6+  | OpenJDK 11  | OpenJDK 17 (for optional virtual threads and HTTP/3 support)
-| jetty-12.0.x | Maven 3.8.6+  | OpenJDK 17  | OpenJDK 17
+| jetty-12.0.x | Maven 3.8.6+  | OpenJDK 17+
+| jetty-11.0.x | Maven 3.8.6+  | OpenJDK 11+
+| jetty-10.0.x | Maven 3.8.6+  | OpenJDK 11+
 |===
 
-[[cg-fast-build]]
+To build the Jetty documentation, OpenJDK 19+ is required due to the use of the virtual thread APIs.
+
+[[cg-build-fast]]
 === Running a fast build
 
 To get started with Jetty as quickly as possible, navigate to your local copy of the Jetty repo and run:
@@ -44,20 +45,25 @@ mvn -Pfast clean install
 
 The `-Pfast` flag tells Maven to bypass running tests and other checks.
 
-[[cg-full-build]]
+[[cg-build-full]]
 === Running a full build
 
 To build Jetty and automatically run all tests, run:
 
 [source, shell]
 ----
-mvn install
+mvn clean install
 ----
 
 The full build takes substantial time and memory, as it runs hundreds of test cases -- many of which spin up embedded instances of Jetty itself.
 
 The build also runs stress tests that may require you (depending on your hardware or operating system) to set you file descriptor limit to a value greater than 2048.
-You can view or set your file descriptor limit by running `ulimit -n [new_value]`.
+You can view or set your file descriptor limit by running:
+
+[source, shell]
+----
+$ ulimit -n [new_value]
+----
 
 [TIP]
 .Flagging flaky tests
@@ -66,7 +72,7 @@ Not all test cases are as timing independent as they should be, which can result
 You can help us track these flaky tests by opening an https://github.com/eclipse/jetty.project/issues[issue] when you come across one.
 ====
 
-[[cg-parallel-execution]]
+[[cg-build-parallel]]
 === Executing tests in parallel
 
 Jetty uses https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution[Junit5's parallel execution] to run test cases in parallel.
@@ -95,25 +101,25 @@ Certain tests cannot be run in parallel because they access or modify  `static`
 Maven will run these tests in isolation even when parallel execution is explicitly enabled.
 ====
 
-[[cg-option-build-tools]]
+[[cg-build-optional-tools]]
 === Optional build tools
 
-* https://graphviz.org/[Graphviz]: used by Asciidoctor in the `jetty-documentation` module to produce various graphs. See <<cg-documentation>> for more information.
+* https://graphviz.org/[Graphviz]: used by Asciidoctor in the `jetty-documentation` module to produce various link:https://plantuml.com/[PlantUML] graphs.
 * https://www.docker.com/[Docker]: used to run some integration tests for testing third party integrations.
 
 [[cg-build-artifacts]]
 === Build artifacts
 
 Once the build is complete, you can find the built Jetty Maven artifacts in your Maven local repository, along with the following locations of note:
 
-[cols="3"]
+[cols="1a,2a,2a"]
 |===
 | Branch(es)     | Location | Description
 
 | all            | `jetty-home/target/jetty-home-<ver>.tar.gz`  | The Jetty Home distribution
-| `jetty-10.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner distribution
-| `jetty-11.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner distribution
 | `jetty-12.0.x` | `jetty-ee10/jetty-ee10-runner/target/jetty-ee10-runner-<ver>.jar` | The Jetty Runner distribution for EE10/Servlet 6 (`jakarta.servlet`) webapps
 | `jetty-12.0.x` | `jetty-ee9/jetty-ee9-runner/target/jetty-ee9-runner-<ver>.jar`    | The Jetty Runner distribution for EE9/Servlet 5 (`jakarta.servlet`) webapps
 | `jetty-12.0.x` | `jetty-ee8/jetty-ee8-runner/target/jetty-ee8-runner-<ver>.jar`    | The Jetty Runner distribution for EE8/Servlet 4 (`javax.servlet`) webapps
+| `jetty-11.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner distribution for EE9/Servlet 5 (`jakarta.servlet`) webapps
+| `jetty-10.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner distribution for EE8/Servlet 4 (`javax.servlet`) webapps
 |===