Improvements to the contribution guide.
Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
ecf8795aef
commit
e71fa6dedd
|
|
@ -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.
|
||||
|
|
|
|||
41
README.md
41
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, "/");
|
||||
context.addServlet(MyServlet.class, "/*");
|
||||
server.setHandler(new MyHandler());
|
||||
server.start();
|
||||
```
|
||||
|
||||
Documentation
|
||||
=============
|
||||
## Embedded Servlet Example
|
||||
|
||||
```java
|
||||
Server server = new Server(port);
|
||||
ServletContextHandler context = new ServletContextHandler("/");
|
||||
context.addServlet(MyServlet.class, "/*");
|
||||
server.setHandler(context);
|
||||
server.start();
|
||||
```
|
||||
|
||||
# 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).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
:ee-all: ee{8,9,10}
|
||||
:ee-current: ee10
|
||||
:ee-current-caps: EE 10
|
||||
:experimental:
|
||||
:imagesdir: images
|
||||
|
|
@ -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].
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 <<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]]
|
||||
|
|
@ -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-<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
|
||||
|===
|
||||
|
|
|
|||
|
|
@ -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())`.
|
||||
====
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<<og-intro,Operations Guide>>::
|
||||
Operations Guide::
|
||||
Targets sysops, devops, and developers who want to run Jetty as a standalone web server.
|
||||
|
||||
<<pg-intro,Programming Guide>>::
|
||||
Programming Guide::
|
||||
Targets developers who want to use the Jetty libraries in their applications.
|
||||
|
||||
<<cg-intro,Contribution Guide>>::
|
||||
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 <<cg-building-jetty,build the Jetty codebase>>, 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 <<cg-getting-source,check out a local copy>> 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 <<cg-documentation-guides,documentation guides>>.
|
||||
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 <<cg-documentation-guides,documentation guide>>.
|
||||
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/<format>`::
|
||||
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]` <<cg-admonitions,admonition>> 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:
|
||||
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}`):
|
||||
|
||||
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:
|
||||
|
||||
[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.
|
||||
|
|
|
|||
|
|
@ -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 <<cg-eca,sign the Eclipse Contributor Agreement>>.
|
||||
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 #<XXX> <description of the commit>*:
|
||||
Specifically, the message should follow the form *Issue #<NNN> <description of the commit>*:
|
||||
|
||||
[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.*
|
||||
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`).
|
||||
|
||||
|
||||
[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
|
||||
----
|
||||
====
|
||||
|
||||
[[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.
|
||||
|
|
|
|||
|
|
@ -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].
|
||||
|
|
|
|||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue