"Fossies" - the Fresh Open Source Software Archive

Member "developer/source.html" (22 Nov 2019, 48410 Bytes) of package /linux/www/geoserver-2.16.1-htmldoc.zip:


The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    2   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
    4 <head>
    5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    6   
    7   <title>Source Code &mdash; GeoServer 2.16.1 Developer Manual</title>
    8   <link rel="stylesheet" href="_static/blueprint/screen.css" type="text/css" media="screen, projection" />
    9   <link rel="stylesheet" href="_static/blueprint/print.css" type="text/css" media="print" /> 
   10   <!--[if IE]>
   11   <link rel="stylesheet" href="_static/blueprint/ie.css" type="text/css" media="screen, projection" />
   12   <![endif]-->
   13   <link rel="stylesheet" href="_static/default.css" type="text/css" />
   14   <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
   15   <script type="text/javascript">
   16     var DOCUMENTATION_OPTIONS = {
   17         URL_ROOT:    './',
   18         VERSION:     '2.16.1',
   19         COLLAPSE_MODINDEX: false,
   20         FILE_SUFFIX: '.html'
   21     };
   22   </script>
   23   <script type="text/javascript" src="_static/jquery.js"></script>
   24   <script type="text/javascript" src="_static/doctools.js"></script>
   25   <script type="text/javascript" src="_static/searchtools.js"></script>
   26   <script type="text/javascript" src="searchindex.js"></script>
   27   <link rel="shortcut icon" href="_static/geoserver.ico"/>
   28       <link rel="search" title="Search" href="search.html" />
   29       <link rel="top" title="GeoServer 2.16.1 Developer Manual" href="index.html" />
   30       <link rel="next" title="Quickstart" href="quickstart/index.html" />
   31       <link rel="prev" title="Tools" href="tools.html" />
   32 </head>
   33 <body class="source">
   34   <div id="header" class="selfclear">
   35     <div class="wrap selfclear">
   36       <div id="logo"><a href="index.html">GeoServer 2.16.1 Developer Manual</a></div>
   37       <ul id="top-nav">
   38         <li class="first"><a href="http://geoserver.org/about">About</a></li>
   39         <li><a href="http://blog.geoserver.org/">Blog</a></li>
   40         <li><a href="http://geoserver.org/download">Download</a></li>
   41         <!--<li><a href="index.html">Documentation</a></li>-->
   42       </ul>
   43         <form id="quick-search" action="search.html" method="get">
   44           <fieldset>
   45             <input type="hidden" name="check_keywords" value="yes" />
   46             <input type="hidden" name="area" value="default" />
   47             <input id="quick-search-query" type="text" name="q" accessKey="q" name="searchQuery.queryString" size="25" value="Search Documentation&hellip;" size="20" tabindex="3" onblur="if(this.value=='') this.value='Search Documentation&hellip;';" onfocus="if(this.value=='Search Documentation&hellip;') this.value='';" />
   48             <input id="quick-search-submit" type="image" value="Search" src="_static/chrome/search_icon_green.png" />
   49           </fieldset>
   50         </form>
   51     </div><!-- /.wrap -->
   52   </div><!-- /#header -->
   53   <div id="main">
   54     <div class="wrap selfclear">
   55       <div id="content-left" class="content-border"></div>
   56       <div id="content">
   57 <ul id="breadcrumbs">
   58   
   59   <li><a href="index.html">GeoServer 2.16.1 Developer Manual</a> &raquo;</li>
   60   <li>Source Code</li>
   61 </ul>
   62 <ul id="relatedlinks" class="selfclear">
   63   <li class="first">
   64     <a href="quickstart/index.html" title="Quickstart"
   65        accesskey="N">next</a></li>
   66   <li>
   67     <a href="tools.html" title="Tools"
   68        accesskey="P">previous</a>|</li>
   69 </ul>
   70         
   71   <div class="section" id="source-code">
   72 <span id="source"></span><h1>Source Code<a class="headerlink" href="#source-code" title="Permalink to this headline"></a></h1>
   73 <p>The GeoServer source code is located on GitHub at <a class="reference external" href="https://github.com/geoserver/geoserver">https://github.com/geoserver/geoserver</a>.</p>
   74 <p>To clone the repository:</p>
   75 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">clone</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">geoserver</span><span class="o">/</span><span class="n">geoserver</span><span class="o">.</span><span class="n">git</span> <span class="n">geoserver</span>
   76 </pre></div>
   77 </div>
   78 <p>To list available branches in the repository:</p>
   79 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">branch</span>
   80    <span class="mf">2.15</span><span class="o">.</span><span class="n">x</span>
   81    <span class="mf">2.16</span><span class="o">.</span><span class="n">x</span>
   82  <span class="o">*</span> <span class="n">master</span>
   83 </pre></div>
   84 </div>
   85 <p>To switch to the 2.16.x branch above:</p>
   86 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="mf">2.16</span><span class="o">.</span><span class="n">x</span>
   87 </pre></div>
   88 </div>
   89 <div class="section" id="git">
   90 <h2>Git<a class="headerlink" href="#git" title="Permalink to this headline"></a></h2>
   91 <p>Git is a distributed version control system with a steep learning curve.
   92 Luckily there is lots of great documentation around. Before continuing developers should take the
   93 time to educate themselves about git. The following are good references:</p>
   94 <ul class="simple">
   95 <li><a class="reference external" href="http://git-scm.com/book/">The Git Book</a></li>
   96 <li><a class="reference external" href="http://www.sbf5.com/~cduan/technical/git/">A nice introduction</a></li>
   97 <li><a class="reference external" href="https://help.github.com/en/articles/about-pull-requests">Git Pull Requests</a></li>
   98 </ul>
   99 </div>
  100 <div class="section" id="git-client-configuration">
  101 <span id="gitconfig"></span><h2>Git client configuration<a class="headerlink" href="#git-client-configuration" title="Permalink to this headline"></a></h2>
  102 <p>To review global settings:</p>
  103 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git config --global --get-regexp core.*
  104 </pre></div>
  105 </div>
  106 <p>On Linux and Windows machines:</p>
  107 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">core</span><span class="o">.</span><span class="n">autocrlf</span> <span class="nb">input</span>
  108 <span class="n">core</span><span class="o">.</span><span class="n">safecrlf</span> <span class="n">true</span>
  109 </pre></div>
  110 </div>
  111 <p>On macOS using decomposed unicode paths, and a default APFS case-insensitive file system:</p>
  112 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">core</span><span class="o">.</span><span class="n">autocrlf</span> <span class="nb">input</span>
  113 <span class="n">core</span><span class="o">.</span><span class="n">safecrlf</span> <span class="n">true</span>
  114 <span class="n">core</span><span class="o">.</span><span class="n">ignorecase</span> <span class="n">false</span>
  115 <span class="n">core</span><span class="o">.</span><span class="n">precomposeunicode</span> <span class="n">true</span>
  116 </pre></div>
  117 </div>
  118 <p>We recommend making these changes to <code class="docutils literal notranslate"><span class="pre">--gloabl</span></code> (or <code class="docutils literal notranslate"><span class="pre">--system</span></code>) as they reflect the operating system and file system on your local machine.</p>
  119 <p>Some useful reading on this subject:</p>
  120 <ul class="simple">
  121 <li><a class="reference external" href="https://git-scm.com/docs/git-config">git config</a> (git)</li>
  122 </ul>
  123 <div class="section" id="line-endings">
  124 <h3>Line endings<a class="headerlink" href="#line-endings" title="Permalink to this headline"></a></h3>
  125 <p>When a repository is shared across different platforms it is necessary to have a
  126 strategy in place for dealing with file line endings. In general git is pretty good about
  127 dealing this without explicit configuration but to be safe developers should set the
  128 <code class="docutils literal notranslate"><span class="pre">core.autocrlf</span></code> setting to “input”:</p>
  129 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git config --global core.autocrlf input
  130 </pre></div>
  131 </div>
  132 <p>The value “input” respects the line ending form as present in the git repository.</p>
  133 <div class="admonition note">
  134 <p class="first admonition-title">Note</p>
  135 <p>It is also a good idea, especially for Windows users, to set the <code class="docutils literal notranslate"><span class="pre">core.safecrlf</span></code>
  136 option to “true”:</p>
  137 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git config --global core.safecrlf <span class="nb">true</span>
  138 </pre></div>
  139 </div>
  140 <p class="last">This will prevent commits that may potentially modify file line endings.</p>
  141 </div>
  142 <p>Some useful reading on this subject:</p>
  143 <ul class="simple">
  144 <li><a class="reference external" href="https://help.github.com/articles/dealing-with-line-endings">Configuring Git to handle line endings</a> (GitHub)</li>
  145 <li><a class="reference external" href="http://stackoverflow.com/questions/170961/whats-the-best-crlf-handling-strategy-with-git">What’s the best CRLF (carriage return, line feed) handling strategy with Git?</a> (Stack Overflow)</li>
  146 <li><a class="reference external" href="https://adaptivepatchwork.com/2012/03/01/mind-the-end-of-your-line/">Mind the end of the End of Your Line</a> (Tim Clem)</li>
  147 </ul>
  148 </div>
  149 <div class="section" id="file-paths">
  150 <h3>File paths<a class="headerlink" href="#file-paths" title="Permalink to this headline"></a></h3>
  151 <p>For those working on non case-sensitive, please keep in mind that our repository is case-sensitive:</p>
  152 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git config --global core.ignorecase <span class="nb">false</span>
  153 </pre></div>
  154 </div>
  155 <p>Take extra care when adding files to prevent problems for others. To correct a file added with the wrong case:</p>
  156 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git mv --cached HttpHandler.java HTTPHandler.java
  157 </pre></div>
  158 </div>
  159 <div class="admonition note">
  160 <p class="first admonition-title">Note</p>
  161 <p>File paths can use two different representations of select unicode characters:</p>
  162 <table border="1" class="docutils">
  163 <colgroup>
  164 <col width="38%" />
  165 <col width="23%" />
  166 <col width="39%" />
  167 </colgroup>
  168 <thead valign="bottom">
  169 <tr class="row-odd"><th class="head">Representation</th>
  170 <th class="head">Example</th>
  171 <th class="head">Operating System Default</th>
  172 </tr>
  173 </thead>
  174 <tbody valign="top">
  175 <tr class="row-even"><td>Precomposed form</td>
  176 <td><code class="docutils literal notranslate"><span class="pre">Ü</span></code></td>
  177 <td>Linux, Windows</td>
  178 </tr>
  179 <tr class="row-odd"><td>Decomposed form</td>
  180 <td><code class="docutils literal notranslate"><span class="pre">U</span></code> + <code class="docutils literal notranslate"><span class="pre">¨</span></code></td>
  181 <td>macOS</td>
  182 </tr>
  183 </tbody>
  184 </table>
  185 <p>Files committed in decomposed form show up as untracked (even with no modification made).</p>
  186 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git status
  187 </pre></div>
  188 </div>
  189 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Untracked</span> <span class="n">files</span><span class="p">:</span>
  190    <span class="p">(</span><span class="n">use</span> <span class="s2">&quot;git add &lt;file&gt;...&quot;</span> <span class="n">to</span> <span class="n">include</span> <span class="ow">in</span> <span class="n">what</span> <span class="n">will</span> <span class="n">be</span> <span class="n">committed</span><span class="p">)</span>
  191 
  192    <span class="o">...</span>
  193 
  194    <span class="s2">&quot;Entit</span><span class="se">\303\251</span><span class="s2">G</span><span class="se">\303\251</span><span class="s2">n</span><span class="se">\303\251</span><span class="s2">rique/&quot;</span>
  195 </pre></div>
  196 </div>
  197 <p>GeoServer requires macOS users to use the following setting:</p>
  198 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git config --global core.precomposeunicode <span class="nb">true</span>
  199 </pre></div>
  200 </div>
  201 <p>This setting converts paths to precomposed form when adding files to the repository.</p>
  202 <p>To fix a file added in decomposed form it must be removed:</p>
  203 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git config --global core.precomposeunicode <span class="nb">false</span>
  204 mv EntitéGénérique /tmp/EntitéGénérique
  205 git rm EntitéGénérique
  206 git commit -m <span class="s2">&quot;Remove EntitéGénérique with decomposed filename&quot;</span>
  207 </pre></div>
  208 </div>
  209 <p>And then added:</p>
  210 <div class="last highlight-bash notranslate"><div class="highlight"><pre><span></span>git config --global core.precomposeunicode <span class="nb">true</span>
  211 mv /tmp/EntitéGénérique EntitéGénérique
  212 git add EntitéGénérique
  213 git commit -m <span class="s2">&quot;Restore EntitéGénérique with precomposed filename&quot;</span>
  214 </pre></div>
  215 </div>
  216 </div>
  217 <p>Some useful reading on this subject:</p>
  218 <ul class="simple">
  219 <li><a class="reference external" href="https://www.git-tower.com/help/mac/faq-and-tips/faq/unicode-filenames">Untracked filenames with unicode names</a></li>
  220 </ul>
  221 </div>
  222 </div>
  223 <div class="section" id="committing">
  224 <h2>Committing<a class="headerlink" href="#committing" title="Permalink to this headline"></a></h2>
  225 <p>In order to commit the following steps must be taken:</p>
  226 <ol class="arabic simple">
  227 <li>Configure your git client for cross platform projects. See <a class="reference internal" href="#gitconfig"><span class="std std-ref">notes</span></a> below.</li>
  228 <li>Register for commit access as described <a class="reference internal" href="policies/committing.html#comitting"><span class="std std-ref">here</span></a>.</li>
  229 <li>Fork the canonical GeoServer repository into your github account.</li>
  230 <li>Clone the forked repository to create a local repository</li>
  231 <li>Create a remote reference to the canonical repository using a non-read only URL (<code class="docutils literal notranslate"><span class="pre">git&#64;github.com:geoserver/geoserver.git</span></code>).</li>
  232 </ol>
  233 <div class="admonition note">
  234 <p class="first admonition-title">Note</p>
  235 <p class="last">The next section describes how the git repositories are distributed for the project and
  236 how to manage local repository remote references.</p>
  237 </div>
  238 </div>
  239 <div class="section" id="repository-distribution">
  240 <h2>Repository distribution<a class="headerlink" href="#repository-distribution" title="Permalink to this headline"></a></h2>
  241 <p>Git is a distributed versioning system which means there is strictly no notion of a single
  242 central repository, but many distributed ones. For GeoServer these are:</p>
  243 <ul class="simple">
  244 <li>The <strong>canonical</strong> repository located on GitHub that serves as the official authoritative
  245 copy of the source code for project</li>
  246 <li>Developers’ <strong>forked</strong> repositories on GitHub. These repositories
  247 generally contain everything in the canonical repository, as well any feature or
  248 topic branches a developer is working on and wishes to back up or share.</li>
  249 <li>Developers’ <strong>local</strong> repositories on their own systems.  This is where development work is actually done.</li>
  250 </ul>
  251 <p>Even though there are numerous copies of the repository they can all interoperate because
  252 they share a common history. This is the magic of git!</p>
  253 <p>In order to interoperate with other repositories hosted on GitHub,
  254 a local repository must contain <em>remote references</em> to them.
  255 A local repository typically contains the following remote references:</p>
  256 <ul class="simple">
  257 <li>A remote called <strong>origin</strong> that points to the developers’ forked GitHub repository.</li>
  258 <li>A remote called <strong>upstream</strong> that points to the canonical GitHub repository.</li>
  259 <li>Optionally, some remotes that point to other developers’ forked repositories on GitHub.</li>
  260 </ul>
  261 <p>To set up a local repository in this manner:</p>
  262 <ol class="arabic">
  263 <li><p class="first">Clone your fork of the canonical repository (where “bob” is replaced with your GitHub account name):</p>
  264 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">clone</span> <span class="n">git</span><span class="nd">@github</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="n">bob</span><span class="o">/</span><span class="n">geoserver</span><span class="o">.</span><span class="n">git</span> <span class="n">geoserver</span>
  265 <span class="o">%</span> <span class="n">cd</span> <span class="n">geoserver</span>
  266 </pre></div>
  267 </div>
  268 </li>
  269 <li><p class="first">Create the <code class="docutils literal notranslate"><span class="pre">upstream</span></code> remote pointing to the canonical repository:</p>
  270 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">git</span><span class="nd">@github</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="n">geoserver</span><span class="o">/</span><span class="n">geoserver</span><span class="o">.</span><span class="n">git</span>
  271 </pre></div>
  272 </div>
  273 <p>Or if your account does not have push access to the canonical repository use the read-only url:</p>
  274 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">geoserver</span><span class="o">/</span><span class="n">geoserver</span><span class="o">.</span><span class="n">git</span>
  275 </pre></div>
  276 </div>
  277 </li>
  278 <li><p class="first">Optionally, create remotes pointing to other developer’s forks. These remotes are typically
  279 read-only:</p>
  280 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">aaime</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">aaime</span><span class="o">/</span><span class="n">geoserver</span><span class="o">.</span><span class="n">git</span>
  281 <span class="o">%</span> <span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">jdeolive</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">jdeolive</span><span class="o">/</span><span class="n">geoserver</span><span class="o">.</span><span class="n">git</span>
  282 </pre></div>
  283 </div>
  284 </li>
  285 </ol>
  286 </div>
  287 <div class="section" id="repository-structure">
  288 <h2>Repository structure<a class="headerlink" href="#repository-structure" title="Permalink to this headline"></a></h2>
  289 <p>A git repository contains a number of branches. These branches fall into three categories:</p>
  290 <ol class="arabic simple">
  291 <li><strong>Primary</strong> branches that correspond to major versions of the software</li>
  292 <li><strong>Release</strong> branches that are used to manage releases of the primary branches</li>
  293 <li><strong>Feature</strong> or topic branches that developers do development on</li>
  294 </ol>
  295 <div class="section" id="primary-branches">
  296 <h3>Primary branches<a class="headerlink" href="#primary-branches" title="Permalink to this headline"></a></h3>
  297 <p>Primary branches are present in all repositories and correspond to the main release streams of the
  298 project. These branches consist of:</p>
  299 <ul class="simple">
  300 <li>The <strong>master</strong> branch that is the current unstable development version of the project</li>
  301 <li>The current <strong>stable</strong> branch that is the current stable development version of the project</li>
  302 <li>The branches for previous stable versions</li>
  303 </ul>
  304 <p>For example at present these branches are:</p>
  305 <ul class="simple">
  306 <li><strong>master</strong> - The 2.17.x release stream, where unstable development such as major new features take place</li>
  307 <li><strong>2.16.x</strong> - The 2.16.x release stream, where stable development such as bug fixing and stable features take place</li>
  308 <li><strong>2.15.x</strong> - The 2.15.x release stream, which is at end-of-life and has no active development</li>
  309 </ul>
  310 </div>
  311 <div class="section" id="release-tags">
  312 <h3>Release tags<a class="headerlink" href="#release-tags" title="Permalink to this headline"></a></h3>
  313 <p>Release tags are used to mark releases from the stable or maintenance branches. These can be used to create a release branch if an emergency patch needs to be made:</p>
  314 <ul class="simple">
  315 <li>2.15-M0</li>
  316 <li>2.15-RC</li>
  317 <li>2.15.0</li>
  318 <li>2.15.1</li>
  319 </ul>
  320 <p>Release tagas are only used during a versioned release of the software. At any given time a release branch
  321 corresponds to the exact state of the last release from that branch. During release these branches are tagged.</p>
  322 <p>Release branches are also present in all repositories.</p>
  323 </div>
  324 <div class="section" id="feature-branches">
  325 <h3>Feature branches<a class="headerlink" href="#feature-branches" title="Permalink to this headline"></a></h3>
  326 <p>Feature branches are what developers use for day-to-day development. This can include small-scale bug fixes or
  327 major new features. Feature branches serve as a staging area for work that allows a developer to freely commit to
  328 them without affecting the primary branches. For this reason feature branches generally only live
  329 in a developer’s local repository, and possibly their remote forked repository. Feature branches are never pushed
  330 up into the canonical repository.</p>
  331 <p>When a developer feels a particular feature is complete enough the feature branch is merged into a primary branch,
  332 usually <code class="docutils literal notranslate"><span class="pre">master</span></code>. If the work is suitable for the current stable branch the changeset can be ported back to the
  333 stable branch as well. This is explained in greater detail in the <a class="reference internal" href="#source-workflow"><span class="std std-ref">Development workflow</span></a> section.</p>
  334 </div>
  335 </div>
  336 <div class="section" id="codebase-structure">
  337 <h2>Codebase structure<a class="headerlink" href="#codebase-structure" title="Permalink to this headline"></a></h2>
  338 <p>Each branch has the following structure:</p>
  339 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">build</span><span class="o">/</span>
  340 <span class="n">doc</span><span class="o">/</span>
  341 <span class="n">src</span><span class="o">/</span>
  342 <span class="n">data</span><span class="o">/</span>
  343 </pre></div>
  344 </div>
  345 <ul class="simple">
  346 <li><code class="docutils literal notranslate"><span class="pre">build</span></code> - release and continuous integration scripts</li>
  347 <li><code class="docutils literal notranslate"><span class="pre">doc</span></code> - sources for the user and developer guides</li>
  348 <li><code class="docutils literal notranslate"><span class="pre">src</span></code> - java sources for GeoServer itself</li>
  349 <li><code class="docutils literal notranslate"><span class="pre">data</span></code> - a variety of GeoServer data directories / configurations</li>
  350 </ul>
  351 </div>
  352 <div class="section" id="development-workflow">
  353 <span id="source-workflow"></span><h2>Development workflow<a class="headerlink" href="#development-workflow" title="Permalink to this headline"></a></h2>
  354 <p>This section contains examples of workflows a developer will typically use on a daily basis.
  355 To follow these examples it is crucial to understand the phases that a changeset goes though in the git
  356 workflow. The lifecycle of a single changeset is:</p>
  357 <ol class="arabic simple">
  358 <li>The change is made in a developer’s local repository.</li>
  359 <li>The change is <strong>staged</strong> for commit.</li>
  360 <li>The staged change is <strong>committed</strong>.</li>
  361 <li>The committed changed is <strong>pushed</strong> up to a remote repository</li>
  362 </ol>
  363 <p>There are many variations on this general workflow.
  364 For instance, it is common to make many local commits and then push them all up in batch to a remote repository.
  365 Also, for brevity multiple local commits may be <em>squashed</em> into a single final commit.</p>
  366 <div class="section" id="updating-from-canonical">
  367 <h3>Updating from canonical<a class="headerlink" href="#updating-from-canonical" title="Permalink to this headline"></a></h3>
  368 <p>Generally developers always work on a recent version of the official source code. The following example
  369 shows how to pull down the latest changes for the master branch from the canonical repository:</p>
  370 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
  371 <span class="o">%</span> <span class="n">git</span> <span class="n">pull</span> <span class="n">upstream</span> <span class="n">master</span>
  372 </pre></div>
  373 </div>
  374 <p>Similarly for the stable branch:</p>
  375 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="mf">2.2</span><span class="o">.</span><span class="n">x</span>
  376 <span class="o">%</span> <span class="n">git</span> <span class="n">pull</span> <span class="n">upstream</span> <span class="mf">2.2</span><span class="o">.</span><span class="n">x</span>
  377 </pre></div>
  378 </div>
  379 </div>
  380 <div class="section" id="making-local-changes">
  381 <h3>Making local changes<a class="headerlink" href="#making-local-changes" title="Permalink to this headline"></a></h3>
  382 <p>As mentioned above, git has a two-phase workflow in which changes are first staged and then committed
  383 locally. For example, to change, stage and commit a single file:</p>
  384 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
  385 <span class="c1"># do some work on file x</span>
  386 <span class="o">%</span> <span class="n">git</span> <span class="n">add</span> <span class="n">x</span>
  387 <span class="o">%</span> <span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;commit message&quot;</span> <span class="n">x</span>
  388 </pre></div>
  389 </div>
  390 <p>Again there are many
  391 variations but generally the staging process involves using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code> to stage files that have been added
  392 or modified, and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">rm</span></code> to stage files that have been deleted. <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">mv</span></code> is used to move files and
  393 stage the changes in one step.</p>
  394 <p>At any time you can run <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">status</span></code> to check what files have been changed in the working area
  395 and what has been staged for commit. It also shows the current branch, which is useful when
  396 switching frequently between branches.</p>
  397 </div>
  398 <div class="section" id="pushing-changes-to-canonical">
  399 <h3>Pushing changes to canonical<a class="headerlink" href="#pushing-changes-to-canonical" title="Permalink to this headline"></a></h3>
  400 <p>Once a developer has made some local commits they generally will want to push them up to a remote repository.
  401 For the primary branches these commits should always be pushed up to the canonical repository. If they are for
  402 some reason not suitable to be pushed to the canonical repository then the work should not be done on a primary
  403 branch, but on a feature branch.</p>
  404 <p>For example, to push a local bug fix up to the canonical <code class="docutils literal notranslate"><span class="pre">master</span></code> branch:</p>
  405 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
  406 <span class="c1"># make a change</span>
  407 <span class="o">%</span> <span class="n">git</span> <span class="n">add</span><span class="o">/</span><span class="n">rm</span><span class="o">/</span><span class="n">mv</span> <span class="o">...</span>
  408 <span class="o">%</span> <span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;making change x&quot;</span>
  409 <span class="o">%</span> <span class="n">git</span> <span class="n">pull</span> <span class="n">upstream</span> <span class="n">master</span>
  410 <span class="o">%</span> <span class="n">git</span> <span class="n">push</span> <span class="n">upstream</span> <span class="n">master</span>
  411 </pre></div>
  412 </div>
  413 <p>The example shows the practice of first pulling from canonical before pushing to it. Developers should <strong>always</strong> do
  414 this. In fact, if there are commits in canonical that have not been pulled down, by default git will not allow
  415 you to push the change until you have pulled those commits.</p>
  416 <div class="admonition note">
  417 <p class="first admonition-title">Note</p>
  418 <p>A <strong>merge commit</strong> may occur when one branch is merged with another.
  419 A merge commit occurs when two branches are merged and the merge is not a “fast-forward” merge.
  420 This happens when the target branch has changed since the commits were created.
  421 Fast-forward merges are worth <a class="reference external" href="http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging">reading about</a>.</p>
  422 <p>An easy way to avoid merge commits is to do a “rebase” when pulling down changes:</p>
  423 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">pull</span> <span class="o">--</span><span class="n">rebase</span> <span class="n">upstream</span> <span class="n">master</span>
  424 </pre></div>
  425 </div>
  426 <p class="last">The rebase makes local changes appear in git history after the changes that are pulled down.
  427 This allows the following merge to be fast-forward. This is not a required practice since merge commits are fairly harmless,
  428 but they should be avoided where possible since they clutter up the commit history and make the git log harder to read.</p>
  429 </div>
  430 </div>
  431 <div class="section" id="working-with-feature-branches">
  432 <h3>Working with feature branches<a class="headerlink" href="#working-with-feature-branches" title="Permalink to this headline"></a></h3>
  433 <p>As mentioned before, it is always a good idea to work on a feature branch rather than directly on a primary branch.
  434 A classic problem every developer who has used a version control system has run into is when they have
  435 worked on a feature locally and made a ton of changes, but then need to switch context to work on some other feature or
  436 bug fix. The developer tries to make the fix in the midst of the other changes
  437 and ends up committing a file that should not have been changed.
  438 Feature branches are the remedy for this problem.</p>
  439 <p>To create a new feature branch off the master branch:</p>
  440 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">my_feature</span> <span class="n">master</span>
  441 <span class="o">%</span> <span class="c1"># make some changes</span>
  442 <span class="o">%</span> <span class="n">git</span> <span class="n">add</span><span class="o">/</span><span class="n">rm</span><span class="p">,</span> <span class="n">etc</span><span class="o">...</span>
  443 <span class="o">%</span> <span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;first part of my_feature&quot;</span>
  444 </pre></div>
  445 </div>
  446 <p>Rinse, wash, repeat. The nice about thing about using a feature branch is that it is easy to switch context
  447 to work on something else. Just <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span></code> whatever other branch you need to work on,
  448 and then return to the feature branch when ready.</p>
  449 <div class="admonition note">
  450 <p class="first admonition-title">Note</p>
  451 <p class="last">When a branch is checked out, all the files in the working area are modified to reflect
  452 the current state of the branch.  When using development tools which cache the state of the
  453 project (such as Eclipse) it may be necessary to refresh their state to match the file system.
  454 If the branch is very different it may even be necessary to perform a rebuild so that
  455 build artifacts match the modified source code.</p>
  456 </div>
  457 </div>
  458 <div class="section" id="merging-feature-branches">
  459 <h3>Merging feature branches<a class="headerlink" href="#merging-feature-branches" title="Permalink to this headline"></a></h3>
  460 <p>Once a developer is done with a feature branch it must be merged into one of the primary branches and pushed up
  461 to the canonical repository. The way to do this is with the <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">merge</span></code> command:</p>
  462 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
  463 <span class="o">%</span> <span class="n">git</span> <span class="n">merge</span> <span class="n">my_feature</span>
  464 </pre></div>
  465 </div>
  466 <p>It’s as easy as that. After the feature branch has been merged into the primary branch push it up as described before:</p>
  467 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">pull</span> <span class="o">--</span><span class="n">rebase</span> <span class="n">upstream</span> <span class="n">master</span>
  468 <span class="o">%</span> <span class="n">git</span> <span class="n">push</span> <span class="n">upstream</span> <span class="n">master</span>
  469 </pre></div>
  470 </div>
  471 </div>
  472 <div class="section" id="porting-changes-between-primary-branches">
  473 <h3>Porting changes between primary branches<a class="headerlink" href="#porting-changes-between-primary-branches" title="Permalink to this headline"></a></h3>
  474 <p>Often a single change (such as a bug fix) has to be committed to multiple branches. Unfortunately primary
  475 branches <strong>cannot</strong> be merged with the <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">merge</span></code> command. Instead we use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">cherry-pick</span></code>.</p>
  476 <p>As an example consider making a change to master:</p>
  477 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
  478 <span class="o">%</span> <span class="c1"># make the change</span>
  479 <span class="o">%</span> <span class="n">git</span> <span class="n">add</span><span class="o">/</span><span class="n">rm</span><span class="o">/</span><span class="n">etc</span><span class="o">...</span>
  480 <span class="o">%</span> <span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;fixing bug GEOS-XYZ&quot;</span>
  481 <span class="o">%</span> <span class="n">git</span> <span class="n">pull</span> <span class="o">--</span><span class="n">rebase</span> <span class="n">upstream</span> <span class="n">master</span>
  482 <span class="o">%</span> <span class="n">git</span> <span class="n">push</span> <span class="n">upstream</span> <span class="n">master</span>
  483 </pre></div>
  484 </div>
  485 <p>We want to backport the bug fix to the stable branch as well. To do so we have to note the commit
  486 id of the change we just made on master. The <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code> command will provide this. Let’s assume the commit
  487 id is “123”. Backporting to the stable branch then becomes:</p>
  488 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="mf">2.2</span><span class="o">.</span><span class="n">x</span>
  489 <span class="o">%</span> <span class="n">git</span> <span class="n">cherry</span><span class="o">-</span><span class="n">pick</span> <span class="mi">123</span>
  490 <span class="o">%</span> <span class="n">git</span> <span class="n">pull</span> <span class="o">--</span><span class="n">rebase</span> <span class="n">upstream</span> <span class="mf">2.2</span><span class="o">.</span><span class="n">x</span>
  491 <span class="o">%</span> <span class="n">git</span> <span class="n">push</span> <span class="n">upstream</span> <span class="mf">2.2</span><span class="o">.</span><span class="n">x</span>
  492 </pre></div>
  493 </div>
  494 </div>
  495 <div class="section" id="cleaning-up-feature-branches">
  496 <h3>Cleaning up feature branches<a class="headerlink" href="#cleaning-up-feature-branches" title="Permalink to this headline"></a></h3>
  497 <p>Consider the following situation. A developer has been working on a feature branch and has gone back
  498 and forth to and from it making commits here and there. The result is that the feature branch has accumulated
  499 a number of commits on it. But all the commits are related, and what we want is really just one commit.</p>
  500 <p>This is easy with git and you have two options:</p>
  501 <ol class="arabic simple">
  502 <li>Do an <strong>interactive rebase</strong> on the feature branch</li>
  503 <li>Do a <strong>merge with squash</strong></li>
  504 </ol>
  505 <div class="section" id="interactive-rebase">
  506 <h4>Interactive rebase<a class="headerlink" href="#interactive-rebase" title="Permalink to this headline"></a></h4>
  507 <p>Rebasing allows us to rewrite the commits on a branch, deleting commits we don’t want, or merging commits that should
  508 really be done. You can read more about interactive rebasing <a class="reference external" href="http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages">here</a>.</p>
  509 <div class="admonition warning">
  510 <p class="first admonition-title">Warning</p>
  511 <p class="last">Much care should be taken with rebasing. You should <strong>never</strong> rebase commits that are public (that is, commits that have
  512 been copied outside your local repository). Rebasing public commits changes branch history and results in the inability to merge
  513 with other repositories.</p>
  514 </div>
  515 <p>The following example shows an interactive rebase on a feature branch:</p>
  516 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">my_feature</span>
  517 <span class="o">%</span> <span class="n">git</span> <span class="n">log</span>
  518 </pre></div>
  519 </div>
  520 <p>The git log shows the current commit on the branch is commit “123”.
  521 We make some changes and commit the result:</p>
  522 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">commit</span> <span class="s2">&quot;fixing bug x&quot;</span> <span class="c1"># results in commit 456</span>
  523 </pre></div>
  524 </div>
  525 <p>We realize we forgot to stage a change before committing, so we add the file and commit:</p>
  526 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;oops, forgot to commit that file&quot;</span> <span class="c1"># results in commit 678</span>
  527 </pre></div>
  528 </div>
  529 <p>Then we notice a small mistake, so we fix and commit again:</p>
  530 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;darn, made a typo&quot;</span> <span class="c1"># results in commit #910</span>
  531 </pre></div>
  532 </div>
  533 <p>At this point we have three commits when what we really want is one. So we rebase,
  534 specifying the revision immediately prior to the first commit:</p>
  535 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">rebase</span> <span class="o">-</span><span class="n">i</span> <span class="mi">123</span>
  536 </pre></div>
  537 </div>
  538 <p>This invokes an editor that allows indicating which commits should be combined.
  539 Git then <em>squashes</em> the commits into an equivalent single commit.
  540 After this we can merge the cleaned-up feature branch into master as usual:</p>
  541 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
  542 <span class="o">%</span> <span class="n">git</span> <span class="n">merge</span> <span class="n">my_feature</span>
  543 </pre></div>
  544 </div>
  545 <p>Again, be sure to read up on this feature before attempting to use it. And again, <strong>never rebase a public commit</strong>.</p>
  546 </div>
  547 <div class="section" id="merge-with-squash">
  548 <h4>Merge with squash<a class="headerlink" href="#merge-with-squash" title="Permalink to this headline"></a></h4>
  549 <p>The <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">merge</span></code> command takes an option <code class="docutils literal notranslate"><span class="pre">--squash</span></code> that performs the merge
  550 against the working area but does not commit the result to the target branch.
  551 This squashes all the commits from the feature branch into a single changeset that
  552 is staged and ready to be committed:</p>
  553 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
  554 <span class="o">%</span> <span class="n">git</span> <span class="n">merge</span> <span class="o">--</span><span class="n">squash</span> <span class="n">my_feature</span>
  555 <span class="o">%</span> <span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">&quot;implemented feature x&quot;</span>
  556 </pre></div>
  557 </div>
  558 </div>
  559 </div>
  560 </div>
  561 <div class="section" id="more-useful-reading">
  562 <h2>More useful reading<a class="headerlink" href="#more-useful-reading" title="Permalink to this headline"></a></h2>
  563 <p>The content in this section is not intended to be a comprehensive introduction to git. There are many things not covered
  564 that are invaluable to day-to-day work with git. Some more useful info:</p>
  565 <ul class="simple">
  566 <li><a class="reference external" href="http://webdeveloperplus.com/general/10-useful-advanced-git-commands/">10 useful git commands</a></li>
  567 <li><a class="reference external" href="http://git-scm.com/book/en/Git-Tools-Stashing">Git stashing</a></li>
  568 <li><a class="reference external" href="http://docs.geotools.org/latest/developer/procedures/git.html">GeoTools git primer</a></li>
  569 </ul>
  570 </div>
  571 </div>
  572 
  573 
  574       <div class="selfclear pagination-nav">
  575           <div class="leftwise"><strong>Previous</strong>: <a href="tools.html" title="previous chapter">Tools</a></div>
  576           <div class="rightwise"><strong>Next</strong>: <a href="quickstart/index.html" title="next chapter">Quickstart</a></div>
  577       </div>
  578       </div><!-- /#content> -->
  579       <div id="content-right" class="content-border"></div>
  580   <div id="sidebar" class="contrast">
  581       <div id="toc" class="section">
  582         <h3 class="pngfix">Table Of Contents</h3>
  583         <ul>
  584 <li><a class="reference internal" href="#">Source Code</a><ul>
  585 <li><a class="reference internal" href="#git">Git</a></li>
  586 <li><a class="reference internal" href="#git-client-configuration">Git client configuration</a><ul>
  587 <li><a class="reference internal" href="#line-endings">Line endings</a></li>
  588 <li><a class="reference internal" href="#file-paths">File paths</a></li>
  589 </ul>
  590 </li>
  591 <li><a class="reference internal" href="#committing">Committing</a></li>
  592 <li><a class="reference internal" href="#repository-distribution">Repository distribution</a></li>
  593 <li><a class="reference internal" href="#repository-structure">Repository structure</a><ul>
  594 <li><a class="reference internal" href="#primary-branches">Primary branches</a></li>
  595 <li><a class="reference internal" href="#release-tags">Release tags</a></li>
  596 <li><a class="reference internal" href="#feature-branches">Feature branches</a></li>
  597 </ul>
  598 </li>
  599 <li><a class="reference internal" href="#codebase-structure">Codebase structure</a></li>
  600 <li><a class="reference internal" href="#development-workflow">Development workflow</a><ul>
  601 <li><a class="reference internal" href="#updating-from-canonical">Updating from canonical</a></li>
  602 <li><a class="reference internal" href="#making-local-changes">Making local changes</a></li>
  603 <li><a class="reference internal" href="#pushing-changes-to-canonical">Pushing changes to canonical</a></li>
  604 <li><a class="reference internal" href="#working-with-feature-branches">Working with feature branches</a></li>
  605 <li><a class="reference internal" href="#merging-feature-branches">Merging feature branches</a></li>
  606 <li><a class="reference internal" href="#porting-changes-between-primary-branches">Porting changes between primary branches</a></li>
  607 <li><a class="reference internal" href="#cleaning-up-feature-branches">Cleaning up feature branches</a><ul>
  608 <li><a class="reference internal" href="#interactive-rebase">Interactive rebase</a></li>
  609 <li><a class="reference internal" href="#merge-with-squash">Merge with squash</a></li>
  610 </ul>
  611 </li>
  612 </ul>
  613 </li>
  614 <li><a class="reference internal" href="#more-useful-reading">More useful reading</a></li>
  615 </ul>
  616 </li>
  617 </ul>
  618 
  619         <div class="section-footer"></div>
  620       </div>
  621         <div class="section">
  622           <h3>Continue Reading</h3>
  623           <ul>
  624             <li>Previous: <a href="tools.html" title="previous chapter">Tools</a></li>
  625             <li>Next: <a href="quickstart/index.html" title="next chapter">Quickstart</a></li>
  626           </ul>
  627         </div>
  628         <div class="section">
  629         <h3>This Page</h3>
  630         <ul class="this-page-menu">
  631                 
  632         <li><a href="https://github.com/geoserver/geoserver/tree/master/doc/en/developer/source/source.rst">Edit</a></li>
  633         </ul>
  634         </div>
  635   </div><!-- /#sidebar -->
  636   </div><!-- /.wrap> -->
  637 </div><!-- /#main -->
  638 <div id="footer">
  639   <div class="wrap">
  640     &copy; Copyright 2019, Open Source Geospatial Foundation. License <a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution</a>.
  641     Last updated on Nov 22, 2019.
  642     Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
  643   </div><!-- /.wrap> -->
  644 </div><!-- /#footer -->
  645   </body>
  646 </html>