additional pass of edits
Signed-off-by: Greg Poulos <eclipse@gregpoulos.com>
This commit is contained in:
Greg Poulos
Simone Bordet
parent
02fc4392cc
commit
ecf8795aef
|
|
@ -14,36 +14,35 @@
|
|||
[[cg-intro]]
|
||||
== Introduction
|
||||
|
||||
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.
|
||||
The Eclipse Jetty Contribution Guide targets developers and writers who want to make contributions to the Jetty project by contributing code, writing documentation, or engaging in the larger community.
|
||||
|
||||
[[cg-mailing-lists]]
|
||||
=== 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])
|
||||
* *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-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].
|
||||
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.
|
||||
You can flag potential bugs or suggest new Jetty features on our https://github.com/eclipse/jetty.project/issues[issue tracker].
|
||||
|
||||
:icons: font
|
||||
[WARNING]
|
||||
====
|
||||
Note that the issue tracker is **not** 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>>.
|
||||
Note that the issue tracker is **not** meant as a standard support channel.
|
||||
For individualized help, you'll have more success on the <<cg-mailing-lists,mailing lists>> or posting your question to <<cg-stack-overflow,Stack Overflow>>.
|
||||
====
|
||||
|
||||
Before filing a new issue, https://github.com/eclipse/jetty.project/issues[check the tracker] to see if it's already been filed by someone else.
|
||||
|
|
@ -52,4 +51,5 @@ If you do file an issue, make sure to label it appropriately, as this will help
|
|||
|
||||
[[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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -15,10 +15,10 @@
|
|||
== 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.
|
||||
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
|
||||
|
|
@ -26,5 +26,5 @@ Before you set up your local development environment, we recommend creating an a
|
|||
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.
|
||||
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**.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
[[cg-getting-source]]
|
||||
== Getting the source code
|
||||
|
||||
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].
|
||||
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:
|
||||
|
||||
|
|
@ -24,18 +24,17 @@ git clone https://github.com/eclipse/jetty.project.git
|
|||
----
|
||||
|
||||
[[cg-repositories]]
|
||||
=== Primary and secondary repositories
|
||||
=== Secondary repositories
|
||||
|
||||
As well as the primary Jetty code repository, we maintain a number of secondary repos for project-related code and metadata.
|
||||
In addition to the https://github.com/eclipse/jetty.project[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.
|
||||
If you plan to work on a specific issue within Jetty, make sure to target the correct branch for your pull request.
|
||||
|
||||
.Active and inactive Jetty branches
|
||||
[cols="4"]
|
||||
|
|
@ -49,8 +48,8 @@ If you are planning on working with a specific issue within Jetty it is importan
|
|||
| jetty-7 | Mythical | Servlet 2.5 | Java 5
|
||||
|===
|
||||
|
||||
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.
|
||||
Maintenance branches are periodically merged wholesale into active development branches.
|
||||
As such, *changes to maintenance branches should typically be forward compatible* with later releases.
|
||||
|
||||
Older branches remain untouched unless specifically targeted by a pull request.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -14,13 +14,13 @@
|
|||
[[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).
|
||||
Jetty's uses http://maven.apache.org/[Apache Maven] for builds.
|
||||
To successfully build the project, you will also need a recent version of the https://www.oracle.com/java/technologies/downloads/[Java Development Kit (JDK)].
|
||||
|
||||
[[cg-maven-jdk-requirements]]
|
||||
=== Maven and JDK requirements
|
||||
|
||||
Here are the minimum Maven and JDK version build requirements for each of the actively maintained branches of Jetty.
|
||||
Here are the minimum Maven and JDK version build requirements for each actively maintained branch.
|
||||
|
||||
.Build versioning requirements by branch
|
||||
[cols="4"]
|
||||
|
|
@ -35,13 +35,11 @@ Here are the minimum Maven and JDK version build requirements for each of the ac
|
|||
[[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`.
|
||||
To get started with Jetty as quickly as possible, navigate to your local copy of the Jetty repo and run:
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
$ git clone https://github.com/eclipse/jetty.project.git
|
||||
$ cd jetty.project
|
||||
$ mvn -Pfast clean install
|
||||
mvn -Pfast clean install
|
||||
----
|
||||
|
||||
The `-Pfast` flag tells Maven to bypass running tests and other checks.
|
||||
|
|
@ -49,16 +47,15 @@ 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:
|
||||
To build Jetty and automatically run all tests, run:
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
$ git clone https://github.com/eclipse/jetty.project.git
|
||||
$ cd jetty.project
|
||||
$ mvn install
|
||||
mvn install
|
||||
----
|
||||
|
||||
The full Jetty build runs hundreds of test cases, many of which spin up embedded instances of Jetty itself.
|
||||
The full build takes substantial time and memory, as it runs hundreds of test cases -- many of which spin up embedded instances of Jetty itself.
|
||||
|
||||
The build also runs stress tests that may require you (depending on your hardware or operating system) to set you file descriptor limit to a value greater than 2048.
|
||||
You can view or set your file descriptor limit by running `ulimit -n [new_value]`.
|
||||
|
||||
|
|
@ -73,11 +70,18 @@ You can help us track these flaky tests by opening an https://github.com/eclipse
|
|||
=== 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.
|
||||
This behavior is configurable via flags passed to Maven, like so:
|
||||
|
||||
-Djunit.jupiter.execution.parallel.enabled:: Set to `false` to disable parallel execution of tests, like so:
|
||||
[source, shell]
|
||||
----
|
||||
mvn install -Djunit.jupiter.execution.parallel.enabled=false
|
||||
----
|
||||
|
||||
mvn install -Djunit.jupiter.execution.parallel.enabled=false
|
||||
Here are the available configuration flags:
|
||||
|
||||
`-Djunit.jupiter.execution.parallel.enabled=[BOOLEAN]`:: Disables parallel execution of tests.
|
||||
|
||||
`-Djunit.jupiter.execution.parallel.config.fixed.parallelism=[NUMBER]`:: Configures the number of tests to be executed in parallel.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
|
|
@ -91,18 +95,12 @@ Certain tests cannot be run in parallel because they access or modify `static`
|
|||
Maven will run these tests in isolation even when parallel execution is explicitly enabled.
|
||||
====
|
||||
|
||||
-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
|
||||
|
||||
|
|
|
|||
|
|
@ -13,26 +13,25 @@
|
|||
|
||||
[[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!
|
||||
This section outlines the various coding conventions and standards we use throughout the Jetty codebase.
|
||||
|
||||
[[cg-ide-configuration]]
|
||||
=== Configuring your IDE
|
||||
|
||||
IntelliJ IDE::
|
||||
An IntelliJ code style XML file is available in the Jetty code tree at
|
||||
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 the https://www.jetbrains.com/help/idea/configuring-code-style.html#import-export-schemes[IntelliJ documentation] to apply these code style settings locally.
|
||||
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 can be found in the code tree
|
||||
An Eclipse code style XML file is available in the source repo at
|
||||
https://github.com/eclipse/jetty.project/blob/jetty-10.0.x/build-resources/jetty-codestyle-eclipse-ide.xml[`/build-resources/jetty-codestyle-eclipse-ide.xml`].
|
||||
|
||||
[[cg-java-conventions]]
|
||||
=== Java conventions
|
||||
|
||||
The following sample code shows the basic Java styles and conventions used throughout the Jetty codebase:
|
||||
The following code sample shows some basic Java styles and conventions used throughout the Jetty codebase:
|
||||
|
||||
[source, java]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -17,42 +17,41 @@
|
|||
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.
|
||||
|
||||
<<og-intro,Operations Guide>>::
|
||||
The Operations Guide targets sysops, devops, and developers who want to run Jetty as a standalone web server.
|
||||
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.
|
||||
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.
|
||||
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/`].
|
||||
Jetty follows a https://www.writethedocs.org/guide/docs-as-code/["docs as code"] philosophy, meaning *we use the same tools to write and build our code and docs*.
|
||||
As such, the docs are maintained directly within the Jetty codebase at https://github.com/eclipse/jetty.project/tree/jetty-12.0.x/documentation/jetty-documentation/src/main/asciidoc[`documentation/jetty-documentation/src/main/asciidoc/`].
|
||||
|
||||
[[cg-asciidoc]]
|
||||
==== AsciiDoc
|
||||
Jetty's documentation is written in https://asciidoc.org/[AsciiDoc], a markup language for writing technical content.
|
||||
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-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.
|
||||
In addition to using Maven to <<cg-building-jetty,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 is integrated with Asciidoctor via the https://docs.asciidoctor.org/maven-tools/latest/[`asciidoctor-maven-plugin`].
|
||||
Maven integrates with Asciidoctor via a plugin called (appropriately enough) https://docs.asciidoctor.org/maven-tools/latest/[`asciidoctor-maven-plugin`].
|
||||
|
||||
[[cg-documentation-build]]
|
||||
==== Building the docs
|
||||
=== 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.
|
||||
|
||||
|
|
@ -61,7 +60,6 @@ To do so, run `mvn install` from the `documentation/jetty-documentation` subdire
|
|||
|
||||
[source, screen]
|
||||
----
|
||||
$ git clone https://github.com/eclipse/jetty.project.git
|
||||
$ cd jetty.project/documentation
|
||||
$ mvn install
|
||||
<...snip...>
|
||||
|
|
@ -86,16 +84,13 @@ When the build completes, you can view the generated docs in your preferred web
|
|||
[[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/`].
|
||||
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:
|
||||
|
||||
`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`::
|
||||
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.
|
||||
|
||||
`src/main/asciidoc/config.adoc`::
|
||||
https://github.com/eclipse/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation/src/main/asciidoc/config.adoc[`src/main/asciidoc/config.adoc`]::
|
||||
This file contains metadata and global variables shared across all the <<cg-documentation-guides,documentation guides>>.
|
||||
This configuration is used by Asciidoctor to correctly render the final docs.
|
||||
|
||||
|
|
@ -107,33 +102,39 @@ 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/<format>`::
|
||||
The final build destination for any docs generated by Maven.
|
||||
By default, docs are generated into `target/html`, but other formats (e.g., `pdf` and `epub`) are available.
|
||||
This directory is not checked into git.
|
||||
|
||||
|
||||
[[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.
|
||||
Stylistically consistency helps keep the docs easy 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.
|
||||
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
|
||||
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-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*.
|
||||
Use subsections to flag major changes in functionality between versions of Jetty.
|
||||
The subsection's title should specifically note the relevant version(s) -- e.g., _Prior to: Version X.Y_ or _In version: X.Y_.
|
||||
|
||||
For minor differences in functionality, a `[NOTE]` or `[WARNING]` <<cg-admonitions,admonition>> may be sufficient.
|
||||
|
||||
|
|
@ -141,34 +142,36 @@ For minor differences in functionality, a `[NOTE]` or `[WARNING]` <<cg-admonitio
|
|||
[[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.
|
||||
Jetty 12 features many parallel modules with similar names and functionality, but which target different versions of Jakarta EE.
|
||||
For instance, the `ee8-deploy`, `ee9-deploy`, and `ee10-deploy` modules all behave similarly, except they target Jakarta EE8, EE9, and EE10, respectively.
|
||||
|
||||
Whenever possible, *try to consolidate these types of parallel references*.
|
||||
For instance, you can quickly refer to all three of the aforementioned modules as a group by writing `ee{8,9,10}-deploy`, `eeN-deploy`, or even just `ee-deploy`.
|
||||
|
||||
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.
|
||||
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 typically use the most recent version number (i.e., `ee10-deploy`).
|
||||
When targeting a specific version in your docs for demonstration purposes, you should prefer to use the most recent version number.
|
||||
For the example above, this would mean targeting `ee10-deploy`.
|
||||
====
|
||||
|
||||
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.
|
||||
|
||||
Consolidating parallel references saves readers from having to sift through repetitive material, and helps us avoid maintaining multiple versions of nearly identical docs.
|
||||
|
||||
[[cg-documenting-versions-in-examples]]
|
||||
===== 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.
|
||||
Instead of referencing multiple versions in your code and command-line examples, it's generally better to target one specific version.
|
||||
For example, let's say you're telling the reader how to install the `ee-deploy` family of modules:
|
||||
|
||||
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-deploy
|
||||
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=ee{8,9,10}-deploy
|
||||
Any reader who copy-pastes the above into their command line will get a failure:
|
||||
|
||||
However, any reader who copy-pastes the above into their command line will get a failure.
|
||||
[source,options=nowrap,subs=attributes]
|
||||
----
|
||||
include::jetty[args="--add-modules=ee-deploy"]
|
||||
----
|
||||
|
||||
Instead, target the `ee10-deploy` module specifically:
|
||||
|
||||
|
|
@ -178,7 +181,7 @@ 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.
|
||||
You may want to remind the reader to change the `10` in the command to their preferred target version -- although doing so isn't strictly necessary for a simple example like above.
|
||||
====
|
||||
|
||||
[[cg-license-blocks]]
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ See link:https://help.github.com/articles/setting-your-email-in-git[this guide]
|
|||
==== 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:
|
||||
Specifically, the message should follow the form *Issue #<XXX> <description of the commit>*:
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@
|
|||
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.
|
||||
Since Webtide comprises the active committers of the Jetty project, this is our preferred reporting method.
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
|
|
@ -27,6 +27,6 @@ We prefer you report any security issues directly to the Jetty developers mailto
|
|||
* 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.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue