Cleanup Jetty Contribution Guide
Signed-off-by: Greg Poulos <eclipse@gregpoulos.com>
This commit is contained in:
Greg Poulos
Simone Bordet
parent
6cefe64a22
commit
02fc4392cc
|
|
@ -1,62 +1,33 @@
|
|||
Contributing to Jetty
|
||||
=====================
|
||||
Thank you for your interest in this project!
|
||||
|
||||
Project description
|
||||
--------------------
|
||||
Jetty is a lightweight highly scalable java based web server and servlet engine.
|
||||
Our goal is to support web protocols like HTTP, HTTP/2, and WebSocket 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 async web server that has a long history as a component oriented technology easily embedded into applications while still offering a solid traditional distribution for webapp deployment.
|
||||
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.
|
||||
|
||||
- [https://projects.eclipse.org/projects/rt.jetty](https://projects.eclipse.org/projects/rt.jetty)
|
||||
Here are some quick links to other useful resources:
|
||||
|
||||
Developer resources
|
||||
--------------------
|
||||
Information regarding source code management, builds, coding standards, and more.
|
||||
* [**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.
|
||||
|
||||
* [**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.
|
||||
|
||||
- [https://eclipse.dev/jetty/documentation/](https://eclipse.dev/jetty/documentation/)
|
||||
|
||||
The canonical Jetty git repository is located at [GitHub.](https://github.com/eclipse/jetty.project) Providing you have
|
||||
completed the contributors agreement mentioned below we will endeavor to pull your commit into Jetty proper.
|
||||
|
||||
Eclipse Contributor Agreement
|
||||
------------------------------
|
||||
Before your contribution can be accepted by the project, you need to create and electronically sign a [Eclipse Contributor Agreement (ECA)](http://www.eclipse.org/legal/ecafaq.php):
|
||||
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. Log in to the [Eclipse foundation website](https://accounts.eclipse.org/user/login/). You will need to
|
||||
create an account with the Eclipse Foundation if you have not already done so.
|
||||
2. Click on "Eclipse ECA", and complete the form.
|
||||
1. Create an account on the [Eclipse foundation website](https://accounts.eclipse.org/user/login/) if you have not already done so.
|
||||
2. Log into your account, click **Eclipse Contributor Agreement**, and complete the form.
|
||||
|
||||
Be sure to use the same email address in your Eclipse account that you intend to use when you commit to GitHub.
|
||||
All committers, and all commits , are bound to the [Developer Certificate of Origin.](https://www.eclipse.org/legal/DCO.php)
|
||||
As such, all parties involved in a contribution must have valid ECAs and commits must include [valid "Signed-off-by" entries.](https://wiki.eclipse.org/Development_Resources/Contributing_via_Git)
|
||||
Commits can be signed off by included the `-s` attribute in your commit message, for example, `git commit -s -am 'Interesting Commit Message.`
|
||||
|
||||
|
||||
Contact
|
||||
--------
|
||||
Contact the project developers via the project's "dev" list.
|
||||
|
||||
- [https://dev.eclipse.org/mailman/listinfo/jetty-dev](https://dev.eclipse.org/mailman/listinfo/jetty-dev)
|
||||
|
||||
Search for bugs
|
||||
----------------
|
||||
This project uses GitHub Issues to track ongoing development and issues.
|
||||
|
||||
- [https://github.com/eclipse/jetty.project/issues](https://github.com/eclipse/jetty.project/issues)
|
||||
|
||||
Create a new bug
|
||||
-----------------
|
||||
Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!
|
||||
|
||||
- [https://github.com/eclipse/jetty.project/issues](https://github.com/eclipse/jetty.project/issues)
|
||||
|
||||
Reporting Security Issues
|
||||
-----------------
|
||||
There are a number of avenues for reporting security issues to the Jetty project available.
|
||||
If the issue is directly related to Jetty itself then reporting to the Jetty developers is encouraged.
|
||||
The most direct method is to mail [security@webtide.com](mailto:security@webtide.com).
|
||||
Webtide is comprised of the active committers of the Jetty project is our preferred reporting method.
|
||||
We are flexible in how we work with reporters of security issues but we reserve the right to act in the interests of the Jetty project in all circumstances.
|
||||
-------------------------
|
||||
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).
|
||||
|
||||
If the issue is related to Eclipse or its Jetty integration then we encourage you to reach out to [security@eclipse.org](mailto:security@eclipse.org).
|
||||
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.
|
||||
|
||||
If the issue is related to Eclipse or its Jetty integration, then we encourage you to reach out to the Eclipse Foundation directly at [security@eclipse.org](mailto:security@eclipse.org).
|
||||
|
|
|
|||
94
README.md
94
README.md
|
|
@ -1,14 +1,5 @@
|
|||
# Eclipse Jetty Canonical Repository
|
||||
|
||||
This is the canonical repository for the Eclipse Jetty project, feel free to fork and contribute now!
|
||||
|
||||
Submitting a patch or pull request?
|
||||
|
||||
Make sure you have an Eclipse Contributor Agreement (ECA) on file.
|
||||
|
||||
- [eclipse.org/legal/ecafaq](https://www.eclipse.org/legal/ecafaq.php)
|
||||
|
||||
## Project description
|
||||
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.
|
||||
|
|
@ -16,7 +7,8 @@ Jetty is a modern fully asynchronous web server that has a long history as a com
|
|||
|
||||
- [https://projects.eclipse.org/projects/rt.jetty](https://projects.eclipse.org/projects/rt.jetty)
|
||||
|
||||
## Webapp Example
|
||||
Webapp Example
|
||||
--------------
|
||||
|
||||
```shell
|
||||
$ mkdir base && cd base
|
||||
|
|
@ -25,7 +17,8 @@ $ 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
|
||||
|
|
@ -36,7 +29,8 @@ $ echo environment: ee8 > webapps/mywebapp8.properties
|
|||
$ java -jar $JETTY_HOME/start.jar
|
||||
```
|
||||
|
||||
## Embedded Example
|
||||
Embedded Example
|
||||
----------------
|
||||
|
||||
```java
|
||||
Server server = new Server(port);
|
||||
|
|
@ -45,74 +39,20 @@ context.addServlet(MyServlet.class, "/*");
|
|||
server.start();
|
||||
```
|
||||
|
||||
## Documentation
|
||||
Documentation
|
||||
=============
|
||||
|
||||
Project documentation is available on the Eclipse Jetty website.
|
||||
[Jetty's documentation](https://eclipse.dev/jetty/documentation) is available on the Eclipse Jetty website.
|
||||
|
||||
- [https://eclipse.dev/jetty/documentation/](https://eclipse.dev/jetty/documentation/)
|
||||
The documentation is divided into three guides, based on use case:
|
||||
|
||||
# Building
|
||||
* The [Operations Guide](https://eclipse.dev/jetty/documentation/jetty-12/operations-guide/index.html) targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications.
|
||||
|
||||
[Apache Maven](https://maven.apache.org/) and [OpenJDK](https://adoptium.net/) requirements:
|
||||
* The [Programming Guide](https://eclipse.dev/jetty/documentation/jetty-11/programming-guide/index.html) targets developers who want to use the Eclipse Jetty libraries in their applications, and advanced sysops/devops that want to customize the deployment of web applications.
|
||||
|
||||
| Branch | Maven Version | Minimum JDK | Recommended 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 |
|
||||
* 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.
|
||||
|
||||
## Full Build
|
||||
|
||||
If you want to build Jetty and run all the tests, which may takes quite some time, use the following command:
|
||||
|
||||
``` shell
|
||||
mvn clean install
|
||||
```
|
||||
|
||||
Note: There are stress tests that on some hardware or operative system require to set the file descriptor limit to a value greater than 2048 to pass successfully (check your `ulimit -n` value).
|
||||
|
||||
Note: The tests are running in parallel using [Junit5 parallel execution](https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution).
|
||||
This is configurable using the following properties:
|
||||
|
||||
```
|
||||
# to enable/disable the parallel execution
|
||||
-Djunit.jupiter.execution.parallel.enabled=true/false
|
||||
# number of tests executed in parallel
|
||||
-Djunit.jupiter.execution.parallel.config.fixed.parallelism=2
|
||||
```
|
||||
|
||||
If a test cannot be run in parallel because it accesses/modifies some `static` fields or for any other reasons, the test should be marked with the annotation:
|
||||
|
||||
```java
|
||||
@Isolated("Access static field of Configurations")
|
||||
```
|
||||
|
||||
## Fast Build
|
||||
|
||||
If you just need the Jetty module jars and the Jetty Home distribution, you can run a fast build that does not run tests and other checks with the following command:
|
||||
|
||||
``` shell
|
||||
mvn -Pfast clean install
|
||||
```
|
||||
|
||||
## Optional Build Tools
|
||||
|
||||
* [`graphviz`](https://graphviz.org/) - used by asciidoctor in the jetty-documentation module to produce various graphs
|
||||
* [`Docker`](https://www.docker.com/) - used to run some integration tests for testing third party integrations
|
||||
|
||||
## 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:
|
||||
|
||||
| Branches | 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 |
|
||||
|
||||
# Commercial Support
|
||||
|
||||
Commercial Support
|
||||
==================
|
||||
Expert advice and production support of Jetty are provided by [Webtide](https://webtide.com).
|
||||
|
|
|
|||
|
|
@ -28,6 +28,8 @@
|
|||
// Use fonts for admonitions.
|
||||
:icons: font
|
||||
|
||||
:imagesdir: images/
|
||||
|
||||
// HTML specific directives
|
||||
ifdef::backend-html5[]
|
||||
:safe-mode-unsafe:
|
||||
|
|
|
|||
|
|
@ -11,9 +11,45 @@
|
|||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-introduction]]
|
||||
== Welcome!
|
||||
[[cg-intro]]
|
||||
== Introduction
|
||||
|
||||
Eclipse Jetty is an open source project with a long pedigree of contribution.
|
||||
Starting over 20 years ago, Jetty has had many committers over the years and owes much of its success to the people that make up the community.
|
||||
There are many ways that you may contribute to Jetty, and the goal of this guide is help you get there!
|
||||
The Eclipse Jetty Contribution Guide targets developers and writers who want to make contributions to the Jetty project, whether it's through direct code and documentation contributions or by actively engaging in the larger community.
|
||||
|
||||
[[cg-mailing-lists]]
|
||||
=== Mailing Lists
|
||||
|
||||
One of the easiest ways to get involved is via our mailing lists:
|
||||
|
||||
* https://accounts.eclipse.org/mailing-list/jetty-users[Jetty Users] is for discussion and questions that are of broad interest to the community of Jetty users. (https://www.eclipse.org/lists/jetty-users[Archives])
|
||||
* https://accounts.eclipse.org/mailing-list/jetty-dev[Jetty Developers] is more narrowly focused on technical topics and discussion regarding Jetty internals. (https://www.eclipse.org/lists/jetty-dev[Archives])
|
||||
* https://accounts.eclipse.org/mailing-list/jetty-announce[Jetty Announcements] is for announcements about new releases and other updates from the project's maintainers. (https://www.eclipse.org/lists/jetty-announce[Archives])
|
||||
|
||||
|
||||
[[cg-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]]
|
||||
=== Filing Issues
|
||||
|
||||
The Jetty project uses GitHub for https://github.com/eclipse/jetty.project/issues[tracking issues].
|
||||
The issue tracker is a good place to flag potential bugs or suggest new Jetty features.
|
||||
|
||||
:icons: font
|
||||
[WARNING]
|
||||
====
|
||||
Note that the issue tracker is **not** designed to be a standard support channel.
|
||||
For individualized help, you'll have better success using 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]]
|
||||
=== Help Wanted
|
||||
If you want to contribute to Jetty but don't have a specific task or goal in mind, consider looking through our backlog of https://github.com/eclipse/jetty.project/issues?q=is%3Aopen+is%3Aissue+label%3A%22Help+Wanted%22[Help Wanted] issues. These tasks range from the simple to the complex, but they're all issues we've identified as being particularly well-suited for new contributors to tackle.
|
||||
|
|
|
|||
|
|
@ -1,56 +0,0 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-community]]
|
||||
== Participate in the Community
|
||||
|
||||
One of the best ways to start contribute and work with Eclipse Jetty is to get plugged into one of the existing communities.
|
||||
In any one of these you will come across users of neophyte to expert experience and as time permits the developers of Jetty themselves.
|
||||
|
||||
[[cg-mailing-lists]]
|
||||
=== Mailing Lists
|
||||
|
||||
Mailing lists are a wonderful way to interact with the community at large and for a certain class of issue have the best chances of achieving resolution. There are a number of mailing lists available within the Jetty project and a good rule of thumb to choose between the developer and user lists is to ask yourself if your question is broadly interesting to the community, use the users list and if narrowly focused on Jetty internals or minutiae, then the dev list might be a better option.
|
||||
|
||||
* Jetty Developers List
|
||||
** Join - https://dev.eclipse.org/mailman/listinfo/jetty-dev
|
||||
** Archives - http://dev.eclipse.org/mhonarc/lists/jetty-dev/
|
||||
* Jetty Users List
|
||||
** Join - https://dev.eclipse.org/mailman/listinfo/jetty-users
|
||||
** Archives - http://dev.eclipse.org/mhonarc/lists/jetty-users/
|
||||
* Jetty Announcements List
|
||||
** Join - https://dev.eclipse.org/mailman/listinfo/jetty-announce
|
||||
** Archives - http://dev.eclipse.org/mhonarc/lists/jetty-announce/
|
||||
|
||||
[[cg-stackoverflow]]
|
||||
=== Stack Overflow
|
||||
|
||||
From a simple support perspective it is hard to beat http://stackoverflow.com[StackOverflow] for interacting with a Jetty community. Numerous users have asked and had answered their questions on the platform by other users and developers alike.
|
||||
|
||||
* Check out the general https://stackoverflow.com/questions/tagged/jetty[Jetty] tag!
|
||||
* The https://stackoverflow.com/questions/tagged/embedded-jetty[Embedded-Jetty] tag has a fair amount of traffic as well.
|
||||
|
||||
[[cg-issues]]
|
||||
=== Github: Issues and Features
|
||||
|
||||
While not necessarily a support channel for solving a specific user problem, the issue tracker for Eclipse Jetty is a great location for addressing issues or suggesting features you want to see (or ideally contribute) in Jetty.
|
||||
|
||||
When you file a Github Issue in the Eclipse Jetty project there are a number of *labels* available and we encourage to you use them appropriately.
|
||||
|
||||
* http://github.com/eclipse/jetty.project[Issues at Github].
|
||||
|
||||
We have additionally identified and labeled a number of issues that may be appropriate for users of different levels of expertise that might want to contribute to Jetty but not have a specific goal or issue in mind.
|
||||
|
||||
* https://github.com/eclipse/jetty.project/issues?q=is%3Aopen+is%3Aissue+label%3A%22Help+Wanted%22[Help Wanted]
|
||||
|
||||
Long story short, if you are interested in getting involved with the community, there are a number of options available and you are encouraged to participate at whatever level you like!
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-eca]]
|
||||
== The Eclipse Contributor Agreement
|
||||
|
||||
Since Jetty is a member of the Eclipse Foundation, all contributors must first sign the https://www.eclipse.org/legal/ECA.php[Eclipse Contributor Agreement (ECA)] before their code changes can be merged into source.
|
||||
|
||||
The Eclipse Foundation maintains an http://www.eclipse.org/legal/ecafaq.php[ECA FAQ] with more information about the ECA's provisions, and a http://wiki.eclipse.org/Development_Resources/Contributing_via_Git[wiki page] about contributing changes to any Eclipse Foundation project more generally.
|
||||
|
||||
Before you set up your local development environment, we recommend creating an account at https://accounts.eclipse.org/user[eclipse.org] and submitting your signed ECA.
|
||||
|
||||
[IMPORTANT]
|
||||
.Make sure your emails match
|
||||
====
|
||||
The email address you use to sign the ECA **must be the same** as the email you use to sign your git commits.
|
||||
====
|
||||
|
||||
Jetty's build process has a git hook to verify that every incoming pull request is signed with an email that has an active ECA.
|
||||
If the git hook cannot verify your email, the Jetty committers **cannot do anything** to accept your commit.
|
||||
|
|
@ -11,293 +11,46 @@
|
|||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-source]]
|
||||
== Participate in the Code
|
||||
[[cg-getting-source]]
|
||||
== Getting the source code
|
||||
|
||||
If you are more interested in digging into what makes Jetty tick then this some information that you will need to arm yourself with.
|
||||
First we start with how to checkout and build Jetty, then on to our general coding standards followed by the actual patch contribution process.
|
||||
Jetty's source code lives 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:
|
||||
|
||||
[[cg-community-source]]
|
||||
=== Source Control
|
||||
[source, shell]
|
||||
----
|
||||
git clone https://github.com/eclipse/jetty.project.git
|
||||
----
|
||||
|
||||
The https://github.com/eclipse/jetty.project[Eclipse Jetty project] is located at https://github.com[Github] under the Eclipse Foundation https://github.com/eclipse[parent project]. There are a number of branches that are generally of interest.
|
||||
[[cg-repositories]]
|
||||
=== Primary and secondary repositories
|
||||
|
||||
.Active Eclipse Jetty Branches
|
||||
As well as the primary Jetty code repository, we maintain a number of secondary repos for project-related code and metadata.
|
||||
|
||||
Primary Jetty code repository:: https://github.com/eclipse/jetty.project
|
||||
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
|
||||
|
||||
[[cg-version-branches]]
|
||||
=== Version branches
|
||||
If you are planning on working with a specific issue within Jetty it is important to target the correct branch for a pull request.
|
||||
|
||||
.Active and inactive Jetty branches
|
||||
[cols="4"]
|
||||
|===
|
||||
| https://github.com/eclipse/jetty.project/tree/jetty-12.0.x[jetty-12.0.x] | Development | Servlet 6.0 | Java 17+
|
||||
| https://github.com/eclipse/jetty.project/tree/jetty-11.0.x[jetty-11.0.x] | Development | Servlet 5.0 | Java 11+
|
||||
| https://github.com/eclipse/jetty.project/tree/jetty-10.0.x[jetty-10.0.x] | Development (default branch) | Servlet 4.0 | Java 11+
|
||||
| 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
|
||||
|===
|
||||
|
||||
If you are planning on working with a specific issue within Jetty it is important to target the correct branch for a pull request. Pull requests that are targeted at Maintenance Branches are typically merged forward into subsequent branches while historical branches are left alone merge wise. Depending on the nature of an issue a historical branch may have an issue cherrypicked forward, but maintenance releases are merged wholesale forward as a matter of project policy.
|
||||
As a matter of project policy, maintenance branches are periodically merged wholesale into active development branches.
|
||||
This means that changes to maintenance branches should typically be forward compatible with later releases.
|
||||
|
||||
==== Primary SCM
|
||||
|
||||
The primary repository for Jetty is:
|
||||
|
||||
Jetty Project Repository::
|
||||
https://github.com/eclipse/jetty.project
|
||||
|
||||
==== Secondary SCM
|
||||
|
||||
These are the URLs for Jetty-related code and metadata.
|
||||
These are not needed to use Jetty; these are primarily of use for developers who are working with the open source project within Eclipse.
|
||||
|
||||
Administrative pom.xml file::
|
||||
https://github.com/eclipse/jetty.parent
|
||||
Build related artifacts that release separately, common assembly descriptors, remote resources, etc.::
|
||||
https://github.com/eclipse/jetty.toolchain
|
||||
|
||||
[[cg-contributing-build]]
|
||||
=== Maven Build
|
||||
|
||||
Eclipse Jetty uses http://maven.apache.org/[Apache Maven] for managing the project metadata and controlling the build.
|
||||
|
||||
Building Jetty should simply be a matter of changing into the relevant directory and executing the following commands:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
||||
$ git clone https://github.com/eclipse/jetty.project.git
|
||||
$ cd jetty.project
|
||||
$ mvn install
|
||||
|
||||
|
||||
....
|
||||
|
||||
All relevant dependencies should be downloaded into your local repository automatically and the build should proceed normally.
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
Jetty has a great many test cases that run through the course of its build. Many of these tests spin up embedded instances of Jetty itself, and it is not uncommon to see hundreds or more instances of Jetty start and stop during tests.
|
||||
Periodically we find some test cases to be more time dependent than they should be and this results in intermittent test failures.
|
||||
You can help track these down by opening an https://github.com/eclipse/jetty.project/issues[Issue].
|
||||
____
|
||||
|
||||
|
||||
|
||||
[[cg-coding-standards]]
|
||||
=== Coding Standards
|
||||
|
||||
Jetty uses number of conventions for its source code. The developers of Jetty use a variety of tooling and editors when developing Jetty so standards and conventions are important!
|
||||
|
||||
==== IntelliJ IDE
|
||||
|
||||
The suggested configuration for the IntelliJ IDE when working with Jetty is available in the code tree
|
||||
`/build-resources/jetty-codestyle-intellij.xml`
|
||||
|
||||
==== Eclipse IDE
|
||||
|
||||
The Eclipse IDE format can be found in the code tree
|
||||
`/build-resources/jetty-codestyle-eclipse-ide.xml`
|
||||
|
||||
==== Code Conventions
|
||||
|
||||
The following is an example of the Java formatting and naming styles to apply to Jetty:
|
||||
|
||||
[source, java, subs="{sub-order}"]
|
||||
----
|
||||
|
||||
import some.exact.ClassName; // GOOD
|
||||
import some.wildcard.package.*; // BAD!
|
||||
|
||||
package org.always.have.a.package;
|
||||
|
||||
/* --------------------------------------------------------- */
|
||||
/** Always have some javadoc
|
||||
*/
|
||||
class MyClassName
|
||||
{
|
||||
// indent by 4 spaces.
|
||||
// use spaced to indent
|
||||
// The code must format OK with default tabsize of 8.
|
||||
|
||||
private static final int ALL_CAPS_FOR_PUBLIC_CONSTANTS=1;
|
||||
|
||||
// Field prefixed with __ for static of _ for normal fields.
|
||||
// This convention is no longer mandatory, but any given
|
||||
// class should either consistently use this style or not.
|
||||
private static String __staticField;
|
||||
private Object _privateField;
|
||||
|
||||
|
||||
// use getters and setters rather than public fields.
|
||||
public void setPrivateField(Object privateField)
|
||||
{
|
||||
_privateField=privateField;
|
||||
}
|
||||
|
||||
public Object getPrivateField()
|
||||
{
|
||||
return _privateField;
|
||||
}
|
||||
|
||||
public void doSomething()
|
||||
throws SomeException
|
||||
{
|
||||
Object local_variable = _privateField;
|
||||
if (local_variable==null)
|
||||
{
|
||||
// do Something
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
----
|
||||
|
||||
While Eclipse Jetty is an open source project it is also a member of the Eclipse Foundation which carries along some additional responsibilities.
|
||||
Intellectual Property is a hallmark concern of the Eclipse Foundation so you are encouraged to understand what that entails before diving in.
|
||||
As much as we would like to accept a tremendous pull request, without the proper chain of events being completed our hands are tied.
|
||||
That being said, the steps are not particularly onerous and we are happy to work with you to get them accomplished.
|
||||
|
||||
==== Logging Conventions
|
||||
|
||||
When deciding when and what to log, bear in mind a few things:
|
||||
|
||||
* never use `LOG.debug` without a preceding `if (LOG.isDebugEnabled())`
|
||||
* we don't want to pollute the log with very long stacktraces unless necessary
|
||||
* we don't want to routinely produce logging events in response to data sent by a user
|
||||
* we should not call more than one LOG method for a single event: otherwise log messages may be interleaved and more confusing
|
||||
* we should never LOG.warn and then throw that exception, as that will result in double handling
|
||||
* we should seldom LOG.debug and then throw as that will make debug verbose and add little information
|
||||
* when interacting with a request, or information received from a client:
|
||||
** no logging unless `isDebugEnabled`, in which case you output at `DEBUG` level eg:
|
||||
[source, java, subs="{sub-order}"]
|
||||
----
|
||||
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, and use `isDebugEnabled` to cut down on the size of the logging of stack traces:
|
||||
[source, java, subs="{sub-order}"]
|
||||
----
|
||||
catch (Throwable t)
|
||||
{
|
||||
if (LOG.isDebugEnabled())
|
||||
LOG.info("Something happened {} {} {}", x, y, z, t);
|
||||
else
|
||||
LOG.info("Something happened {} {} {} {}", x, y, z, t.toString());
|
||||
}
|
||||
----
|
||||
|
||||
* when exceptions happen in jetty code:
|
||||
** mostly use `WARN` or `ERROR` level
|
||||
** if the exception is not entirely unexpected, can happen relatively frequently, or can potentially have a very long stack trace and you don't want to clutter up the log, you can use `isDebugEnabled` to cut down on the size of the logging of the stacktrace:
|
||||
[source, java, subs="{sub-order}"]
|
||||
----
|
||||
catch (Throwable t)
|
||||
{
|
||||
if (LOG.isDebugEnabled())
|
||||
LOG.warn("Something happened {} {} {}", x, y, z, t);
|
||||
else
|
||||
LOG.warn("Something happened {} {} {} {}", x, y, z, t.toString());
|
||||
}
|
||||
----
|
||||
|
||||
____
|
||||
[TIP]
|
||||
Be aware that `LOG.warn("Something happened", t)` is the same as `LOG.warn("Something happened {}", t)`, at least for the default jetty logging.
|
||||
In both cases, the full stacktrace is output. If you only want the log message, you need to do `LOG.warn("Something happened {}", t.toString())`.
|
||||
____
|
||||
|
||||
[[cg-patches]]
|
||||
=== Contributing Patches
|
||||
|
||||
We love seeing people contribute patches to the Jetty project and the process is relatively simple.
|
||||
The requirements to commit are modest but very important to the Eclipse Foundation and the intellectual property of the open source project.
|
||||
The following is the general process by which we operate.
|
||||
|
||||
* You must have a signed Eclipse Contributor Agreement.
|
||||
* This agreement must be under the _same_ email address as the Git pull request originates from.
|
||||
* The commit must be signed.
|
||||
* When the pull request is made, a git-hook will validate the email address.
|
||||
** If the result is a green checkbox then the Jetty committers can review the pull request.
|
||||
** If the result is a red X then there is absolutely nothing the Jetty committers can do to accept the commit at this point.
|
||||
* This may not be the final form a commit will take, there may be some back and forth and you may be asked to re-issue a pull request.
|
||||
|
||||
|
||||
Not everything is specifically relevant since we are at GitHub but the crux of things are detailed there.
|
||||
The ECA is *critically* important to the process.
|
||||
|
||||
[[cg-contributing-eca]]
|
||||
==== Sign an Eclipse Contributor Agreement (ECA)
|
||||
|
||||
The Eclipse Foundation has a strong Intellectual Property policy which tracks contributions in detail to ensure that:
|
||||
|
||||
1. Did the contributor author 100% of the content?
|
||||
2. Does the contributor have the rights to contribute this content to Eclipse?
|
||||
3. Is the contribution under the project’s license(s) (e.g. EPL)
|
||||
|
||||
A contributor needs to e-sign a Eclipse Contributor Agreement (for more explanation see the http://www.eclipse.org/legal/ecafaq.php[Eclipse ECA FAQ] ) regardless of how their contribution patch is provided.
|
||||
You can familiarize yourself with the Eclipse wiki page at http://wiki.eclipse.org/Development_Resources/Contributing_via_Git[Contributing via Git].
|
||||
In order to have a pull request accepted by any Eclipse project you *must* complete this agreement.
|
||||
____
|
||||
[TIP]
|
||||
Log into the https://www.eclipse.org[Eclipse home page] (you will need to create an account with the Eclipse Foundation if you have not already done so), click on "Eclipse ECA", and complete the form.
|
||||
Be sure to use the _same email address_ when you create any Git commit records.
|
||||
____
|
||||
|
||||
[[t-contributing-git-config]]
|
||||
==== Configuring Git
|
||||
|
||||
GitHub has copious amounts of quality documentation on how to interact with the system and you will minimally need to configure the user.email property.
|
||||
Check out the following link:https://help.github.com/articles/setting-your-email-in-git[guide on GitHub] for more information.
|
||||
|
||||
[[t-contributing-making-the-commit]]
|
||||
==== Making the Commit
|
||||
|
||||
When making the commit for the pull request it is _vital_ that you "sign-off" on the commit using `git commit -s` option.
|
||||
Without this sign-off, your patch cannot be applied to the Jetty repository because it will be rejected.
|
||||
|
||||
You can check out the link:https://help.github.com/articles/signing-tags-using-gpg[guide at Github] for more information.
|
||||
____
|
||||
[TIP]
|
||||
One way to think of this is that when you sign the ECA you are indicating that you are free to contribute to eclipse, but that doesn't mean everything you ever do can be contributed.
|
||||
Using the commit signing mechanism indicates that your commit is under the auspices of your agreement.
|
||||
____
|
||||
|
||||
If a pull request is for a particular issue in our repository then the format of the commit message is important.
|
||||
The message should follow the form "Issue #123 <description of the commit>".
|
||||
When the Jetty project runs releases we have an automated process that scans for commits with this format for inclusion in our VERSION.txt file.
|
||||
|
||||
[source, screen]
|
||||
----
|
||||
> git commit -s -m "Issue #123 resolving the issue by adding widget"
|
||||
----
|
||||
|
||||
[[cg-the-pull-request]]
|
||||
==== The Pull Request
|
||||
|
||||
Pull requests are very much a GitHub process so best link:https://help.github.com/articles/creating-a-pull-request[explained by Github].
|
||||
|
||||
[[cg-our-policies]]
|
||||
==== Our Policies
|
||||
|
||||
We wholeheartedly welcome contributions to Jetty and will do our best to process them in a timely fashion.
|
||||
While not every contribution will be accepted, our commitment is to work with interested parties on the things they care about.
|
||||
With that in mind, we can only handle pull requests with actively engaged parties.
|
||||
We reserve the right to abandon pull requests whose authors do no respond in a timely fashion.
|
||||
|
||||
We will generally adhere to the following time frames for contributions:
|
||||
|
||||
* Invalid Pull Requests - 1 week
|
||||
** These pull requests do not follow the contribution requirements for some reason, be it missing contributor agreement or the wrong email.
|
||||
** We will try and follow up with the pull request author to resolve the issue but much of this is out of our hands and are between committer and the Eclipse Foundation.
|
||||
** If we do not hear from the contributor after a week we will close the pull request.
|
||||
|
||||
* Valid Pull Requests - 2 weeks
|
||||
** These pull requests have a green check mark after the commit title.
|
||||
** If the pull request can be immediately applied we will do so.
|
||||
** There may need to be some conversation on the issue in which case a committer will follow up with the author in the pull request.
|
||||
** If the original contributor does not respond within 2 weeks we may close the commit.
|
||||
** If we see value in the commit yet the author has not responded after 2 weeks we may make some variation of the commit ourselves.
|
||||
Older branches remain untouched unless 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.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,121 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-building-jetty]]
|
||||
== Building Jetty
|
||||
|
||||
Jetty uses http://maven.apache.org/[Apache Maven] as its build tool.
|
||||
To successfully build the project, you will also need a recent version of the Java Development Kit (JDK).
|
||||
|
||||
[[cg-maven-jdk-requirements]]
|
||||
=== Maven and JDK requirements
|
||||
|
||||
Here are the minimum Maven and JDK version build requirements for each of the actively maintained branches of Jetty.
|
||||
|
||||
.Build versioning requirements by branch
|
||||
[cols="4"]
|
||||
|===
|
||||
| Branch | Maven Version | Minimum JDK | Recommended 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
|
||||
|===
|
||||
|
||||
[[cg-fast-build]]
|
||||
=== Running a fast build
|
||||
|
||||
To get started with Jetty as quickly as possible, navigate to your local copy of the Jetty repo and run `maven -Pfast clean install`.
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
$ git clone https://github.com/eclipse/jetty.project.git
|
||||
$ cd jetty.project
|
||||
$ mvn -Pfast clean install
|
||||
----
|
||||
|
||||
The `-Pfast` flag tells Maven to bypass running tests and other checks.
|
||||
|
||||
[[cg-full-build]]
|
||||
=== Running a full build
|
||||
|
||||
To build Jetty and automatically run all tests -- which can take quite some time -- run `mvn install` without any flags:
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
$ git clone https://github.com/eclipse/jetty.project.git
|
||||
$ cd jetty.project
|
||||
$ mvn install
|
||||
----
|
||||
|
||||
The full Jetty build 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]`.
|
||||
|
||||
[TIP]
|
||||
.Flagging flaky tests
|
||||
====
|
||||
Not all test cases are as timing independent as they should be, which can result in intermittent test failures.
|
||||
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]]
|
||||
=== 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.
|
||||
This is configurable with the following command line flags.
|
||||
|
||||
-Djunit.jupiter.execution.parallel.enabled:: Set to `false` to disable parallel execution of tests, like so:
|
||||
|
||||
mvn install -Djunit.jupiter.execution.parallel.enabled=false
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Certain tests cannot be run in parallel because they access or modify `static` fields, and are tagged in the codebase with this annotation:
|
||||
|
||||
[source, java]
|
||||
----
|
||||
@Isolated("Access static field of Configurations")
|
||||
----
|
||||
|
||||
Maven will run these tests in isolation even when parallel execution is explicitly enabled.
|
||||
====
|
||||
|
||||
-Djunit.jupiter.execution.parallel.config.fixed.parallelism:: Configures the number of tests to be executed in parallel.
|
||||
|
||||
mvn install -Djunit.jupiter.execution.parallel.config.fixed.parallelism=2
|
||||
|
||||
// TODO: review this section
|
||||
[[cg-option-build-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://www.docker.com/[Docker]: used to run some integration tests for testing third party integrations.
|
||||
|
||||
// TODO: review this section
|
||||
[[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"]
|
||||
|===
|
||||
| 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
|
||||
|===
|
||||
|
|
@ -1,201 +0,0 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-documentation]]
|
||||
== Participate in the Documentation
|
||||
|
||||
Another wonderful way to help with Eclipse Jetty is to help contribute to our corpus of documentation.
|
||||
We have made an effort to reduce the barriers to contributing to our documentation, and many contributors find our documentation as a low-key way to participate and learn the process.
|
||||
|
||||
|
||||
[[cg-documentation-format]]
|
||||
=== Source Control and Maven Build.
|
||||
|
||||
The Jetty documentation is a module within the overall Jetty project and is build as a part of the standard build process.
|
||||
As such to checkout the documentation you can follow the link:#cg-community-source[same process] as checking out Jetty itself.
|
||||
|
||||
As a part of the main Jetty project the documentation is build through the link:#cg-contributing-build[same process] as Jetty.
|
||||
However, it is a more independent module and can be worked with much simpler by building strictly the jetty-documentation module.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
|
||||
$ git clone https://github.com/eclipse/jetty.project.git
|
||||
$ cd jetty.project/jetty-documentation
|
||||
$ mvn install
|
||||
|
||||
....
|
||||
|
||||
While maven is running you may see a lot of files being downloaded.
|
||||
If you are not familiar with Maven you are seeing Maven set up the execution environment for generating the documentation.
|
||||
|
||||
The build is finished once you see a message akin to:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
....
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] BUILD SUCCESS
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] Total time: 9.272 s
|
||||
[INFO] Finished at: 2018-04-09T13:06:10-05:00
|
||||
[INFO] Final Memory: 74M/247M
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
....
|
||||
|
||||
At this point you open your web browser and view the produced documentation (under the target/html directory)!
|
||||
|
||||
[TIP]
|
||||
====
|
||||
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 indicates that an ID is being reused and should be resolved or else deep linking will work correctly.
|
||||
====
|
||||
|
||||
[[cg-documentation-render]]
|
||||
=== The Render Chain Explained
|
||||
|
||||
The Jetty documentation is all written in https://asciidoctor.org/docs/user-manual/[asciidoc].
|
||||
The maven build uses the asciidoctor-maven-plugin to process specific index.adoc[] files which act as the root structure for various guides (Administrative, Developer, QuickStart, etc).
|
||||
The main pom.xml file also provides a maven profile which when activated can produce the guides in both pdf and epub formats.
|
||||
|
||||
[[cg-documentation-structure]]
|
||||
=== Project Structure
|
||||
|
||||
It may be useful to understand the layout of the documentation before digging into the details.
|
||||
The following table lists some helpful directories and their purpose.
|
||||
|
||||
.Documentation Layout
|
||||
[cols="2"]
|
||||
|===
|
||||
| src/main/asciidoc | root of asciidoc layout
|
||||
| src/main/asciidoc/*-guide | root structure for each individual guide
|
||||
| target/html | post build, where the rendered html files will appear
|
||||
| target/pdf | post build (-Palt-formats) pdf files
|
||||
| target/epub | post build (-Palt-formats) epub files
|
||||
|===
|
||||
|
||||
[[cg-documentation-guide]]
|
||||
=== Guide Structure
|
||||
|
||||
Each guide starts with an *index.adoc* file which acts as the point of origin for the document structure.
|
||||
It will declare useful metadata for the proper rendering of the overall guide and use the asciidoc *include* directive to pull in content for each chapter which are conveniently named by chapter number and name.
|
||||
|
||||
[[cg-documentation-conventions]]
|
||||
=== Conventions
|
||||
|
||||
Below is list of conventions that should be followed when developing documentation within this framework.
|
||||
These are not set in stone but you are encouraged to follow them when possible.
|
||||
|
||||
ventilated prose::
|
||||
Each sentence should generally be on its own line with a hard return at the end of the line.
|
||||
Asciidoc rendering does not treat this style as separate lines and will produce paragraphs correctly.
|
||||
The primary benefit is that you can easily see changes between versions of files, and it makes it trivial to quickly look through a pull request.
|
||||
Additional benefits are the ability to comment out a sentence mid paragraph or move sentences around within a paragraph.
|
||||
Enabling Soft Line Wrap in your favorite editor can make this a bit easier to stomach.
|
||||
|
||||
id's::
|
||||
Critically important for being able to generate url's that can be used in a persistent fashion.
|
||||
Without sane id's the chapters and sections will have generated id which are rooted in some obscure location based
|
||||
voodoo.
|
||||
A url using these 'e12c8673' type links will not be durable across generations of the documentation.
|
||||
These id's need to be used on chapters and sections two deep, and anywhere that you intend to cross link deeper.
|
||||
The id values go into a global namespace so they must be unique across the entire document or the last example will win and any cross links will go there.
|
||||
Links inside of a guides narrative structure should be prefixed with an acronym (contributor guide = cg-) while any links within the topics structure should be prefixed with t- and ideally the name of the topic it corresponds to.
|
||||
|
||||
link vs xref::
|
||||
The `link:` item should be generally used for linking around the document when you want to choose the text that will be rendered in the link itself.
|
||||
However if you are linking to a section and want to use the title itself as the link text, use the `xref:` tag without the hashmark in front of the link id.
|
||||
|
||||
cross guide linkage::
|
||||
To link to another guide it is best to use a property to address it. The following guide shortcuts are provided.
|
||||
* DISTGUIDE
|
||||
* EMBEDGUIDE
|
||||
* QUICKGUIDE
|
||||
* CONTRIBUIDE
|
||||
|
||||
....
|
||||
This is a test to link to link:{DISTGUIDE}[Distribution Guide]
|
||||
|
||||
This is a test to deep link to link:{DISTGUIDE}#startup[Distribution Guide Deep Link]
|
||||
....
|
||||
|
||||
This is a test to link to link:{DISTGUIDE}[Distribution Guide]
|
||||
|
||||
This is a test to deep link to link:{DISTGUIDE}#startup[Distribution Guide Deep Link]
|
||||
|
||||
images::
|
||||
Images are placed in the `/images*` directory of the guide they should appear in and then referenced with a `image:` tag.
|
||||
|
||||
....
|
||||
image:small_powered_by.gif[image,width=340]
|
||||
....
|
||||
|
||||
image:small_powered_by.gif[image,width=340]
|
||||
|
||||
version differences::
|
||||
In general differences in functionality within a release should go into nested sections and use titles like 'Prior to: ##' or 'In version: ##'.
|
||||
|
||||
license blocks::
|
||||
Each adoc file should contain the license block that exists in the index.adoc file and a copy has been added to the bottom of this page as well for reference.
|
||||
|
||||
....
|
||||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
....
|
||||
|
||||
Some admonition examples:
|
||||
|
||||
______________________________________________
|
||||
[NOTE]
|
||||
A note about the previous case to be aware of.
|
||||
______________________________________________
|
||||
|
||||
________________________________________
|
||||
[IMPORTANT]
|
||||
Important notes are marked with an icon.
|
||||
________________________________________
|
||||
|
||||
________________________________
|
||||
[TIP]
|
||||
Tips that make your life easier.
|
||||
________________________________
|
||||
|
||||
_______________________________________________________
|
||||
[CAUTION]
|
||||
Places where you have to be careful what you are doing.
|
||||
_______________________________________________________
|
||||
|
||||
__________________________________________________________________________________________________________________
|
||||
[WARNING]
|
||||
Where extreme care has to be taken. Data corruption or other nasty
|
||||
things may occur if these warnings are ignored.
|
||||
__________________________________________________________________________________________________________________
|
||||
|
||||
==== Oddities
|
||||
|
||||
* If an included file ends with a list entry, it needs to have two empty lines at the end of the file in order for the section rendering to work correctly.
|
||||
|
|
@ -0,0 +1,140 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-code-standards]]
|
||||
== Code Standards
|
||||
Jetty uses number of conventions for its source code.
|
||||
The developers of Jetty use a variety of tooling and editors when developing Jetty so standards and conventions are important!
|
||||
|
||||
[[cg-ide-configuration]]
|
||||
=== Configuring your IDE
|
||||
|
||||
IntelliJ IDE::
|
||||
An IntelliJ code style XML file is available in the Jetty code tree at
|
||||
https://github.com/eclipse/jetty.project/blob/jetty-10.0.x/build-resources/jetty-codestyle-intellij.xml[`/build-resources/jetty-codestyle-intellij.xml`]
|
||||
// TODO: The above link points to the jetty-10.0.x branch, but it doesn't look like there's a `build-resources` directory for jetty-12.0.x.
|
||||
Follow the https://www.jetbrains.com/help/idea/configuring-code-style.html#import-export-schemes[IntelliJ documentation] to apply these code style settings locally.
|
||||
|
||||
Eclipse IDE::
|
||||
An Eclipse code style XML file can be found in the code tree
|
||||
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]]
|
||||
=== Java conventions
|
||||
|
||||
The following sample code shows the 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
|
||||
*/
|
||||
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;
|
||||
|
||||
// Prefix static fields with two underscores (__)
|
||||
// and normal 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.
|
||||
public void setPrivateField(Object privateField)
|
||||
{
|
||||
_privateField=privateField;
|
||||
}
|
||||
|
||||
public Object getPrivateField()
|
||||
{
|
||||
return _privateField;
|
||||
}
|
||||
|
||||
public void doSomething()
|
||||
throws SomeException
|
||||
{
|
||||
Object local_variable = _privateField;
|
||||
if (local_variable==null)
|
||||
{
|
||||
// do Something
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
----
|
||||
|
||||
[[cg-logging-conventions]]
|
||||
=== Logging conventions
|
||||
|
||||
When deciding when and what to log, bear in mind a few things:
|
||||
|
||||
* Never use `LOG.debug()` without a preceding `if (LOG.isDebugEnabled())`.
|
||||
* 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.
|
||||
* 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:
|
||||
|
||||
[source, java]
|
||||
----
|
||||
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)
|
||||
{
|
||||
if (LOG.isDebugEnabled())
|
||||
LOG.info("Something happened {} {} {}", x, y, z, t);
|
||||
else
|
||||
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:
|
||||
[source, java]
|
||||
----
|
||||
catch (Throwable t)
|
||||
{
|
||||
if (LOG.isDebugEnabled())
|
||||
LOG.warn("Something happened {} {} {}", x, y, z, t);
|
||||
else
|
||||
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())`.
|
||||
====
|
||||
|
|
@ -1,30 +0,0 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-security]]
|
||||
== Security
|
||||
|
||||
[[cg-security-reporting]]
|
||||
=== Reporting Security Issues
|
||||
|
||||
There are a number of avenues for reporting security issues to the Jetty project available.
|
||||
If the issue is directly related to Jetty itself then reporting to the Jetty developers is encouraged.
|
||||
The most direct method is to send e-mail to _security@webtide.com_.
|
||||
Since Webtide is comprised of the active committers of the Jetty project this is our preferred reporting method.
|
||||
We are generally flexible in how we work with reporters of security issues from an attribution perspective but we reserve the right to act in the interests of the Jetty project in all circumstances.
|
||||
|
||||
If the issue is related to Eclipse or its Jetty integration then we encourage you to reach out to _security@eclipse.org_.
|
||||
|
||||
If the issue is related to some third party integration with Jetty we are happy to work with you to identify the proper entity and worth with them to properly address any issue so either of the above outreaches is fine.
|
||||
|
||||
We prefer that security issues are reported directly to Jetty developers via email as opposed through GitHub Issues since there is currently no facility for _private_ issues. There is an https://github.com/isaacs/github/issues/37[unofficial thread] for this support at github you are welcome to follow along on.
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-conclusion]]
|
||||
== Thank you!
|
||||
|
||||
Your interest in contributing to Eclipse Jetty is welcome and if there is anything you feel this guide is lacking please let us know.
|
||||
Feel free to open an Issue as described in this document and perhaps even contribute your suggestion to {GITDOCURL}/contribution-guide[this document] itself!
|
||||
|
||||
[[cg-contributing-guides]]
|
||||
|
||||
Our current guides are:
|
||||
|
||||
* {GUIDEBASEURL}/quickstart/[Distribution Quickstart Guide]
|
||||
* {GUIDEBASEURL}/contribution/[Contribution Guide]
|
||||
|
|
@ -0,0 +1,284 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-documentation]]
|
||||
== Writing Documentation
|
||||
|
||||
Another great way to contribute to Jetty is to help us write and maintain our documentation.
|
||||
|
||||
[[cg-documentation-guides]]
|
||||
Jetty's documentation is grouped into three guides, each written for a different target audience.
|
||||
|
||||
<<og-intro,Operations Guide>>::
|
||||
The Operations Guide targets sysops, devops, and developers who want to run Jetty as a standalone web server.
|
||||
|
||||
<<pg-intro,Programming Guide>>::
|
||||
The Programming Guide targets developers who want to use the Jetty libraries in their applications.
|
||||
|
||||
<<cg-intro,Contribution Guide>>::
|
||||
The Contribution Guide targets developers and writers who want to make contributions to the Jetty project.
|
||||
|
||||
[[cg-doc-toolchain]]
|
||||
=== The documentation toolchain
|
||||
The Jetty project uses a https://www.writethedocs.org/guide/docs-as-code/["docs as code"] philosophy, meaning we use the same tools to write and build both our code and our documentation.
|
||||
|
||||
For instance, we maintain the docs 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]]
|
||||
==== AsciiDoc
|
||||
Jetty's documentation is 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.
|
||||
|
||||
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]]
|
||||
==== Maven and Asciidoctor
|
||||
Just as we use Maven to <<cg-building-jetty,build the Jetty codebase>>, we also use Maven to build the docs.
|
||||
Specifically, 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 is integrated 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.
|
||||
|
||||
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.
|
||||
|
||||
[source, screen]
|
||||
----
|
||||
$ git clone https://github.com/eclipse/jetty.project.git
|
||||
$ cd jetty.project/documentation
|
||||
$ mvn install
|
||||
<...snip...>
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] BUILD SUCCESS
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
[INFO] Total time: 9.272 s
|
||||
[INFO] Finished at: 2018-04-09T13:06:10-05:00
|
||||
[INFO] Final Memory: 74M/247M
|
||||
[INFO] ------------------------------------------------------------------------
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
You'll see a lot of files getting downloaded during the build process.
|
||||
This is Maven setting up the execution environment, which it uses to generate the docs.
|
||||
====
|
||||
|
||||
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]]
|
||||
==== Documentation project structure
|
||||
|
||||
The documentation root is https://github.com/eclipse/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation/src/main[`documentation/jetty-documentation/`].
|
||||
Within this root directory are some files and subdirectories of note:
|
||||
|
||||
`target/<format>`::
|
||||
The final build destination for any docs generated by Maven. The default is `html`, but other formats (e.g., `pdf` and `epub`) are available.
|
||||
|
||||
`src/main/asciidoc`::
|
||||
The primary root for all documentation content.
|
||||
|
||||
`src/main/asciidoc/config.adoc`::
|
||||
This file contains metadata and global variables shared across all the <<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>>.
|
||||
|
||||
`src/main/asciidoc/*-guide/index.adoc`::
|
||||
Asciidoctor's "point of entry" for each guide.
|
||||
Content is pulled into the guide via the `include::` directives in these index files.
|
||||
Also, guide-specific metadata and variables that wouldn't belong in the root `config.adoc` can also be defined here.
|
||||
|
||||
|
||||
[[cg-documentation-style-guide]]
|
||||
=== Style guide
|
||||
|
||||
The following conventions are not set in stone, but you are encouraged to follow them where possible.
|
||||
They are intended to keep the docs stylistically consistent, in an effort to keep them both to both understand and maintain.
|
||||
|
||||
[[cg-ventilated-prose]]
|
||||
==== Ventilated prose
|
||||
|
||||
In markup, each sentence should be on its own line with a hard return at the end of the line.
|
||||
This practice is known variously as https://writetheasciidocs.netlify.app/ventilated-prose[ventilated prose] or https://rhodesmill.org/brandon/2012/one-sentence-per-line/[semantic linefeeds].
|
||||
|
||||
AsciiDoc treats a single line breaks just like a space, and so will render ventilated prose naturally.
|
||||
|
||||
This practice makes for more readable file diffs, and makes it easier to comment out individual lines of text or move sentences around
|
||||
|
||||
|
||||
[[cg-documenting-versions]]
|
||||
==== Documenting versions
|
||||
|
||||
|
||||
[[cg-documenting-version-changes]]
|
||||
===== Documenting changes in functionality
|
||||
|
||||
Major changes in functionality between versions of Jetty should be called out using separate subsections.
|
||||
The title of the subsection should specifically call out the relevant versions, 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]]
|
||||
===== Documenting multiple versions at once
|
||||
|
||||
Jetty 12 features 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, but 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`.
|
||||
|
||||
Another approach is to write your docs targeting a single specific module, and to tell the reader what substitution(s) they would need to make if they want to target a different one.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
When targeting a specific version in your docs for demonstration purposes, you should typically use the most recent version number (i.e., `ee10-deploy`).
|
||||
====
|
||||
|
||||
Consolidating parallel references saves readers from reading through unhelpfully repetitive content.
|
||||
It also saves us from having to maintain multiple versions of nearly identical docs.
|
||||
|
||||
|
||||
[[cg-documenting-versions-in-examples]]
|
||||
===== 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 a specific "example" version.
|
||||
|
||||
For example, let's say you're telling the reader how to install the `ee{8,9,10}-deploy` family of modules:
|
||||
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=ee{8,9,10}-deploy
|
||||
|
||||
However, any reader who copy-pastes the above into their command line will get a failure.
|
||||
|
||||
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]
|
||||
====
|
||||
You may want to remind the reader to change the `10` in the command to their preferred target version -- although it's not strictly necessary for a simple example like this.
|
||||
====
|
||||
|
||||
[[cg-license-blocks]]
|
||||
==== 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:
|
||||
|
||||
----
|
||||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
----
|
||||
|
||||
[[cg-asciidoc-conventions]]
|
||||
=== AsciiDoc conventions
|
||||
|
||||
[[cg-custom-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.
|
||||
|
||||
At minimum, every chapter and top-level section should have its own custom ID; however, best practice is to give each subsection its own custom ID, too.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Custom IDs share a single global namespace, which means they must be unique across all documentation guides.
|
||||
To help deal with this constraint, we used different ID prefixes in each guide:
|
||||
|
||||
* Operations Guide: `og-`
|
||||
* Programming Guide: `pg-`
|
||||
* Contribution Guide: `cg-`
|
||||
====
|
||||
|
||||
|
||||
[[cg-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=340]
|
||||
|
||||
|
||||
[[cg-admonitions]]
|
||||
==== Admonitions
|
||||
|
||||
Admonitions (a.k.a. "callout blocks") are useful for flagging information that doesn't belong in the natural flow of text.
|
||||
Asciidoc supports five levels of admonition:
|
||||
|
||||
* `[NOTE]`
|
||||
* `[IMPORTANT]`
|
||||
* `[TIP]`
|
||||
* `[CAUTION]`
|
||||
* `[WARNING]`
|
||||
|
||||
Each admonition's visual appearance and typical usage situation are as follows:
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
A note about the previous case to be aware of.
|
||||
====
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
Important notes are marked with an icon.
|
||||
====
|
||||
|
||||
[TIP]
|
||||
====
|
||||
Tips that make your life easier.
|
||||
====
|
||||
|
||||
[CAUTION]
|
||||
====
|
||||
Places where you have to be careful what you are doing.
|
||||
====
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
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.
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-submitting-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
|
||||
|
||||
The email in your git commits must match the email you used to <<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]]
|
||||
==== 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>*, like so:
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
$ 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]]
|
||||
=== 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
|
||||
----
|
||||
====
|
||||
|
||||
[[cg-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]]
|
||||
=== Time frames
|
||||
|
||||
We do our best to process contributions in a timely fashion.
|
||||
Please note that we can only handle pull requests with actively engaged parties.
|
||||
We reserve the right to abandon pull requests whose authors do not respond in a timely fashion.
|
||||
|
||||
We will generally adhere to the following time frames for contributions:
|
||||
|
||||
Invalid Pull Requests - 1 week::
|
||||
These pull requests do not follow the contribution requirements for some reason -- e.g., a missing contributor agreement or mismatched email signature.
|
||||
We will try and follow up with the pull request author to resolve the issue.
|
||||
If we do not hear from the contributor after a week we will close the pull request.
|
||||
|
||||
Valid Pull Requests - 2 weeks::
|
||||
If the pull request can be immediately merged, we will do so.
|
||||
Otherwise, we will follow up with the author in a comment to discuss what additional actions must be taken before the change can be landed.
|
||||
If the original contributor does not respond within two weeks, we may close the commit, or make some variation of the commit ourselves.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[cg-security]]
|
||||
== Security
|
||||
|
||||
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.
|
||||
|
||||
[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].
|
||||
====
|
||||
|
||||
* 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].
|
||||
|
||||
* If the issue is related to some third party integration, we are happy to work with you to identify the proper reporting entity and work with them to properly address the issue.
|
||||
In this case, you are welcome to contact either of the above outreach addresses.
|
||||
|
||||
We are generally flexible in how we work with reporters of security issues from an attribution perspective, but reserve the right to act in the interests of the Jetty project in all circumstances.
|
||||
|
|
@ -11,15 +11,18 @@
|
|||
// ========================================================================
|
||||
//
|
||||
|
||||
:doctitle: Eclipse Jetty: Contribution Guide
|
||||
:toc-title: Contribution Guide
|
||||
:breadcrumb: Home:../index.html | Contribution Guide:./index.html
|
||||
:idprefix: cg-
|
||||
|
||||
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::1-introduction.adoc[]
|
||||
include::2-community.adoc[]
|
||||
include::2-eca.adoc[]
|
||||
include::3-source.adoc[]
|
||||
include::4-documentation.adoc[]
|
||||
include::5-security.adoc[]
|
||||
include::6-conclusion.adoc[]
|
||||
include::4-build.adoc[]
|
||||
include::5-code-standards.adoc[]
|
||||
include::6-documentation.adoc[]
|
||||
include::7-submitting-patches.adoc[]
|
||||
include::8-security.adoc[]
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ Refer to the section about xref:og-deploy[deployment] for further information ab
|
|||
$ java -jar $JETTY_HOME/start.jar --add-modules={ee-current}-deploy
|
||||
----
|
||||
|
||||
[source,options=nowrap]
|
||||
[source,options=nowrap,subs=attributes]
|
||||
----
|
||||
include::jetty[setupArgs="--add-modules=http",args="--add-modules={ee-current}-deploy"]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -11,12 +11,12 @@
|
|||
// ========================================================================
|
||||
//
|
||||
|
||||
:doctitle: link:https://eclipse.org/jetty[Eclipse Jetty]: Operations Guide
|
||||
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
|
||||
:toc-title: Jetty Programming Guide
|
||||
:toc-title: Programming Guide
|
||||
:idprefix: pg-
|
||||
:docinfo: private-head
|
||||
|
||||
include::../config.adoc[]
|
||||
include::.asciidoctorconfig[]
|
||||
include::introduction.adoc[]
|
||||
include::client/client.adoc[]
|
||||
|
|
|
|||
|
|
@ -11,6 +11,7 @@
|
|||
// ========================================================================
|
||||
//
|
||||
|
||||
[[pg-intro]]
|
||||
== Eclipse Jetty Programming Guide
|
||||
|
||||
The Eclipse Jetty Programming Guide targets developers who want to use the Jetty libraries in their applications.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
[[jetty-jspc-maven-plugin]]
|
||||
=== Jetty Jspc Maven Plugin
|
||||
|
||||
This plugin will help you pre-compile your jsps and works in conjunction with the Maven war plugin to put them inside an assembled war.
|
||||
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.
|
||||
|
||||
[[jspc-config]]
|
||||
==== Configuration
|
||||
|
|
|
|||
Loading…
Reference in New Issue