| <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-NS Stylesheets V1.76.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 : The Definitive Reference"><link rel="up" href="advanced-contributing.html" title="Chapter 33. Contributing to Jetty"><link rel="prev" href="advanced-contributing.html" title="Chapter 33. 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"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/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.0.v20150612</span></td><td style="width: 50%"><script type="text/javascript"> (function() { |
| var cx = '016459005284625897022:obd4lsai2ds'; |
| var gcse = document.createElement('script'); |
| gcse.type = 'text/javascript'; |
| gcse.async = true; |
| gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + |
| '//www.google.com/cse/cse.js?cx=' + cx; |
| var s = document.getElementsByTagName('script')[0]; |
| s.parentNode.insertBefore(gcse, s); |
| })(); |
| </script><gcse:search></gcse:search></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="icon-chevron-left"></i> Previous</a> </td><th width="60%" align="center">Chapter 33. Contributing to Jetty<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="contributing-source-build.html">Next <i class="icon-chevron-right"></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 from 1 day to full product delivery |
| </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><dt><span class="section"><a href="contributing-documentation.html#d0e23291">Tools</a></span></dt><dt><span class="section"><a href="contributing-documentation.html#d0e23315">Getting Started (cli)</a></span></dt><dt><span class="section"><a href="contributing-documentation.html#d0e23341">Making Changes</a></span></dt><dt><span class="section"><a href="contributing-documentation.html#d0e23361">Conventions</a></span></dt></dl></div><p>This document is produced using a combination of maven, git, and |
| docbook. 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 EPL and |
| the copyright is assigned to Mortbay.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e23291"></a>Tools</h3></div></div></div><p>You will need:</p><div class="variablelist"><dl><dt><span class="term">git</span></dt><dd><p>This project is located at github so if you do not have a |
| GitHub account already you should register for one. You can do that |
| at <a class="link" href="https://github.com" target="_top">Github</a></p><p>You can go one of two ways for using git, if you are familiar |
| with SCM's and the command line interface then 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.</p></dd><dt><span class="term">maven 3</span></dt><dd><p>We build the project with maven 3 which can be found at <a class="link" href="http://maven.apache.org" target="_top">Apache Maven</a></p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e23315"></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/jetty-project/jetty-documentation.git |
| |
| </pre></div><p>You will now have a local directory with all of the |
| jetty-documentation. Now we move on to building it.</p><div class="screenexample"><pre class="screen"> |
| |
| $ cd 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 should produce xhtml, as well as any other output formats that |
| we are working with as time goes on. 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'll see the execution of the |
| docbkx-maven-plugin.</p><div class="screenexample"><pre class="screen"> |
| |
| [INFO] --- docbkx-maven-plugin:2.0.13:generate-xhtml (documentation identifier) @ jetty-documentation --- |
| [INFO] Processing input file: jetty.xml |
| [INFO] Dumping to /home/jesse/src/projects/jetty/jetty-documentation/target/docbkx/generated/(gen)jetty.xml |
| [INFO] Applying customization parameters |
| [INFO] Chunking output. &lt;?xml version="1.0" encoding="UTF-8"?&gt; |
| [INFO] See /home/jesse/src/projects/jetty/jetty-documentation/target/docbkx/xhtml/jetty for generated file(s) |
| [INFO] Executing tasks |
| [INFO] Executed tasks |
| |
| </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/xhtml/jetty/jetty.html which is the first page of the |
| produced documentation.</p><p><span class="emphasis"><em>Note: if the build is broken, feel free to notify |
| us.</em></span></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e23341"></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><div class="screenexample"><pre class="screen">https://github.com/jetty-project/jetty-documentation</pre></div><p>When you are on this page you will see a little button called 'Fork' |
| 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 -m "Tweaked the introduction to fix a horrid misspelled word." src/docbkbx/topics/introduction/topic.xml |
| |
| </pre></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 'Pull Request'. 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 |
| commiter on the documentation.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e23361"></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><dt><span class="term">build before committing</span></dt><dd><p>We have an xmlfresh maven plugin that reformats the code to |
| the standards for the project. This is to prevent wide spread merge |
| conflict between commits. The line wrap is set to 120 and the indent |
| is 2 spaces, never tab characters. There are a handful of tags that |
| render inline to the para tags, these are found in the maven |
| configuration of the xmlfresh-maven-plugin.</p></dd><dt><span class="term">xml:id</span></dt><dd><p>Critically important for being able to generate url's that can |
| be used in a persistent fashion. Without xml:id's the chapters and |
| sections will have generated id which are rooting in obscure |
| location based voodoo. A url using these 'e12c8673' type links will |
| not be durable across generations of the documentation. These |
| xml:id's need to be used on chapters and sections two deep, and |
| anywhere that you intend to cross link deeper.</p><p>The xml: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. We will have a maven plugin that will |
| fail the build on detecting this soon.</p></dd><dt><span class="term">version differences</span></dt><dd><p>in general differences in functionality within a major should |
| go into nested sections and use titles like 'Prior to: ##' or 'In |
| version: ##'</p></dd><dt><span class="term">license blocks</span></dt><dd><p>each xml file should contain the license block that exists in |
| the jetty.xml file and a copy has been added to the bottom of this |
| page as well for reference. It should occupy the second through |
| eighteeth lines while the first line should be the xml |
| descriptor.</p></dd></dl></div><div class="screenexample"><pre class="screen"> |
| |
| <?xml version="1.0" encoding="utf-8"?> |
| <!-- |
| // ======================================================================== |
| // Copyright (c) 1995-2012 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></div><p>Some admonition examples:</p><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="icon-asterisk"></i> Note</h3><p>A note about the previous case to be aware of.</p></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="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-plus-sign-alt"></i> Important</h3><p>Important notes are marked with an icon.</p></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="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-lightbulb"></i> Tip</h3><p>Tips that make your life easier.</p></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="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-exclamation-sign"></i> Caution</h3><p>Places where you have to be careful what you are doing.</p></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="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-warning-sign"></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></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="icon-chevron-left"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="advanced-contributing.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="contributing-source-build.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 33. Contributing to Jetty </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></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/jetty-project/jetty-documentation">Contribute to this documentation at |
| <span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2015-06-15T13:18:55-05:00)</i></span></div></p><script 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" type="text/javascript"> |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-1149868-7']); |
| _gaq.push(['_trackPageview']); |
| |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| </script></body></html> |
