| <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 35. Contributing to Jetty"><link rel="prev" href="advanced-contributing.html" title="Chapter 35. 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.3.28.v20191105</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> </td><th width="60%" align="center">Chapter 35. 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"> <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’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 → Open File → 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’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’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’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’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 <a class="link" href="contributing-patches.html#contributing-cla" title="Sign a CLA">patches</a> 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’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’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’s</span></dt><dd><p class="simpara">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 <span class="emphasis"><em>e12c8673</em></span> 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.</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-2018 Mort Bay Consulting Pty. Ltd. |
| // ======================================================================== |
| // 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> </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"> <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 35. Contributing to Jetty </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"> 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: 2019-11-05)</i></span></div></p></body></html> |
