From b6786e29c255c77c6dccd2a53c31fe48fc897961 Mon Sep 17 00:00:00 2001 From: Jesse McConnell Date: Fri, 17 May 2024 12:04:55 -0500 Subject: [PATCH] Add the contribution guide from Jetty 12 --- .../ROOT/assets/images/small_powered_by.gif | Bin 0 -> 4787 bytes contribution-guide/modules/ROOT/nav.adoc | 22 +- .../modules/ROOT/pages/build/index.adoc | 137 +++++++++ .../ROOT/pages/documentation/index.adoc | 273 ++++++++++++++++++ .../modules/ROOT/pages/eca/index.adoc | 30 ++ .../modules/ROOT/pages/index.adoc | 54 +++- .../modules/ROOT/pages/patches/index.adoc | 67 +++++ .../modules/ROOT/pages/security/index.adoc | 32 ++ .../modules/ROOT/pages/source/index.adoc | 49 ++++ .../modules/ROOT/pages/standards/index.adoc | 133 +++++++++ 10 files changed, 794 insertions(+), 3 deletions(-) create mode 100644 contribution-guide/modules/ROOT/assets/images/small_powered_by.gif create mode 100644 contribution-guide/modules/ROOT/pages/build/index.adoc create mode 100644 contribution-guide/modules/ROOT/pages/documentation/index.adoc create mode 100644 contribution-guide/modules/ROOT/pages/eca/index.adoc create mode 100644 contribution-guide/modules/ROOT/pages/patches/index.adoc create mode 100644 contribution-guide/modules/ROOT/pages/security/index.adoc create mode 100644 contribution-guide/modules/ROOT/pages/source/index.adoc create mode 100644 contribution-guide/modules/ROOT/pages/standards/index.adoc diff --git a/contribution-guide/modules/ROOT/assets/images/small_powered_by.gif b/contribution-guide/modules/ROOT/assets/images/small_powered_by.gif new file mode 100644 index 0000000000000000000000000000000000000000..c5dd44319f0aa17ea93b15fbcc8a18e14ca397d5 GIT binary patch literal 4787 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.tar.gz` | The Jetty Home distribution +| `jetty-12.0.x` | `jetty-ee10/jetty-ee10-runner/target/jetty-ee10-runner-.jar` | The Jetty Runner distribution for EE10/Servlet 6 (`jakarta.servlet`) webapps +| `jetty-12.0.x` | `jetty-ee9/jetty-ee9-runner/target/jetty-ee9-runner-.jar` | The Jetty Runner distribution for EE9/Servlet 5 (`jakarta.servlet`) webapps +| `jetty-12.0.x` | `jetty-ee8/jetty-ee8-runner/target/jetty-ee8-runner-.jar` | The Jetty Runner distribution for EE8/Servlet 4 (`javax.servlet`) webapps +| `jetty-11.0.x` | `jetty-runner/target/jetty-runner-.jar` | The Jetty Runner distribution for EE9/Servlet 5 (`jakarta.servlet`) webapps +| `jetty-10.0.x` | `jetty-runner/target/jetty-runner-.jar` | The Jetty Runner distribution for EE8/Servlet 4 (`javax.servlet`) webapps +|== diff --git a/contribution-guide/modules/ROOT/pages/documentation/index.adoc b/contribution-guide/modules/ROOT/pages/documentation/index.adoc new file mode 100644 index 0000000..d0776af --- /dev/null +++ b/contribution-guide/modules/ROOT/pages/documentation/index.adoc @@ -0,0 +1,273 @@ +// +// ==================================== +// 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 +// ==================================== +// + +:ee-all: ee{8,9,10} +:ee-current: ee12 +:ee-current-caps: EE 12 + +[[cg-documentation]] += Writing Documentation + +Another great way to contribute to Jetty is to help us write and maintain our documentation. + +[[cg-documentation-guides]] +== Documentation guides +Jetty's documentation is grouped into three guides, each written for a different target audience. + +Operations Guide:: +Targets sysops, devops, and developers who want to run Jetty as a standalone web server. + +Programming Guide:: +Targets developers who want to use the Jetty libraries in their applications. + +Contribution Guide:: +Targets developers and writers who want to make contributions to the Jetty project. + +[[cg-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-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. + +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-documentation-asciidoctor]] +== Maven and Asciidoctor + +TODO UPDATE FOR ANTORA + +In addition to using Maven to link: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 the https://docs.asciidoctor.org/maven-tools/latest/[`asciidoctor-maven-plugin`]. + +[[cg-documentation-build]] +== Building the docs + +TODO UPDATE FOR ANTORA + + +Since Jetty's docs are maintained in `git` alongside the rest of the Jetty codebase, you'll need to link: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 clean install` from the `documentation/jetty-documentation` subdirectory. + +[source, shell] +---- +$ 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-build-structure]] +== Documentation project structure + +TODO UPDATE FOR ANTORA + + +The documentation root is https://github.com/eclipse/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation[`documentation/jetty-documentation/`]. +Within this root directory are some files and subdirectories of note: + +https://github.com/eclipse/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation/src/main/asciidoc[`src/main/asciidoc`]:: +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 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 xref: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. + +`target/`:: +The final build destination for any docs generated by Maven. +By default, docs are generated into `target/html`, but other formats (e.g., `pdf` and `epub`) are available. +This directory is not checked into `git`. + +[[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-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*. +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]. + +This practice makes for more readable file diffs, and also makes it easier to comment out individual lines or to move sentences around. + +[TIP] +== +AsciiDoc treats a single line breaks just like a space, so it will render ventilated prose naturally. +== + +[[cg-documentation-versions]] +== Documenting versions + +[[cg-documentation-versions-multiple]] +=== Documenting multiple versions at once + +TODO UPDATE FOR ANTORA AND FORTHCOMING EE11 + +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-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 `{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-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, typically the latest (currently `{ee-current}`): + +[source,subs="verbatim,attributes"] +---- +$ java -jar $JETTY_HOME/start.jar --add-modules={ee-current}-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 doing so isn't strictly necessary for a simple example like above. +== + +[[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: + +---- +// +// ==================================== +// 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-asciidoc-conventions]] +== AsciiDoc conventions + +TODO UPDATE FOR ANTORA + + +[[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. + +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-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=145] +---- + +image::small_powered_by.gif[image,width=145] + +[[cg-documentation-asciidoc-conventions-admonitions]] +== Admonitions + +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]` +* `[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. +== diff --git a/contribution-guide/modules/ROOT/pages/eca/index.adoc b/contribution-guide/modules/ROOT/pages/eca/index.adoc new file mode 100644 index 0000000..ecfcbc5 --- /dev/null +++ b/contribution-guide/modules/ROOT/pages/eca/index.adoc @@ -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. + +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. +http://wiki.eclipse.org/Development_Resources/Contributing_via_Git[Follow the instructions on the Eclipse wiki] for details on how to create your account and sign the 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 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. diff --git a/contribution-guide/modules/ROOT/pages/index.adoc b/contribution-guide/modules/ROOT/pages/index.adoc index 11b68e3..981b7fe 100644 --- a/contribution-guide/modules/ROOT/pages/index.adoc +++ b/contribution-guide/modules/ROOT/pages/index.adoc @@ -1,5 +1,55 @@ -= Contribution Guide +// +// ==================================== +// 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 +// ==================================== +// -== Introduction += Participation and Contribution 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-intro-mailing-lists]] +== Mailing Lists + +One of the easiest ways to get involved is via our mailing lists: + +* *Jetty Users* (https://accounts.eclipse.org/mailing-list/jetty-users[jetty-users], https://www.eclipse.org/lists/jetty-users[archives]) is for discussion and questions that are of broad interest to the community of Jetty users. +* *Jetty Developers* (https://accounts.eclipse.org/mailing-list/jetty-dev[jetty-dev], https://www.eclipse.org/lists/jetty-dev[archives]) is more narrowly focused on technical topics and discussion regarding Jetty internals. +* *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-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-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]. + +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-intro-help-wanted]] +== Help Wanted +If you want to contribute to Jetty but don't have a specific task or goal in mind, consider looking through our https://github.com/eclipse/jetty.project/issues?q=is%3Aopen+is%3Aissue+label%3A%22Help+Wanted%22["Help Wanted" issue backlog]. +These tasks range from the simple to the complex, but they're all ones we've identified as being particularly well-suited for new contributors to tackle. + + +[[cg-intro-commercial-support]] +== Commercial Support +link:https://webtide.com[Webtide] is the company behind Jetty that provides services and support for the Jetty Project. + +mailto:sales@webtide.com[Contact Webtide]. + diff --git a/contribution-guide/modules/ROOT/pages/patches/index.adoc b/contribution-guide/modules/ROOT/pages/patches/index.adoc new file mode 100644 index 0000000..3111e07 --- /dev/null +++ b/contribution-guide/modules/ROOT/pages/patches/index.adoc @@ -0,0 +1,67 @@ +// +// ==================================== +// 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-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-patches-git-config]] +== Configuring `git` + +The email in your git commits must match the email you used to link: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-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 # *: + +[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-patches-git-commit-signing]] +== Signing the commit + +You should sign off on every commit in your pull request using git's https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff[signoff] feature (`git commit -s`). + +[[cg-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-patches-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. diff --git a/contribution-guide/modules/ROOT/pages/security/index.adoc b/contribution-guide/modules/ROOT/pages/security/index.adoc new file mode 100644 index 0000000..cef95c5 --- /dev/null +++ b/contribution-guide/modules/ROOT/pages/security/index.adoc @@ -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]. +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 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]. + +* 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. diff --git a/contribution-guide/modules/ROOT/pages/source/index.adoc b/contribution-guide/modules/ROOT/pages/source/index.adoc new file mode 100644 index 0000000..db1359e --- /dev/null +++ b/contribution-guide/modules/ROOT/pages/source/index.adoc @@ -0,0 +1,49 @@ +// +// ==================================== +// 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-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: + +---- +git clone https://github.com/eclipse/jetty.project.git +---- + +[[cg-source-repositories]] +== Related repositories + +In addition to the https://github.com/eclipse/jetty.project[Jetty code repository], we maintain a number of related repositories: + +Non-Eclipse Jetty Repositories:: https://github.com/jetty-project +Build Toolchain:: https://github.com/eclipse/jetty.toolchain + +[[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 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] | link:https://github.com/eclipse/jetty.project/issues/7958[End of Community Support] | Servlet 3.1 | Java 8+ +|== + +Maintenance branches are periodically merged into active development branches. + +Older branches are only updated if they get specifically targeted by a pull request. +Also, changes to older branches aren't regularly merged forward -- although an individual change may be cherry-picked forward, depending on the nature of the fix. diff --git a/contribution-guide/modules/ROOT/pages/standards/index.adoc b/contribution-guide/modules/ROOT/pages/standards/index.adoc new file mode 100644 index 0000000..8624a9e --- /dev/null +++ b/contribution-guide/modules/ROOT/pages/standards/index.adoc @@ -0,0 +1,133 @@ +// +// ==================================== +// 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 +This section outlines the various coding conventions and standards we use throughout the Jetty codebase. + +[[cg-code-standards-ide]] +== Configuring your IDE + +IntelliJ IDE:: +An IntelliJ 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-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 https://www.jetbrains.com/help/idea/configuring-code-style.html#import-export-schemes[IntelliJ's documentation] to import these settings into your IDE. + +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-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 + */ +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 fields with one underscore (_). This + // convention is not mandatory, but the chosen style + // should be used consistently within a single class. + private Object _privateField; + + // Use getters and setters rather than public fields. + // Braces always on new line. + public void setPrivateField(Object privateField) + { + _privateField = privateField; + } + + public Object getPrivateField() + { + return _privateField; + } + + public void doSomething() throws SomeException + { + Object local_variable = _privateField; + // Braces always on new line. + if (local_variable = null) + { + // do Something + } + } +} +---- + +[[cg-code-standards-logging]] +== 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 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 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); +} +---- +* 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, 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) +{ + 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 but not the stack trace, you need to do call `.toString()` on the caught exception, e.g., `LOG.warn("Something happened {}", t.toString())`. +==