diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fbfe94f1927..e608f16119a1 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 66d4a36778e0..5b3c942d1b96 100644 --- a/README.md +++ b/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). diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/.asciidoctorconfig b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/.asciidoctorconfig new file mode 100644 index 000000000000..c2c64317ae73 --- /dev/null +++ b/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 diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/1-introduction.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/1-introduction.adoc index 817dca276c95..715b1387507e 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/1-introduction.adoc +++ b/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 <> or posting your question to <>. -==== - 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]. + diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/2-eca.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/2-eca.adoc index b3867b533691..2a37c0a4d7ae 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/2-eca.adoc +++ b/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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/3-source.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/3-source.adoc index 1ab32a2adada..e7517c6c6bcf 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/3-source.adoc +++ b/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. diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/4-build.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/4-build.adoc index e536814c0459..4bb9e18a6b47 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/4-build.adoc +++ b/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,10 +101,10 @@ 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 <> 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]] @@ -106,14 +112,14 @@ Maven will run these tests in isolation even when parallel execution is explicit 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-.tar.gz` | The Jetty Home distribution -| `jetty-10.0.x` | `jetty-runner/target/jetty-runner-.jar` | The Jetty Runner distribution -| `jetty-11.0.x` | `jetty-runner/target/jetty-runner-.jar` | The Jetty Runner distribution | `jetty-12.0.x` | `jetty-ee10/jetty-ee10-runner/target/jetty-ee10-runner-.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-.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-.jar` | The Jetty Runner distribution for EE8/Servlet 4 (`javax.servlet`) webapps +| `jetty-11.0.x` | `jetty-runner/target/jetty-runner-.jar` | The Jetty Runner distribution for EE9/Servlet 5 (`jakarta.servlet`) webapps +| `jetty-10.0.x` | `jetty-runner/target/jetty-runner-.jar` | The Jetty Runner distribution for EE8/Servlet 4 (`javax.servlet`) webapps |=== diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/5-code-standards.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/5-code-standards.adoc index cb17ac422df2..d4087f84e01f 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/5-code-standards.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/5-code-standards.adoc @@ -15,7 +15,7 @@ == Code Standards This section outlines the various coding conventions and standards we use throughout the Jetty codebase. -[[cg-ide-configuration]] +[[cg-code-standards-ide]] === Configuring your IDE IntelliJ IDE:: @@ -28,41 +28,38 @@ Eclipse IDE:: An Eclipse code style XML file is available in the source repo at https://github.com/eclipse/jetty.project/blob/jetty-10.0.x/build-resources/jetty-codestyle-eclipse-ide.xml[`/build-resources/jetty-codestyle-eclipse-ide.xml`]. -[[cg-java-conventions]] +[[cg-code-standards-java]] === Java conventions The following code sample shows some basic Java styles and conventions used throughout the Jetty codebase: [source, java] ---- - import some.exact.ClassName; // GOOD import some.wildcard.package.*; // BAD! package org.always.have.a.package; -/* --------------------------------------------------------- */ -/** All classes should have a javadoc +/** + * All classes should have a javadoc */ class MyClassName { // Use 4 spaces to indent. // The code must format OK with default tab size of 8. - private static final int ALL_CAPS_FOR_PUBLIC_CONSTANTS=1; + private static final int ALL_CAPS_FOR_PUBLIC_CONSTANTS = 1; - // Prefix static fields with two underscores (__) - // and normal fields with one underscore (_). This + // Prefix fields with one underscore (_). This // convention is not mandatory, but the chosen style // should be used consistently within a single class. - private static String __staticField; private Object _privateField; - // Use getters and setters rather than public fields. + // Braces always on new line. public void setPrivateField(Object privateField) { - _privateField=privateField; + _privateField = privateField; } public Object getPrivateField() @@ -70,20 +67,19 @@ class MyClassName return _privateField; } - public void doSomething() - throws SomeException + public void doSomething() throws SomeException { Object local_variable = _privateField; - if (local_variable==null) + // Braces always on new line. + if (local_variable == null) { // do Something } } } - ---- -[[cg-logging-conventions]] +[[cg-code-standards-logging]] === Logging conventions When deciding when and what to log, bear in mind a few things: @@ -92,48 +88,46 @@ When deciding when and what to log, bear in mind a few things: * Avoid polluting the log with very long stack traces. * Don't routinely produce logging events in response to data sent by a user. * Only call one `LOG` method for a given event, to avoid generating confusingly interleaved log messages. -* Never call `LOG.warn()` right before throwing an exception, as this will result in double handling. +* Never call `LOG.warn()` right before throwing an exception, as this will likely result in double logging the exception. * Avoid calling `LOG.debug()` right before throwing an exception, as this will make debug logs verbose while adding little information. -* When interacting with a request or other client-provided data, *do not log* unless `LOG.isDebugEnabled()` is true, and then use `DEBUG`-level logging: - +* When interacting with a request or other client-provided data that result in an exception, use `DEBUG`-level logging: ++ [source, java] ---- - catch (Throwable t) - { - if (LOG.isDebugEnabled()) - LOG.debug("Something happened {} {} {}",x, y, z, t); - } +catch (Throwable t) +{ + if (LOG.isDebugEnabled()) + LOG.debug("Something happened {} {} {}",x, y, z, t); +} ---- - * When calling into application code that throws an exception, use `INFO`-level logging, and gate the log with `LOG.isDebugEnabled()` to reduce the size of logging stack traces: - ++ [source, java] ---- - catch (Throwable t) - { +catch (Throwable t) +{ if (LOG.isDebugEnabled()) - LOG.info("Something happened {} {} {}", x, y, z, t); + LOG.info("Something happened {} {} {}", x, y, z, t); else - LOG.info("Something happened {} {} {} {}", x, y, z, t.toString()); - } + LOG.info("Something happened {} {} {} {}", x, y, z, t.toString()); +} ---- - -* When exceptions happen in Jetty code: -** Mostly use the `WARN` or `ERROR` level. -** If the exception is (1) not entirely unexpected, (2) can happen relatively frequently, or (3) can potentially have a very long stack trace, you can use `LOG.isDebugEnabled()` to cut down on the size of the logging of the stacktrace: +* When exceptions happen in Jetty code, and if the exception is (1) not entirely unexpected, (2) can happen relatively frequently, or (3) can potentially have a very long stack trace, you can use `LOG.isDebugEnabled()` to cut down on the size of the logging of the stacktrace: ++ [source, java] ---- - catch (Throwable t) - { +catch (Throwable t) +{ if (LOG.isDebugEnabled()) - LOG.warn("Something happened {} {} {}", x, y, z, t); + LOG.warn("Something happened {} {} {}", x, y, z, t); else - LOG.warn("Something happened {} {} {} {}", x, y, z, t.toString()); - } + LOG.warn("Something happened {} {} {} {}", x, y, z, t.toString()); +} ---- [TIP] ==== By default, Jetty's logger outputs a full stacktrace whether you call it like `LOG.warn("Something happened", t)` or `LOG.warn("Something happened {}", t)`. -If you only want the log message, you need to do call `.toString()` on the caught exception, e.g., `LOG.warn("Something happened {}", t.toString())`. + +If you only want the log message but not the stack trace, you need to do call `.toString()` on the caught exception, e.g., `LOG.warn("Something happened {}", t.toString())`. ==== diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/6-documentation.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/6-documentation.adoc index d6243174914e..6149d73514fd 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/6-documentation.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/6-documentation.adoc @@ -20,21 +20,21 @@ Another great way to contribute to Jetty is to help us write and maintain our do === Documentation guides Jetty's documentation is grouped into three guides, each written for a different target audience. -<>:: +Operations Guide:: Targets sysops, devops, and developers who want to run Jetty as a standalone web server. -<>:: +Programming Guide:: Targets developers who want to use the Jetty libraries in their applications. -<>:: +Contribution Guide:: Targets developers and writers who want to make contributions to the Jetty project. -[[cg-doc-toolchain]] +[[cg-documentation-toolchain]] === The documentation toolchain Jetty follows a https://www.writethedocs.org/guide/docs-as-code/["docs as code"] philosophy, meaning *we use the same tools to write and build our code and docs*. As such, the docs are maintained directly within the Jetty codebase at https://github.com/eclipse/jetty.project/tree/jetty-12.0.x/documentation/jetty-documentation/src/main/asciidoc[`documentation/jetty-documentation/src/main/asciidoc/`]. -[[cg-asciidoc]] +[[cg-documentation-asciidoc]] ==== AsciiDoc Our docs are written in https://asciidoc.org/[AsciiDoc], a markup language for writing technical content. AsciiDoc supports many advanced features, such as robust linking across different documentation sets, while remaining human-readable. @@ -42,23 +42,23 @@ AsciiDoc supports many advanced features, such as robust linking across differen Although Jetty takes advantage of many of these features, you don't need to be an AsciiDoc expert to contribute to our documentation. If you _are_ interested in learning the ins and outs of AsciiDoc, the https://docs.asciidoctor.org/asciidoc/latest/[official language documentation] is a good place to start. -[[cg-maven-asciidoctor]] +[[cg-documentation-asciidoctor]] ==== Maven and Asciidoctor -In addition to using Maven to <>, we use it to build our docs. +In addition to using Maven to xref:cg-build[build the Jetty codebase], we use it to build our docs. During a build, Maven converts AsciiDoc-formatted docs into the HTML pages that you are reading right now. https://asciidoctor.org/[Asciidoctor] is the tool that actually performs this compilation step. -Maven integrates with Asciidoctor via a plugin called (appropriately enough) https://docs.asciidoctor.org/maven-tools/latest/[`asciidoctor-maven-plugin`]. +Maven integrates with Asciidoctor via the https://docs.asciidoctor.org/maven-tools/latest/[`asciidoctor-maven-plugin`]. [[cg-documentation-build]] === Building the docs -Since Jetty's docs are maintained in git alongside the rest of the Jetty codebase, you'll need to <> of the code to contribute to the docs. +Since Jetty's docs are maintained in `git` alongside the rest of the Jetty codebase, you'll need to xref:cg-source[check out a local copy] of the code to contribute to the docs. The docs are maintained as a separate module within Jetty, which means you can build the docs separately from the rest of the project. -To do so, run `mvn install` from the `documentation/jetty-documentation` subdirectory. +To do so, run `mvn clean install` from the `documentation/jetty-documentation` subdirectory. -[source, screen] +[source, shell] ---- $ cd jetty.project/documentation $ mvn install @@ -80,8 +80,7 @@ This is Maven setting up the execution environment, which it uses to generate th When the build completes, you can view the generated docs in your preferred web browser by opening file:///path/to/jetty.project/documentation/jetty-documentation/target/html/index.html on your local filesystem. - -[[cg-documentation-structure]] +[[cg-documentation-build-structure]] ==== Documentation project structure The documentation root is https://github.com/eclipse/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation[`documentation/jetty-documentation/`]. @@ -91,11 +90,11 @@ https://github.com/eclipse/jetty.project/tree/jetty-10.0.x/documentation/jetty-d The primary root for all documentation content. https://github.com/eclipse/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation/src/main/asciidoc/config.adoc[`src/main/asciidoc/config.adoc`]:: -This file contains metadata and global variables shared across all the <>. +This file contains metadata and global variables shared across all the xref:cg-documentation-guides[documentation guides]. This configuration is used by Asciidoctor to correctly render the final docs. `src/main/asciidoc/*-guide`:: -Secondary root directories for each individual <>. +Secondary root directories for each individual xref:cg-documentation-guides[documentation guide]. `src/main/asciidoc/*-guide/index.adoc`:: Asciidoctor's "point of entry" for each guide. @@ -105,16 +104,15 @@ Also, guide-specific metadata and variables that wouldn't belong in the root `co `target/`:: The final build destination for any docs generated by Maven. By default, docs are generated into `target/html`, but other formats (e.g., `pdf` and `epub`) are available. -This directory is not checked into git. - +This directory is not checked into `git`. -[[cg-documentation-style-guide]] +[[cg-documentation-style]] === Style guide The following conventions are not set in stone, but you are encouraged to follow them where possible. Stylistically consistency helps keep the docs easy to both understand and maintain. -[[cg-ventilated-prose]] +[[cg-documentation-style-prose]] ==== Ventilated prose In markup, *each sentence should be on its own line with a hard return at the end of the line*. @@ -127,56 +125,38 @@ This practice makes for more readable file diffs, and also makes it easier to co AsciiDoc treats a single line breaks just like a space, so it will render ventilated prose naturally. ==== -[[cg-documenting-versions]] +[[cg-documentation-versions]] ==== Documenting versions -[[cg-documenting-version-changes]] -===== Documenting changes in functionality - -Use subsections to flag major changes in functionality between versions of Jetty. -The subsection's title should specifically note the relevant version(s) -- e.g., _Prior to: Version X.Y_ or _In version: X.Y_. - -For minor differences in functionality, a `[NOTE]` or `[WARNING]` <> may be sufficient. - - -[[cg-documenting-multiple-versions]] +[[cg-documentation-versions-multiple]] ===== Documenting multiple versions at once Jetty 12 features many parallel modules with similar names and functionality, but which target different versions of Jakarta EE. For instance, the `ee8-deploy`, `ee9-deploy`, and `ee10-deploy` modules all behave similarly, except they target Jakarta EE8, EE9, and EE10, respectively. Whenever possible, *try to consolidate these types of parallel references*. -For instance, you can quickly refer to all three of the aforementioned modules as a group by writing `ee{8,9,10}-deploy`, `eeN-deploy`, or even just `ee-deploy`. +For instance, you can quickly refer to all three of the aforementioned modules as a group by writing `{ee-all}-deploy` or `eeN-deploy`. Another approach is to write your docs targeting one specific module, and tell the reader what substitution(s) they would need to make to target a different module. [NOTE] ==== When targeting a specific version in your docs for demonstration purposes, you should prefer to use the most recent version number. -For the example above, this would mean targeting `ee10-deploy`. +For the example above, this would mean targeting `{ee-current}-deploy`. ==== Consolidating parallel references saves readers from having to sift through repetitive material, and helps us avoid maintaining multiple versions of nearly identical docs. -[[cg-documenting-versions-in-examples]] +[[cg-documentation-versions-multiple-example]] ===== Dealing with multiple versions in code examples -Instead of referencing multiple versions in your code and command-line examples, it's generally better to target one specific version. -For example, let's say you're telling the reader how to install the `ee-deploy` family of modules: - - java -jar $JETTY_HOME/start.jar --add-modules=ee-deploy - -Any reader who copy-pastes the above into their command line will get a failure: +Instead of referencing multiple versions in your code and command-line examples, it's generally better to target one specific version, typically the latest (currently `{ee-current}`): -[source,options=nowrap,subs=attributes] +[source,subs=attributes] ---- -include::jetty[args="--add-modules=ee-deploy"] +$ java -jar $JETTY_HOME/start.jar --add-modules={ee-current}-deploy ---- -Instead, target the `ee10-deploy` module specifically: - - java -jar $JETTY_HOME/start.jar --add-modules=ee10-deploy - This will work when copy-pasted into the command line. [NOTE] @@ -184,8 +164,8 @@ This will work when copy-pasted into the command line. You may want to remind the reader to change the `10` in the command to their preferred target version -- although doing so isn't strictly necessary for a simple example like above. ==== -[[cg-license-blocks]] -==== License blocks +[[cg-documentation-license]] +=== License blocks Each `.adoc` file should contain the license block that exists in the `index.adoc` file. For reference, here is a standard license header: @@ -204,10 +184,10 @@ For reference, here is a standard license header: // ---- -[[cg-asciidoc-conventions]] +[[cg-documentation-asciidoc-conventions]] === AsciiDoc conventions -[[cg-custom-ids]] +[[cg-documentation-asciidoc-conventions-ids]] ==== Custom IDs We rely heavily on https://docs.asciidoctor.org/asciidoc/latest/sections/custom-ids/[custom IDs] for generating stable documentation URLs and linking within docs. @@ -223,23 +203,21 @@ To help deal with this constraint, we used different ID prefixes in each guide: * Contribution Guide: `cg-` ==== - -[[cg-images]] +[[cg-documentation-asciidoc-conventions-images]] ==== Images Images should live in the `images/` directory of the guide they appear in. Use the `image::` directive to include an image, like so: ---- -image::small_powered_by.gif[image,width=340] +image::small_powered_by.gif[image,width=145] ---- -image::small_powered_by.gif[image,width=340] - +image::small_powered_by.gif[image,width=145] -[[cg-admonitions]] +[[cg-documentation-asciidoc-conventions-admonitions]] ==== Admonitions -Admonitions (a.k.a. "callout blocks") are useful for flagging information that doesn't belong in the natural flow of text. +Admonitions (or "callout blocks") are useful for flagging information that doesn't belong in the natural flow of text. Asciidoc supports five levels of admonition: * `[NOTE]` @@ -275,13 +253,3 @@ Places where you have to be careful what you are doing. Where extreme care has to be taken. Data corruption or other nasty things may occur if these warnings are ignored. ==== - -[cg-documentation-troubleshooting] -=== Troubleshooting - -Pay close attention to the build output for lines like: - - asciidoctor: WARNING: 9-jsp.adoc: line 0: id assigned to section already in use: ag-http2 - -This error indicates that a custom ID is being reused somewhere. -The ID conflict should be resolved, or else deep linking will work incorrectly. diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/7-submitting-patches.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/7-submitting-patches.adoc index ec6ce4c135cf..adcd0b6b99c6 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/7-submitting-patches.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/7-submitting-patches.adoc @@ -11,24 +11,24 @@ // ======================================================================== // -[[cg-submitting-patches]] +[[cg-patches]] == Submitting Patches We wholeheartedly welcome contributions to Jetty. While not every contribution will be accepted, our commitment is to work with interested parties on the things they care about. -[[cg-git-config]] -=== Configuring git +[[cg-patches-git-config]] +=== Configuring `git` -The email in your git commits must match the email you used to <>. +The email in your git commits must match the email you used to xref:cg-eca[sign the Eclipse Contributor Agreement]. As such, you'll likely want to configure `user.email` in git accordingly. See link:https://help.github.com/articles/setting-your-email-in-git[this guide] on GitHub for details on how to do so. -[[cg-commit-messages]] +[[cg-patches-git-commit-messages]] ==== Writing commit messages If your pull request addresses a particular issue in our repository, then the commit message should reference the issue. -Specifically, the message should follow the form *Issue # *: +Specifically, the message should follow the form *Issue # *: [source, shell] ---- @@ -37,38 +37,17 @@ $ git commit -s -m "Issue #123 resolving the issue by adding widget" Using this format will ensure that the commit will be included in `VERSIONS.txt` upon new releases of Jetty. - -[[cg-making-the-commit]] +[[cg-patches-git-commit-signing]] === Signing the commit -You must sign off on every commit in your pull request using git's https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff[signoff] feature (`git commit -s`). -Without this signoff, your patch will be automatically rejected before it can be incorporated into to the Jetty repository. -*There is nothing the Jetty committers can do to bypass this check.* - - -[NOTE] -.Why do my commits need the signoff flag if I already signed the ECA? -==== -By signing the ECA, you are indicating that you are free to contribute to Eclipse; however, that doesn't mean every line of code you ever write is subject to the agreement! -Signing off on your individual commits clearly indicates that you are submitting your code under the auspices of the ECA. -==== - -[TIP] -==== -If you made a commit but forgot to pass the `-s` flag, you can retroactively add a signoff by running: - -[source,shell] ----- -git commit --amend --signoff ----- -==== +You should sign off on every commit in your pull request using git's https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff[signoff] feature (`git commit -s`). -[[cg-pull-requests]] +[[cg-patches-pull-requests]] === Creating pull requests Please see https://help.github.com/articles/creating-a-pull-request[GitHub's documentation for creating pull requests]. -[[cg-time-frames]] +[[cg-patches-time-frames]] === Time frames We do our best to process contributions in a timely fashion. diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/8-security.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/8-security.adoc index b531e86a2d8d..307286592dcd 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/8-security.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/8-security.adoc @@ -17,11 +17,11 @@ There are a number of ways to report security issues to the Jetty project. * If the issue is directly related to Jetty itself then you are encouraged to report to the Jetty developers directly at mailto:security@webtide.com[security@webtide.com]. -Since Webtide comprises the active committers of the Jetty project, this is our preferred reporting method. +link:https://webtide.com[Webtide] employs the active committers of the Jetty project, so this is the preferred reporting method. [IMPORTANT] ==== -We prefer you report any security issues directly to the Jetty developers mailto:security@webtide.com[via email] rather than via GitHub Issues, as the latter https://github.com/isaacs/github/issues/37[does not support private issues]. +We prefer you report any security issues directly to the Jetty developers mailto:security@webtide.com[via email] rather than via GitHub Issues, as GitHub https://github.com/isaacs/github/issues/37[does not support private issues]. ==== * If the issue is related to Eclipse or its Jetty integration then we encourage you to reach out to mailto:security@eclipse.org[security@eclipse.org]. diff --git a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/index.adoc b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/index.adoc index 986bd9830241..b3b1fecf23da 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/index.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/contribution-guide/index.adoc @@ -11,13 +11,14 @@ // ======================================================================== // -include::../config.adoc[] :doctitle: link:https://eclipse.org/jetty[Eclipse Jetty]: Contribution Guide :toc-title: Contribution Guide :idprefix: cg- :breadcrumb: Home:../index.html | Contribution Guide:./index.html :toclevels: 3 +include::../config.adoc[] +include::.asciidoctorconfig[] include::1-introduction.adoc[] include::2-eca.adoc[] include::3-source.adoc[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc index c00060e50937..4d7b4f3250e0 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc @@ -11,12 +11,12 @@ // ======================================================================== // -include::../config.adoc[] :doctitle: link:https://eclipse.dev/jetty[Eclipse Jetty]: Operations Guide :toc-title: Operations Guide :idprefix: og- :docinfo: private-head +include::../config.adoc[] include::.asciidoctorconfig[] include::introduction.adoc[] include::begin/chapter.adoc[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc index c21cc1f7a488..b1bdbd02d021 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc @@ -11,12 +11,12 @@ // ======================================================================== // -include::../config.adoc[] -:doctitle: link:https://eclipse.org/jetty[Eclipse Jetty]: Programming Guide +:doctitle: link:https://eclipse.dev/jetty[Eclipse Jetty]: Programming Guide :toc-title: Programming Guide :idprefix: pg- :docinfo: private-head +include::../config.adoc[] include::.asciidoctorconfig[] include::introduction.adoc[] include::client/client.adoc[] diff --git a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-jspc-maven-plugin.adoc b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-jspc-maven-plugin.adoc index f8536ac5e873..384eeb921fe2 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-jspc-maven-plugin.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/programming-guide/maven/jetty-jspc-maven-plugin.adoc @@ -14,7 +14,7 @@ [[jetty-jspc-maven-plugin]] === Jetty Jspc Maven Plugin -This plugin will help you pre-compile your jspc and works in conjunction with the Maven war plugin to put them inside an assembled war. +This plugin will help you pre-compile your JSP and works in conjunction with the Maven war plugin to put them inside an assembled war. [[jspc-config]] ==== Configuration