<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Documentation</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="advanced-contributing.html" title="Chapter&nbsp;35.&nbsp;Contributing to Jetty"><link rel="prev" href="advanced-contributing.html" title="Chapter&nbsp;35.&nbsp;Contributing to Jetty"><link rel="next" href="contributing-source-build.html" title="Source Control and Building"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script>
      hljs.initHighlightingOnLoad();
    </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
            Version: 9.4.28-SNAPSHOT</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Documentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="advanced-contributing.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;35.&nbsp;Contributing to Jetty<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="contributing-source-build.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
          <span class="website">www.webtide.com</span></a></h5><p>
 private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ...
 scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="contributing-documentation"></a>Documentation</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="contributing-documentation.html#_tools">Tools</a></span></dt><dt><span class="section"><a href="contributing-documentation.html#_render_chain">Render Chain</a></span></dt><dt><span class="section"><a href="contributing-documentation.html#_getting_started_cli">Getting Started (cli)</a></span></dt><dt><span class="section"><a href="contributing-documentation.html#_making_changes">Making Changes</a></span></dt><dt><span class="section"><a href="contributing-documentation.html#_conventions">Conventions</a></span></dt><dt><span class="section"><a href="contributing-documentation.html#_oddities">Oddities</a></span></dt></dl></div><p>This document is produced using a combination of maven, git, and asciidoc.
We welcome anyone and everyone to contribute to the content of this book.
Below is the information on how to obtain the source of this book and to build it as well as information on how to contribute back to it.</p><p>Note: All contributions to this documentation are under the EPLv1 and the copyright is assigned to Mort Bay.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_tools"></a>Tools</h3></div></div></div><p>You will need:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">git</span></dt><dd><p class="simpara">This documentation is part of the Jetty project so all contributions must be through the normal Jetty contribution process.</p><p class="simpara">You can go one of two ways for using git, if you are familiar with SCM&#8217;s and the command line interface feel free to install and use git from there.
Otherwise we would recommend you use the github client itself as it will help with some of the workflow involved with working with git.
All contributions much be signed and can be pulled into Jetty through the normal pull request process.</p></dd><dt><span class="term">maven 3</span></dt><dd>We build the documentation with maven 3 which can be found at <a class="link" href="http://maven.apache.org" target="_top">Apache Maven</a>.</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_render_chain"></a>Render Chain</h3></div></div></div><p>The Jetty documentation is all written in asciidoc which is used as the origin format.
The maven build uses the asciidoctor-maven-plugin to process all of the .adoc files into a single docbook file which is then used to produce the final output.
We use this intermediary step in order to primarily produce chunked html which we then deploy to the Eclipse Jetty website.
However we can also use this docbook output to produce pdf files, epub books or even Eclipse Help files should we so desire.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_getting_started_cli"></a>Getting Started (cli)</h3></div></div></div><p>First you need to obtain the source of the documentation project.</p><p>Clone the repository:</p><div class="screenexample"><pre class="screen">$ git clone https://github.com/eclipse/jetty.project.git</pre></div><p>You will now have a local directory with all of jetty, including the jetty-documentation.
Now we move on to building it.</p><div class="screenexample"><pre class="screen">$ cd jetty.project/jetty-documentation
$ mvn install</pre></div><p>While maven is running you may see a lot of files being downloaded.
If you are not familiar with maven, then what you are seeing is maven setting up the execution environment for generating the documentation.
This build will first produce docbook xml and then through the docbkx-maven-plugin generate the chunked html output.
The downloads are all of the java dependencies that are required to make this build work.
After a while the downloading will stop and you should see the execution of the asciidoctor-maven-plugin followed by the docbkx-maven-plugin.</p><div class="screenexample"><pre class="screen">[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (output-html) @ jetty-documentation ---
[INFO] Rendered /Users/jesse/src/projects/jetty/jetty-docs/src/main/asciidoc/index.adoc
[INFO]

[INFO] Processing input file: index.xml
[INFO] Applying customization parameters
[INFO] Chunking output.
[INFO] See /Users/jesse/src/projects/jetty/jetty-docs/target/docbkx/html/index for generated file(s)</pre></div><p>The build is finished once you see a message akin to this:</p><div class="screenexample"><pre class="screen">[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7.014s
[INFO] Finished at: Tue Oct 25 14:15:37 CDT 2011
[INFO] Final Memory: 14M/229M
[INFO] ------------------------------------------------------------------------</pre></div><p>You may now open your web browser and browse to the first page of the html output to see what you have produced!
Generally you can do this with File &#8594; Open File &#8594; which will open a file system browsing screen, navigate to your jetty-documentation directory and then further into target/docbkx/html/index/index.html which is the first page of the produced documentation.</p><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-lightbulb-o" aria-hidden="true"></i> Tip</h3><p>If the build is broken, feel free to notify us.</p></div></blockquote></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_making_changes"></a>Making Changes</h3></div></div></div><p>Now that you have built the documentation, you want to edit it and make some changes.
We&#8217;ll now have to take a bit of as step back and look at how git and github works.
In the above example you have cloned directly from our canonical documentation repository.
Obviously we can not allow anyone immediate access to this repository so you must make a fork of it for your own and then issue back pull requests to build up documentation karma.
In English that means that you would go to the url of the documentation in github:</p><pre class="literallayout">https://github.com/eclipse/jetty.project</pre><p>When you are on this page you will see a little button called <span class="emphasis"><em>Fork</em></span> which you can click and you will be taken back to your main page on github where you have a new repository.
When you checkout this repository you are free to commit to your heart&#8217;s delight all the changes you so direly wish to see in the Jetty documentation.
You can clone it to your local machine and build it the same way as above.
So let&#8217;s start small with a little example.
Find some paragraph in the documentation that you think needs changed. Locate that in the local checkout and make the change.
Now follow the process to push that change back into Jetty proper.
Do make sure the change works and the build isn&#8217;t broken though so make sure you run maven and check the output.
Then commit the change.</p><div class="screenexample"><pre class="screen">$ git commit -s -m "Tweaked the introduction to fix a horrid misspelled word." src/main/asciidoc/quickstart/introduction/topic.xml</pre></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>In order for us to accept your commit into the Jetty repository you must have an Eclipse CLA on file and sign your commit.
Please check out the patches section for more information.</p></div></blockquote></div><p>This will commit the change in your local repository.
You can then push the change up to your repository on github.</p><div class="screenexample"><pre class="screen">$ git push</pre></div><p>Now you&#8217;ll see some output showing that your change has been propagated to your repository on github.
In fact if you navigate to that repository at the top of the files list you should see your comment there.
Success, your change is now positioned for notifying us about it!
If you click on the commit message itself you&#8217;ll be taken to a screen that shows what files were changed in that commit. In the upper right corner is a button for <span class="emphasis"><em>Pull Request</em></span>.
When you select this and follow the workflow we will then be notified of your contribution and will be able to apply it to our git repository upon review.</p><p>Thats it! You have successfully contributed to the documentation efforts of the Jetty project.
After enough of these sorts of contributions and building up good community karma, you may be asked to join us as a committer on the documentation.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_conventions"></a>Conventions</h3></div></div></div><p>Below is list of conventions that should be followed when developing documentation within this framework.
These are not set in stone and should be updated as we learn more.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">ventilated prose</span></dt><dd>Each sentence should 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 scm 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.</dd><dt><span class="term">id&#8217;s</span></dt><dd><p class="simpara">Critically important for being able to generate url&#8217;s that can be used in a persistent fashion.
Without sane id&#8217;s the chapters and sections will have generated id which are rooted in some obscure location based
voodoo.
A url using these <span class="emphasis"><em>e12c8673</em></span> type links will not be durable across generations of the documentation.
These id&#8217;s need to be used on chapters and sections two deep, and anywhere that you intend to cross link deeper.</p><p class="simpara">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.
Below is an example of an id.</p></dd></dl></div><pre class="literallayout">[[this-id-an-id]]</pre><div class="variablelist"><dl class="variablelist"><dt><span class="term">link vs xref</span></dt><dd>The <code class="literal">link:</code> 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 <code class="literal">xref:</code> tag without the hashmark in front of the link id.</dd><dt><span class="term">version differences</span></dt><dd>In general differences in functionality within a release should go into nested sections and use titles like <span class="emphasis"><em>Prior to: <span class="marked"></span> or <span class="emphasis"><em>In version: </em></span></em></span>.</dd><dt><span class="term">license blocks</span></dt><dd>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.</dd></dl></div><pre class="literallayout">//
//  ========================================================================
//  Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================
//</pre><p>Some admonition examples:</p><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>A note about the previous case to be aware of.</p></div></blockquote></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-plus" aria-hidden="true"></i> Important</h3><p>Important notes are marked with an icon.</p></div></blockquote></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-lightbulb-o" aria-hidden="true"></i> Tip</h3><p>Tips that make your life easier.</p></div></blockquote></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-exclamation" aria-hidden="true"></i> Caution</h3><p>Places where you have to be careful what you are doing.</p></div></blockquote></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-exclamation-triangle" aria-hidden="true"></i> Warning</h3><p>Where extreme care has to be taken. Data corruption or other nasty
things may occur if these warnings are ignored.</p></div></blockquote></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_oddities"></a>Oddities</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">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.</li></ul></div></div></div><script type="text/javascript">
      SyntaxHighlighter.all()
    </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="advanced-contributing.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="advanced-contributing.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="contributing-source-build.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;35.&nbsp;Contributing to Jetty&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Source Control and Building</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
            See an error or something missing?
            <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at
                <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2020-03-10)</i></span></div></p></body></html>