http://git-wip-us.apache.org/repos/asf/isis-site/blob/97af7e5f/content/versions/SNAPSHOT/guides/cgcom/cgcom.html
----------------------------------------------------------------------
diff --git a/content/versions/SNAPSHOT/guides/cgcom/cgcom.html 
b/content/versions/SNAPSHOT/guides/cgcom/cgcom.html
new file mode 100644
index 0000000..a2eee0c
--- /dev/null
+++ b/content/versions/SNAPSHOT/guides/cgcom/cgcom.html
@@ -0,0 +1,4458 @@
+<!doctype html>
+<html>
+ <head> 
+  <!--
+        Licensed to the Apache Software Foundation (ASF) under one
+        or more contributor license agreements.  See the NOTICE file
+        distributed with this work for additional information
+        regarding copyright ownership.  The ASF licenses this file
+        to you under the Apache License, Version 2.0 (the
+        "License"); you may not use this file except in compliance
+        with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+        Unless required by applicable law or agreed to in writing,
+        software distributed under the License is distributed on an
+        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+        KIND, either express or implied.  See the License for the
+        specific language governing permissions and limitations
+        under the License.
+    --> 
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
+  <meta charset="utf-8"> 
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"> 
+  <!-- No caching headers --> 
+  <meta http-equiv="cache-control" content="no-cache"> 
+  <meta http-equiv="pragma" content="no-cache"> 
+  <meta http-equiv="expires" content="-1"> 
+  <title>Committers' Guide</title> 
+  <link rel="icon" type="image/png" href="../../images/isis-favicon.png"> 
+  <!--
+        Based on DataNucleus' template,
+        that was in turn based on an earlier version of Apache Isis' template,
+        that was in turn based on Apache Deltaspike's template.
+
+        This template uses
+        * Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar.
+        * Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/)
+          for the table of contents.
+        * jQuery (necessary for Bootstrap's JavaScript plugins)
+        * Font-Awesome for some icons used by Asciidoctor
+
+        Also:
+        * Bootswatch "flatly" theme for Bootstrap 
(https://bootswatch.com/flatly).
+        * slick.js (carousel)
+        * add a link to all headers (home-grown, adapted from blog posts)
+        * integration of elasticlunr.js (home-grown, adapted from blog posts)
+    --> 
+  <link 
href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.3.7/flatly/bootstrap.min.css";
 rel="stylesheet"> 
+  <link href="../../css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" 
rel="stylesheet"> 
+  <link href="../../css/asciidoctor/foundation.css" rel="stylesheet"> 
+  <link 
href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css";
 rel="stylesheet"> 
+  <link href="../../css/slick/1.5.0/slick.css" rel="stylesheet"> 
+  <link href="../../css/slick/1.5.0/slick-theme.css" rel="stylesheet"> 
+  <link href="../../css/search-panel/search-panel.css" rel="stylesheet"> 
+  <link href="../../css/header-links/header-links.css" rel="stylesheet"> 
+  <link href="../../css/sticky-header/sticky-header.css" rel="stylesheet"> 
+  <link href="../../css/customisations.css" rel="stylesheet"> 
+  <!-- Coderay syntax formatter --> 
+  <style type="text/css">
+        /* Stylesheet for CodeRay to match GitHub theme | MIT License | 
http://foundation.zurb.com */
+/*pre.CodeRay {background-color:#f7f7f8;}*/
+.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
+.CodeRay 
span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
+.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
+table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
+table.CodeRay td{vertical-align: top;line-height:1.45}
+table.CodeRay td.line-numbers{text-align:right}
+table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
+table.CodeRay td.code{padding:0 0 0 .5em}
+table.CodeRay td.code>pre{padding:0}
+.CodeRay .debug{color:#fff !important;background:#000080 !important}
+.CodeRay .annotation{color:#007}
+.CodeRay .attribute-name{color:#000080}
+.CodeRay .attribute-value{color:#700}
+.CodeRay .binary{color:#509}
+.CodeRay .comment{color:#998;font-style:italic}
+.CodeRay .char{color:#04d}
+.CodeRay .char .content{color:#04d}
+.CodeRay .char .delimiter{color:#039}
+.CodeRay .class{color:#458;font-weight:bold}
+.CodeRay .complex{color:#a08}
+.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
+.CodeRay .color{color:#099}
+.CodeRay .class-variable{color:#369}
+.CodeRay .decorator{color:#b0b}
+.CodeRay .definition{color:#099}
+.CodeRay .delimiter{color:#000}
+.CodeRay .doc{color:#970}
+.CodeRay .doctype{color:#34b}
+.CodeRay .doc-string{color:#d42}
+.CodeRay .escape{color:#666}
+.CodeRay .entity{color:#800}
+.CodeRay .error{color:#808}
+.CodeRay .exception{color:inherit}
+.CodeRay .filename{color:#099}
+.CodeRay .function{color:#900;font-weight:bold}
+.CodeRay .global-variable{color:#008080}
+.CodeRay .hex{color:#058}
+.CodeRay .integer,.CodeRay .float{color:#099}
+.CodeRay .include{color:#555}
+.CodeRay .inline{color:#000}
+.CodeRay .inline .inline{background:#ccc}
+.CodeRay .inline .inline .inline{background:#bbb}
+.CodeRay .inline .inline-delimiter{color:#d14}
+.CodeRay .inline-delimiter{color:#d14}
+.CodeRay .important{color:#555;font-weight:bold}
+.CodeRay .interpreted{color:#b2b}
+.CodeRay .instance-variable{color:#008080}
+.CodeRay .label{color:#970}
+.CodeRay .local-variable{color:#963}
+.CodeRay .octal{color:#40e}
+.CodeRay .predefined{color:#369}
+.CodeRay .preprocessor{color:#579}
+.CodeRay .pseudo-class{color:#555}
+.CodeRay .directive{font-weight:bold}
+.CodeRay .type{font-weight:bold}
+.CodeRay .predefined-type{color:inherit}
+.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
+.CodeRay .key{color:#808}
+.CodeRay .key .delimiter{color:#606}
+.CodeRay .key .char{color:#80f}
+.CodeRay .value{color:#088}
+.CodeRay .regexp .delimiter{color:#808}
+.CodeRay .regexp .content{color:#808}
+.CodeRay .regexp .modifier{color:#808}
+.CodeRay .regexp .char{color:#d14}
+.CodeRay .regexp .function{color:#404;font-weight:bold}
+.CodeRay .string{color:#d20}
+.CodeRay .string .string .string{background:#ffd0d0}
+.CodeRay .string .content{color:#d14}
+.CodeRay .string .char{color:#d14}
+.CodeRay .string .delimiter{color:#d14}
+.CodeRay .shell{color:#d14}
+.CodeRay .shell .delimiter{color:#d14}
+.CodeRay .symbol{color:#990073}
+.CodeRay .symbol .content{color:#a60}
+.CodeRay .symbol .delimiter{color:#630}
+.CodeRay .tag{color:#008080}
+.CodeRay .tag-special{color:#d70}
+.CodeRay .variable{color:#036}
+.CodeRay .insert{background:#afa}
+.CodeRay .delete{background:#faa}
+.CodeRay .change{color:#aaf;background:#007}
+.CodeRay .head{color:#f8f;background:#505}
+.CodeRay .insert .insert{color:#080}
+.CodeRay .delete .delete{color:#800}
+.CodeRay .change .change{color:#66f}
+.CodeRay .head .head{color:#f4f}
+    </style> 
+ </head> 
+ <body data-spy="scroll" data-target="#toc"> 
+  <div id="basedir" style="display:none;">
+   ../../
+  </div> 
+  <div id="docname" style="display:none;">
+   cgcom
+  </div> 
+  <div id="filetype" style="display:none;">
+   html
+  </div> 
+  <!-- Navbar --> 
+  <nav class="navbar navbar-default navbar-static-top header"> 
+   <div class="container"> 
+    <div class="navbar-header"> 
+     <!-- Three line menu button for use on mobile screens --> 
+     <button type="button" class="navbar-toggle collapsed" 
data-toggle="collapse" data-target="#navbar" aria-expanded="false" 
aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span 
class="icon-bar"></span> <span class="icon-bar"></span> <span 
class="icon-bar"></span> </button> 
+     <a class="navbar-brand" href="../../index.html"> <img alt="Brand" 
src="../../images/isis-logo-48x48.png"> </a> 
+     <a class="navbar-brand" href="../../index.html">Apache Isis</a> 
+    </div> 
+    <!-- Navbar that will collapse on mobile screens --> 
+    <div id="navbar" class="navbar-collapse collapse"> 
+     <ul class="nav navbar-nav"> 
+      <li class="dropdown"> <a href="#" class="dropdown-toggle" 
data-toggle="dropdown" role="button" aria-haspopup="true" 
aria-expanded="false">Documentation<span class="caret"></span></a> 
+       <ul class="dropdown-menu"> 
+        <li><a href="../../documentation.html">Table of Contents</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">User Guides</li> 
+        <li><a href="../../guides/ugfun/ugfun.html">Fundamentals</a></li> 
+        <li><a href="../../guides/ugvw/ugvw.html">Wicket Viewer</a></li> 
+        <li><a href="../../guides/ugvro/ugvro.html">Restful Objects 
Viewer</a></li> 
+        <li><a href="../../guides/ugodn/ugodn.html">DataNucleus Object 
Store</a></li> 
+        <li><a href="../../guides/ugsec/ugsec.html">Security</a></li> 
+        <li><a href="../../guides/ugtst/ugtst.html">Testing</a></li> 
+        <li><a href="../../guides/ugbtb/ugbtb.html">Beyond the Basics</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">Reference Guides</li> 
+        <li><a href="../../guides/rgant/rgant.html">Annotations</a></li> 
+        <li><a href="../../guides/rgsvc/rgsvc.html">Domain Services</a></li> 
+        <li><a href="../../guides/rgcfg/rgcfg.html">Core Config' 
Properties</a></li> 
+        <li><a href="../../guides/rgcms/rgcms.html">Classes, Methods and 
Schema</a></li> 
+        <li><a href="../../guides/rgmvn/rgmvn.html">Maven plugin</a></li> 
+        <li><a href="../../guides/rgfis/rgfis.html">Framework Internal 
Services</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">Javadoc</li> 
+        <li><a 
href="http://javadoc.io/doc/org.apache.isis.core/isis-core-applib";>Applib</a></li>
 
+       </ul> </li> 
+      <li class="dropdown  hidden-sm hidden-md"> <a href="#" 
class="dropdown-toggle" data-toggle="dropdown" role="button" 
aria-haspopup="true" aria-expanded="false">Downloads<span 
class="caret"></span></a> 
+       <ul class="dropdown-menu"> 
+        <li class="dropdown-header">Maven archetypes</li> 
+        <li><a 
href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">helloworld</a></li>
 
+        <li><a 
href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">simpleapp</a></li>
 
+        <li role="separator" class="divider"></li> 
+        <li><a href="../../downloads.html">Downloads</a></li> 
+        <li><a href="../../release-notes/release-notes.html">Release 
Notes</a></li> 
+        <li><a href="../../migration-notes/migration-notes.html">Migration 
Notes</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li><a href="https://github.com/apache/isis";>Github mirror</a></li> 
+       </ul> </li> 
+      <li class="dropdown  hidden-sm"> <a href="#" class="dropdown-toggle" 
data-toggle="dropdown" role="button" aria-haspopup="true" 
aria-expanded="false">Support<span class="caret"></span></a> 
+       <ul class="dropdown-menu"> 
+        <li class="dropdown-header">Guides</li> 
+        <li><a href="../../guides/dg/dg.html">Developers' Guide</a></li> 
+        <li><a href="../../guides/cgcom/cgcom.html">Committers' Guide</a></li> 
+        <li><a href="../../guides/htg.html">Hints-n-Tips Guide</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">Mailing Lists</li> 
+        <li><a href="../../support.html">How to subscribe</a></li> 
+        <li><a 
href="https://lists.apache.org/list.html?us...@isis.apache.org";>Archives (ASF 
Pony mail)</a></li> 
+        <li><a href="http://isis.markmail.org/search/?q=";>Archives 
(Markmail)</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">Other Resources</li> 
+        <li><a href="https://issues.apache.org/jira/browse/ISIS";>ASF 
JIRA</a></li> 
+        <li><a href="http://stackoverflow.com/questions/tagged/isis";>Stack 
Overflow</a></li> 
+        <li><a href="../../help.html">Wiki, Fisheye etc.</a></li> 
+       </ul> </li> 
+      <li class="dropdown hidden-sm hidden-md"> <a href="#" 
class="dropdown-toggle" data-toggle="dropdown" role="button" 
aria-haspopup="true" aria-expanded="false">@ASF<span class="caret"></span></a> 
+       <ul class="dropdown-menu"> 
+        <li><a href="http://www.apache.org/";>Apache Homepage</a></li> 
+        <li><a href="http://www.apache.org/licenses/";>Licenses</a></li> 
+        <li><a href="http://www.apache.org/security/";>Security</a></li> 
+        <li><a 
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li> 
+        <li><a 
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li><a href="https://whimsy.apache.org/board/minutes/Isis.html";>PMC 
board minutes</a></li> 
+       </ul> </li> 
+     </ul> 
+     <div class="nav navbar-nav navbar-right"> 
+      <!-- 'style' added to fix height of input box. FIX THIS --> 
+      <form class="navbar-form" role="search" id="search-form" style="padding: 
1px 15px;"> 
+       <div class="form-group"> 
+        <input class="form-control" id="search-field" type="text" size="30" 
placeholder="Search"> 
+       </div> 
+      </form> 
+     </div> 
+     <p class="nav navbar-text navbar-right small">v2.0.0-M1-SNAPSHOT</p> 
+    </div> 
+   </div> 
+  </nav> 
+  <div class="container"> 
+   <div class="row-fluid"> 
+    <div class="col-xs-12 col-sm-12 col-md-12 col-lg-9"> 
+     <div id="search-panel"> 
+      <div id="search-results"></div> 
+      <div> 
+       <br> 
+       <a href="#" id="search-results-clear">clear</a> 
+      </div> 
+     </div> 
+     <span class="pdf-link"><a href="cgcom.pdf"><img 
src="../../images/PDF-50.png"></a></span> 
+     <div class="page-title"> 
+      <h1>Committers' Guide</h1> 
+     </div> 
+     <div id="doc-content">
+      <div class="btn-group" style="float: right; font-size: small; padding: 
6px;  ">
+       <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+       <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+       <ul class="dropdown-menu">
+        <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+        <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+        <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+        <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+       </ul>
+      </div> 
+      <div class="sect1"> 
+       <h2 id="__cgcom">1. Committers' Guide</h2> 
+       <div class="sectionbody"> 
+        <div class="paragraph"> 
+         <p>This committers' guide is for committers of Apache Isis itself who 
want guidance on release process, publishing documents and other related 
procedures.</p> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_other_guides">1.1. Other Guides</h3> 
+         <div class="paragraph"> 
+          <p>Apache Isis documentation is broken out into a number of user, 
reference and "supporting procedures" guides.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The user guides available are:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p><a href="../ugfun/ugfun.html">Fundamentals</a></p> </li> 
+           <li> <p><a href="../ugvw/ugvw.html">Wicket viewer</a></p> </li> 
+           <li> <p><a href="../ugvro/ugvro.html">Restful Objects 
viewer</a></p> </li> 
+           <li> <p><a href="../ugodn/ugodn.html">DataNucleus object 
store</a></p> </li> 
+           <li> <p><a href="../ugsec/ugsec.html">Security</a></p> </li> 
+           <li> <p><a href="../ugtst/ugtst.html">Testing</a></p> </li> 
+           <li> <p><a href="../ugbtb/ugbtb.html">Beyond the Basics</a></p> 
</li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The reference guides are:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p><a href="../rgant/rgant.html">Annotations</a></p> </li> 
+           <li> <p><a href="../rgsvc/rgsvc.html">Domain Services</a></p> </li> 
+           <li> <p><a href="../rgcfg/rgcfg.html">Configuration 
Properties</a></p> </li> 
+           <li> <p><a href="../rgcms/rgcms.html">Classes, Methods and 
Schema</a></p> </li> 
+           <li> <p><a href="../rgmvn/rgmvn.html">Apache Isis Maven 
plugin</a></p> </li> 
+           <li> <p><a href="../rgfis/rgfis.html">Framework Internal 
Services</a></p> </li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The remaining guides are:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p><a href="../dg/dg.html">Developers' Guide</a> (how to set 
up a development environment for Apache Isis and contribute back to the 
project)</p> </li> 
+           <li> <p><a href="../cgcom/cgcom.html">Committers' Guide</a> (this 
guide)</p> </li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>This guide provides guidance for Apache Isis' own committers.</p> 
+         </div> 
+        </div> 
+       </div> 
+      </div> 
+      <div class="sect1"> 
+       <h2 id="_cgcom_applying-patches">2. Applying Patches</h2>
+       <div class="btn-group" style="float: right; font-size: small; padding: 
6px; margin-top: -55px; ">
+        <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+        <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+        <ul class="dropdown-menu">
+         <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+         <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+         <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+         <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+        </ul>
+       </div> 
+       <div class="sectionbody"> 
+        <div class="paragraph"> 
+         <p>If a patch is received on a JIRA ticket, then it should be 
reviewed and applied. The commands are slightly different for diff files vs 
patch files.</p> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_diff_files">2.1. Diff files</h3> 
+         <div class="paragraph"> 
+          <p>If a diff file has been provided, then it can easily be applied 
using eGit’s wizards (Eclipse’s Git integration)…</p> 
+         </div> 
+         <div class="admonitionblock note"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> 
+             <td class="content"> FIXME - this stuff needs fleshing out …​ 
</td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_patch_files">2.2. Patch files</h3> 
+         <div class="paragraph"> 
+          <p>If a patch file has been provided, then it can be applied using 
command line tools.</p> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_inspect_the_patch">2.2.1. Inspect the patch</h4> 
+          <div class="paragraph"> 
+           <p>First, take a look at what changes are in the patch. You can do 
this easily with <code>git apply</code></p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">git apply 
--stat ISIS-xxx.patch</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Note that this command does not apply the patch, but only shows 
you the stats about what it’ll do. After peeking into the patch file 
with your favorite editor, you can see what the actual changes are.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Next, you’re interested in how troublesome the patch is going 
to be. Git allows you to test the patch before you actually apply it.</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">git apply 
--check ISIS-xxx.patch</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>If you don’t get any errors, the patch has no conflicts. 
Otherwise you may see what trouble you’ll run into.</p> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_apply_a_clean_patch">2.2.2. Apply a (clean) patch</h4> 
+          <div class="paragraph"> 
+           <p>To apply a clean patch (adding the items and commit/signoff in a 
single step), use <code>git am</code>:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">git am 
--signoff &lt; ISIS-xxx.patch</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>This preserves the original author’s commit message.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>However, this can fail if the patch file does not contain the 
original committers email address. In this case you will need to abort the 
<code>am</code> session:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">git am 
abort</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>and continue on by applying a non-clean patch, as described 
next.</p> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_apply_a_non_clean_patch">2.2.3. Apply a (non-clean) 
patch</h4> 
+          <div class="paragraph"> 
+           <p>If the patch does not apply cleanly, then the original authors 
commit message cannot be preserved. This sequence in this case is:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">git apply 
ISIS-xxx.patch</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Fix up any issues. The add and commit as usual</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">git add .
+git commit -am "&lt;original authors' commit message&gt;" 
--signoff</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>The <code>--signoff</code> simply adds a line to the commit 
message indicating you have signed off the commit.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Information adapted from <a 
href="https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/";>this
 blog post</a> and <a 
href="http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches";>this wiki 
page</a>.</p> 
+          </div> 
+         </div> 
+        </div> 
+       </div> 
+      </div> 
+      <div class="sect1"> 
+       <h2 id="_cgcom_merging-a-pull-request">3. Merging a Pull Request</h2>
+       <div class="btn-group" style="float: right; font-size: small; padding: 
6px; margin-top: -55px; ">
+        <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_merging-a-pull-request.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+        <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+        <ul class="dropdown-menu">
+         <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_merging-a-pull-request.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+         <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_merging-a-pull-request.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+         <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_merging-a-pull-request.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+         <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_merging-a-pull-request.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+        </ul>
+       </div> 
+       <div class="sectionbody"> 
+        <div class="paragraph"> 
+         <p>The process for merging in github pull requests (so that they can 
be tested locally before committing) has been scripted in the 
<code>github-pr.sh</code> script.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>The script will merge the fork into a temporary branch, and then 
run a build. Once you are happy, you can commit.</p> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_process_and_usage">3.1. Process and Usage</h3> 
+         <div class="paragraph"> 
+          <p>The overall process is as follows:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p>locate/raise corresponding JIRA ticket, eg ISIS-1162</p> 
</li> 
+           <li> <p>checkout branch from which PR was forked (usually just 
'master')</p> </li> 
+           <li> <p>merge PR into temporary branch using the 
<code>github-pr.sh</code> script</p> </li> 
+           <li> <p>test the change locally (run the app, rebuild, manual 
regression tests etc)</p> </li> 
+           <li> <p>if required, tidy up/refactor code as required</p> </li> 
+           <li> <p>merge temporary branch into mainline, and commit</p> </li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>This <a href="https://youtu.be/CKSLZBBHjME";>screencast</a> also 
shows the process.</p> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_prerequisites">3.2. Prerequisites</h3> 
+         <div class="paragraph"> 
+          <p>The script uses 'jq' to parse JSON. To install:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p>on Linux:<br></p> 
+            <div class="listingblock"> 
+             <div class="content"> 
+              <pre class="CodeRay highlight"><code data-lang="bash">aptitude 
install jq</code></pre> 
+             </div> 
+            </div> </li> 
+           <li> <p>on MacOS:<br></p> 
+            <div class="listingblock"> 
+             <div class="content"> 
+              <pre class="CodeRay highlight"><code data-lang="bash">brew 
install jq</code></pre> 
+             </div> 
+            </div> </li> 
+           <li> <p>on Windows:<br></p> 
+            <div class="paragraph"> 
+             <p>Download exe from <a 
href="http://stedolan.github.io/jq/download/";>website</a></p> 
+            </div> </li> 
+          </ul> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_syntax">3.3. Syntax</h3> 
+         <div class="paragraph"> 
+          <p>The syntax is:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="bash">github-pr.sh 
-j 1162 -g 31 [-s] [-p ISIS]</code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>where:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p><code>-j 1162</code><br></p> 
+            <div class="paragraph"> 
+             <p>is the JIRA ticket number</p> 
+            </div> </li> 
+           <li> <p><code>-g 31</code> <br></p> 
+            <div class="paragraph"> 
+             <p>is the github PR issue number</p> 
+            </div> </li> 
+           <li> <p><code>-s</code><br></p> 
+            <div class="paragraph"> 
+             <p>will optionally skip the build and auto-merge</p> 
+            </div> </li> 
+           <li> <p><code>-p ISIS</code><br></p> 
+            <div class="paragraph"> 
+             <p>optionally overrids the JIRA project (defaults to 'ISIS')</p> 
+            </div> </li> 
+          </ul> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_example_transcript">3.4. Example transcript</h3> 
+         <div class="paragraph"> 
+          <p>The listing below shows the steps taken by the script:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="bash">$ sh 
github-pr.sh isis 1162 31
+
+Found JIRA ticket
+Found github PR
+branch_name_local: master
+username         : sebadiaz
+repo_full_name   : sebadiaz/isis
+repo_clone_url   : https://github.com/sebadiaz/isis.git
+branch_name_fork : master
+
+merging into: ISIS-1162_pr-31
+
+Deleting branch 'ISIS-1162_pr-31'
+Deleted branch ISIS-1162_pr-31 (was bd2e3c2).
+Creating the branch ISIS-1162_pr-31
+Switched to a new branch 'ISIS-1162_pr-31'
+Pulling the changes from https://github.com/sebadiaz/isis.git master
+From https://github.com/sebadiaz/isis
+ * branch            master     -&gt; FETCH_HEAD
+Auto-merging core/pom.xml
+Merge made by the 'recursive' strategy.
+ core/pom.xml                                       |   3 +-
+ .../apache/isis/security/shiro/IsisLdapRealm.java  | 198 +++++++++++++++++++--
+ 2 files changed, 186 insertions(+), 15 deletions(-)
+
+Merged the PR; hit enter to build</code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The build now commences. Once done, the script continues:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="bash">If build 
successful and happy to merge, execute:
+
+git checkout master &amp;&amp; git merge --no-ff ISIS-1162_pr-31 &amp;&amp; 
git branch -d ISIS-1162_pr-31</code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The screenshot belows shows the history we end up with:</p> 
+         </div> 
+         <div class="imageblock"> 
+          <div class="content"> 
+           <a class="image" 
href="images/committers/github-pr-history.png"><img 
src="images/committers/github-pr-history.png" alt="github pr history"></a> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>This shows the fork being merged into the temporary branch 
("ISIS-1162_pr-31"), then some further tidy-up, and finally the merging of the 
temporary branch into mainline.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Note that there is no rebasing in this model. This is 
intentional: when the merged branch is pushed, github will automatically close 
the original pull request.</p> 
+         </div> 
+        </div> 
+       </div> 
+      </div> 
+      <div class="sect1"> 
+       <h2 id="_cgcom_cutting-a-release">4. Cutting a Release</h2>
+       <div class="btn-group" style="float: right; font-size: small; padding: 
6px; margin-top: -55px; ">
+        <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+        <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+        <ul class="dropdown-menu">
+         <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+         <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+         <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+         <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+        </ul>
+       </div> 
+       <div class="sectionbody"> 
+        <div class="paragraph"> 
+         <p>The release process consists of:</p> 
+        </div> 
+        <div class="ulist"> 
+         <ul> 
+          <li> <p>the release manager cutting the release (documented 
below)</p> </li> 
+          <li> <p>Members of the Apache Isis PMC <a 
href="../cgcom/cgcom.html#_cgcom_verifying-releases">verifying</a> and voting 
on the release</p> </li> 
+          <li> <p>the release manager performing post-release tasks, for 
either a <a 
href="../cgcom/cgcom.html#_cgcom_post-release-successful">successful</a> or an 
<a href="../cgcom/cgcom.html#_cgcom_post-release-unsuccessful">unsuccessful</a> 
vote.</p> </li> 
+         </ul> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Apache Isis itself consists of three separately releasable 
modules; relative to the <a href="https://github.com/apache/isis";>source code 
root</a> there are:</p> 
+        </div> 
+        <div class="ulist"> 
+         <ul> 
+          <li> <p><code>core</code></p> </li> 
+          <li> <p><code>component/example/archetypes/helloworld</code></p> 
</li> 
+          <li> <p><code>component/example/archetypes/simpleapp</code></p> 
</li> 
+         </ul> 
+        </div> 
+        <div class="paragraph"> 
+         <p>This section details the process for formally releasing Isis 
modules. It describes the process for both <code>core</code> and then the 
archetypes. The subsequent sections describe how other committers can <a 
href="../cgcom/cgcom.html#_cgcom_verifying-releases">verify a release</a> and 
how the release manager can then perform <a 
href="../cgcom/cgcom.html#_cgcom_post-release">post-release</a> activities and 
set up for the next development iteration.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>If you’ve not performed a release before, then note that there 
are some configuration <a 
href="../cgcom/cgcom.html#_cgcom_release-process-prereqs">prerequisites</a> 
that must be configured first. In particular, you’ll need signed 
public/private keys, and the ASF Nexus staging repo inlocal 
<code>~/.m2/settings.xml</code> file.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>These release notes using bash command line tools. They should 
work on Linux and MacOS; for Windows, use mSysGit.</p> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="__cgcom_cutting-a-release_obtain-consensus">4.1. Obtain 
Consensus</h3> 
+         <div class="paragraph"> 
+          <p>Before releasing <code>core</code>, ensure there is consensus on 
the <a href="../../support.html">dev mailing list</a> that this is the right 
time for a release. The discussion should include confirming the version number 
to be used, and to confirm content.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>These discussions should also confirm the version number of the 
module being released. This should be in line with our <a 
href="../cgcom/cgcom.html#_cgcom_versioning-policy">semantic versioning 
policy</a>.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Make sure you have a JIRA ticket open against which to perform 
all commits. In most cases a JIRA ticket will have been created at the 
beginning of the previous release cycle.</p> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="__cgcom_cutting-a-release_set-environment-variables">4.2. Set 
environment variables</h3> 
+         <div class="paragraph"> 
+          <p>We use environment variables to parameterize as many of the steps 
as possible. For example:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="bash">cd core
+export ISISTMP=/c/tmp                               <i class="conum" 
data-value="1"></i><b>(1)</b>
+export ISISDEV=2.1.0-SNAPSHOT
+export ISISREL=2.0.0
+export ISISRC=RC1
+export ISISBRANCH=release-$ISISREL-$ISISRC
+export ISISJIRA=ISIS-9999                           <i class="conum" 
data-value="2"></i><b>(2)</b>
+export CATALINA_HOME=/c/java/apache-tomcat-8.0.30   <i class="conum" 
data-value="3"></i><b>(3)</b>
+
+env | grep ISIS | sort</code></pre> 
+          </div> 
+         </div> 
+         <div class="colist arabic"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td><i class="conum" data-value="1"></i><b>1</b></td> 
+             <td>adjust by platform</td> 
+            </tr> 
+            <tr> 
+             <td><i class="conum" data-value="2"></i><b>2</b></td> 
+             <td>set to an "umbrella" ticket for all release activities. (One 
should exist already, <a 
href="../cgcom/cgcom.html#__cgcom_post-release-successful_update-jira_create-new-jira">created
 at</a> the beginning of the development cycle now completing).</td> 
+            </tr> 
+            <tr> 
+             <td><i class="conum" data-value="3"></i><b>3</b></td> 
+             <td>adjust as required (Tomcat is used to smoke test the 
simpleapp archetype)</td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Obviously, alter <code>$ISISDEV</code> and <code>$ISISREL</code> 
as required, and bump <code>$ISISRC</code> for re-releasing following an <a 
href="../cgcom/cgcom.html#_cgcom_post-release-unsuccessful">unsuccessful</a> 
releases.</p> 
+         </div> 
+         <div class="admonitionblock important"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-important" 
title="Important"></i> </td> 
+             <td class="content"> 
+              <div class="paragraph"> 
+               <p>Note that the branch name is <strong>not</strong> the same 
any of the eventual tag names (eg <code>isis-2.0.0</code> or 
<code>simpleapp-archetype-2.0.0</code>).</p> 
+              </div> 
+              <div class="paragraph"> 
+               <p>If they did have the same name, then what would happen is 
that the <code>maven-release-plugin</code> would checkout the (HEAD of the) 
branch and thus upload a SNAPSHOT to the snapshot repository. What it should of 
course do is checkout the tag and then upload that to the release staging 
repository.</p> 
+              </div> </td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="__cgcom_cutting-a-release_pull-down-code-to-release">4.3. 
Pull down code to release</h3> 
+         <div class="paragraph"> 
+          <p>Set the HEAD of your local git repo to the commit to be released. 
This will usually be the tip of the origin’s <code>master</code> branch. 
Then, create a release branch for the version number being released; eg:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="bash">git checkout 
master
+git pull --ff-only
+git checkout -b $ISISBRANCH</code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>All release preparation is done locally; if we are successful, 
this branch will be merged back into master.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Double check that the version number of the parent pom should 
reflect the branch name that you are now on (with a <code>-SNAPSHOT</code> 
suffix). his will normally have been done already during earlier development; 
but confirm that it has been updated. If it has not, make the change.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Double check that the version number of the core POM 
(<code>core/pom.xml</code>) should reflect the branch name that you are now on. 
For example, if releasing version <code>2.0.0</code>, the POM should read:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="xml"><span 
class="tag">&lt;groupId&gt;</span>org.apache.isis.core<span 
class="tag">&lt;/groupId&gt;</span>
+<span class="tag">&lt;artifactId&gt;</span>isis<span 
class="tag">&lt;/artifactId&gt;</span>
+<span class="tag">&lt;version&gt;</span>2.0.0-SNAPSHOT<span 
class="tag">&lt;/version&gt;</span></code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Also, check that there are no snapshot dependencies:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="bash">grep SNAPSHOT 
`/bin/find . -name pom.xml | grep -v target | grep -v mothball | 
sort`</code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The only mention of <code>SNAPSHOT</code> should be for the Isis 
modules about to be released.</p> 
+         </div> 
+         <div class="admonitionblock tip"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> 
+             <td class="content"> 
+              <div class="paragraph"> 
+               <p>Obviously, don’t update Apache Isis' <code>SNAPSHOT</code> 
references; these get updated by the <code>mvn release:prepare</code> command 
we run later.</p> 
+              </div> </td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="__cgcom_cutting-a-release_releasing-core">4.4. Releasing 
Core</h3> 
+         <div class="paragraph"> 
+          <p>First, we release <code>core</code>. Switch to the appropriate 
directory:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="bash">cd 
core</code></pre> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_set-environment-variables">4.4.1. 
Set environment variables</h4> 
+          <div class="paragraph"> 
+           <p>Set additional environment variables for the core 
"artifact":</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">export 
ISISART=isis
+export ISISCOR="Y"
+
+env | grep ISIS | sort</code></pre> 
+           </div> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_license-headers">4.4.2. License 
headers</h4> 
+          <div class="paragraph"> 
+           <p>The Apache Release Audit Tool <code>RAT</code> (from the <a 
href="http://creadur.apache.org";>Apache Creadur</a> project) checks for missing 
license header files. The parent <code>pom.xml</code> of each releasable module 
specifies the RAT Maven plugin, with a number of custom exclusions.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>To run the RAT tool, use:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">mvn 
org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o 
&amp;&amp; \
+for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done || \
+for a in `/bin/find . -name rat.txt -print`; do grep '!AL' $a; 
done</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>where <code>rat.numUnapprovedLicenses</code> property is set to 
a high figure, temporarily overriding the default value of 0. This will allow 
the command to run over all submodules, rather than failing after the first 
one. The command writes out a <code>target\rat.txt</code> for each submodule. 
missing license notes are indicated using the key <code>!???</code>. The 
<code>for</code> command collates all the errors.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Investigate and fix any reported violations, typically by 
either:</p> 
+          </div> 
+          <div class="ulist"> 
+           <ul> 
+            <li> <p>adding genuinely missing license headers from Java (or 
other) source files, or</p> </li> 
+            <li> <p>updating the <code>&lt;excludes&gt;</code> element for the 
<code>apache-rat-plugin</code> plugin to ignore test files, log files and any 
other non-source code files</p> </li> 
+            <li> <p>also look to remove any stale <code>&lt;exclude&gt;</code> 
entries</p> </li> 
+           </ul> 
+          </div> 
+          <div class="paragraph"> 
+           <p>To add missing headers, use the groovy script 
<code>addmissinglicenses.groovy</code> (in the <code>scripts</code> directory) 
to automatically insert missing headers for certain file types. The actual 
files checked are those with extensions specified in the line <code>def 
fileEndings = [".java", ".htm"]</code>:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">groovy 
../scripts/addmissinglicenses.groovy -x</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>(If the <code>-x</code> is omitted then the script is run in 
"dry run" mode). Once you’ve fixed all issues, confirm once more that 
<code>apache-rat-plugin</code> no longer reports any license violations, this 
time leaving the <code>rat.numUnapprovedLicenses</code> property to its 
default, 0:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">mvn 
org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=0 -o 
&amp;&amp; \
+for a in `find . -name rat.txt -print`; do grep '!???' $a; done</code></pre> 
+           </div> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_missing-license-check">4.4.3. 
Missing License Check</h4> 
+          <div class="paragraph"> 
+           <p>Although Apache Isis has no dependencies on artifacts with 
incompatible licenses, the POMs for some of these dependencies (in the Maven 
central repo) do not necessarily contain the required license information. 
Without appropriate additional configuration, this would result in the 
generated <code>DEPENDENCIES</code> file and generated Maven site indicating 
dependencies as having "unknown" licenses.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Fortunately, Maven allows the missing information to be provided 
by configuring the <code>maven-remote-resources-plugin</code>. This is stored 
in the <code>src/main/appended-resources/supplemental-models.xml</code> file, 
relative to the root of each releasable module.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>To capture the missing license information, use:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">mvn 
license:download-licenses &amp;&amp; \
+groovy ../scripts/checkmissinglicenses.groovy</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>The Maven plugin creates a <code>license.xml</code> file in the 
<code>target/generated-resources</code> directory of each module. The script 
then searches for these <code>licenses.xml</code> files, and compares them 
against the contents of the <code>supplemental-models.xml</code> file.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>For example, the output could be something like:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">licenses to 
add to supplemental-models.xml:
+
+[org.slf4j, slf4j-api, 1.5.7]
+[org.codehaus.groovy, groovy-all, 1.7.2]
+
+licenses to remove from supplemental-models.xml (are spurious):
+
+[org.slf4j, slf4j-api, 1.5.2]</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>If any missing entries are listed or are spurious, then update 
<code>supplemental-models.xml</code> and try again.</p> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_commit-changes">4.4.4. Commit 
changes</h4> 
+          <div class="paragraph"> 
+           <p>Commit any changes from the preceding steps:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">git commit 
-am "$ISISJIRA: updates to pom.xml etc for release"</code></pre> 
+           </div> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_sanity-check">4.4.5. Sanity 
check</h4> 
+          <div class="paragraph"> 
+           <p>Perform one last sanity check on the codebase. Delete all Isis 
artifacts from your local Maven repo, then build using the <code>-o</code> 
offline flag:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">rm -rf 
~/.m2/repository/org/apache/isis
+mvn clean install -o</code></pre> 
+           </div> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_release-prepare-dry-run">4.4.6. 
Release prepare "dry run"</h4> 
+          <div class="paragraph"> 
+           <p>Most of the work is done using the <code>mvn 
release:prepare</code> goal. Since this makes a lot of changes, we run it first 
in "dry run" mode; only if that works do we run the goal for real.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Run the dry-run as follows:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">mvn 
release:prepare -P apache-release -D dryRun=true \
+    -DreleaseVersion=$ISISREL \
+    -Dtag=$ISISART-$ISISREL \
+    -DdevelopmentVersion=$ISISDEV</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>You may be prompted for the gpg passphrase.</p> 
+          </div> 
+          <div class="admonitionblock note"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td class="icon"> <i class="fa icon-note" title="Note"></i> 
</td> 
+              <td class="content"> 
+               <div class="paragraph"> 
+                <p>Experiments in using <code>--batch-mode 
-Dgpg.passphrase="…​"</code> to fully automate this didn’t work; for more 
info, see <a 
href="http://maven.apache.org/plugins/maven-gpg-plugin/sign-mojo.html";>here</a> 
(maven release plugin docs) and <a 
href="http://maven.apache.org/maven-release/maven-release-plugin/examples/non-interactive-release.html";>here</a>
 (maven gpg plugin docs).</p> 
+               </div> </td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_release-prepare-proper">4.4.7. 
Release prepare "proper"</h4> 
+          <div class="paragraph"> 
+           <p>Assuming this completes successfully, re-run the command, but 
without the <code>dryRun</code> flag and specifying <code>resume=false</code> 
(to ignore the generated <code>release.properties</code> file that gets 
generated as a side-effect of using <code>git</code>). You can also set the 
<code>skipTests</code> flag since they would have been run during the previous 
dry run:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">mvn 
release:prepare -P apache-release -D resume=false -DskipTests=true \
+        -DreleaseVersion=$ISISREL \
+        -Dtag=$ISISART-$ISISREL \
+        -DdevelopmentVersion=$ISISDEV</code></pre> 
+           </div> 
+          </div> 
+          <div class="admonitionblock tip"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> 
+              <td class="content"> 
+               <div class="paragraph"> 
+                <p>If there are any snags at this stage, then explicitly 
delete the generated <code>release.properties</code> file first before trying 
again.</p> 
+               </div> </td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_post-prepare-sanity-check">4.4.8. 
Post-prepare sanity check</h4> 
+          <div class="paragraph"> 
+           <p>You should end up with artifacts in your local repo with the new 
version (eg <code>2.0.0-M1</code>). This is a good time to do some quick sanity 
checks; nothing has yet been uploaded:</p> 
+          </div> 
+          <div class="ulist"> 
+           <ul> 
+            <li> <p>unzip the source-release ZIP and check it builds.</p> 
</li> 
+            <li> <p>Inspect the <code>DEPENDENCIES</code> file, and check it 
looks correct.</p> </li> 
+           </ul> 
+          </div> 
+          <div class="paragraph"> 
+           <p>These steps can be performed using the following script:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code>rm -rf 
$ISISTMP/$ISISART-$ISISREL
+mkdir $ISISTMP/$ISISART-$ISISREL
+
+if [ "$ISISCOR" == "Y" ]; then
+    ZIPDIR="$M2_REPO/repository/org/apache/isis/core/$ISISART/$ISISREL"
+else
+    ZIPDIR="$M2_REPO/repository/org/apache/isis/$ISISCPT/$ISISART/$ISISREL"
+fi
+echo "cp \"$ZIPDIR/$ISISART-$ISISREL-source-release.zip\" 
$ISISTMP/$ISISART-$ISISREL/."
+cp "$ZIPDIR/$ISISART-$ISISREL-source-release.zip" $ISISTMP/$ISISART-$ISISREL/.
+
+pushd $ISISTMP/$ISISART-$ISISREL
+unzip $ISISART-$ISISREL-source-release.zip
+
+cd $ISISART-$ISISREL
+mvn clean install
+
+cat DEPENDENCIES
+
+popd</code></pre> 
+           </div> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-core_release-perform-upload">4.4.9. 
Release perform (Upload)</h4> 
+          <div class="paragraph"> 
+           <p>Once the release has been built locally, it should be uploaded 
for voting. This is done by deploying the Maven artifacts to a staging 
directory (this includes the source release ZIP file which will be voted 
upon).</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>The Apache staging repository runs on Nexus server, hosted at <a 
href="https://repository.apache.org";>repository.apache.org</a>. The process of 
uploading will create a staging repository that is associated with the host (IP 
address) performing the release. Once the repository is staged, the newly 
created staging repository is "closed" in order to make it available to 
others.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Use:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">mvn 
release:perform -P apache-release \
+    -DworkingDirectory=$ISISTMP/$ISISART-$ISISREL/checkout</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>The custom <code>workingDirectory</code> prevents file path 
issues if releasing on Windows. The command checks out the codebase from the 
tag, then builds the artifacts, then uploads them to the Apache staging 
repository:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">...
+[INFO] --- maven-release-plugin:2.3.2:perform (default-cli) @ isis ---
+[INFO] Performing a LOCAL checkout from 
scm:git:file:///C:\APACHE\isis-git-rw\co
+re
+[INFO] Checking out the project to perform the release ...
+[INFO] Executing: cmd.exe /X /C "git clone --branch release-2.0.0-M1 
file:///C:\APACHE\isis-git-rw\core C:\APACHE\isis-git-rw\core\target\checkout"
+[INFO] Working directory: C:\APACHE\isis-git-rw\core\target
+[INFO] Performing a LOCAL checkout from scm:git:file:///C:\APACHE\isis-git-rw
+[INFO] Checking out the project to perform the release ...
+[INFO] Executing: cmd.exe /X /C "git clone --branch release-2.0.0-M1 
file:///C:\APACHE\isis-git-rw C:\APACHE\isis-git-rw\core\target\checkout"
+[INFO] Working directory: C:\APACHE\isis-git-rw\core\target
+[INFO] Executing: cmd.exe /X /C "git ls-remote file:///C:\APACHE\isis-git-rw"
+[INFO] Working directory: C:\Users\ADMINI~1\AppData\Local\Temp
+[INFO] Executing: cmd.exe /X /C "git fetch file:///C:\APACHE\isis-git-rw"
+[INFO] Working directory: C:\APACHE\isis-git-rw\core\target\checkout
+[INFO] Executing: cmd.exe /X /C "git checkout release-2.0.0-M1"
+[INFO] Working directory: C:\APACHE\isis-git-rw\core\target\checkout
+[INFO] Executing: cmd.exe /X /C "git ls-files"
+[INFO] Working directory: C:\APACHE\isis-git-rw\core\target\checkout
+[INFO] Invoking perform goals in directory 
C:\APACHE\isis-git-rw\core\target\checkout\core
+[INFO] Executing goals 'deploy'...
+...</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>You may (again) be prompted for gpg passphrase. All being well 
this command will complete successfully. Given that it is uploading code 
artifacts, it could take a while to complete.</p> 
+          </div> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="__cgcom_cutting-a-release_releasing-the-archetypes">4.5. 
Releasing the Archetypes</h3> 
+         <div class="paragraph"> 
+          <p>Apache Isis archetypes are reverse engineered from example 
applications. Once reverse engineered, the source is checked into git 
(replacing any earlier version of the archetype) and released.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>There are currently two archetypes, <code>simpleapp</code> and 
<code>helloworld</code>.</p> 
+         </div> 
+         <div class="admonitionblock note"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> 
+             <td class="content"> 
+              <div class="paragraph"> 
+               <p>If releasing using Windows and Maven &gt;= 3.3.3, then there 
is an issue that requires a small workaround.</p> 
+              </div> 
+              <div class="paragraph"> 
+               <p>In Maven 3.3.3 the <code>mvn.bat</code> file was removed, 
replaced instead with <code>mvn.cmd</code>. However, 
<code>maven-archetype-plugin:2.4</code> only uses <code>mvn.bat</code>; this 
causes the <code>archetype:create-from-project</code> goal to fail. The fix is 
simple: just copy <code>mvn.cmd</code> to <code>mvn.bat</code>.</p> 
+              </div> </td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_setup-environment-variables">4.5.1.
 Releasing <code>simpleapp</code> archetype</h4> 
+          <div class="paragraph"> 
+           <p>Switch to the directory containing the <code>simpleapp</code> 
example:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">cd 
../example/application/simpleapp</code></pre> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_setup-environment-variables">Setup
 environment variables</h5> 
+           <div class="paragraph"> 
+            <p>Set additional environment variables for the 
<code>simpleapp-archetype</code> artifact:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">export 
ISISART=simpleapp-archetype
+export ISISPAR=$ISISREL                 <i class="conum" 
data-value="1"></i><b>(1)</b>
+
+export ISISCPT=$(echo $ISISART | cut -d- -f2)
+export ISISCPN=$(echo $ISISART | cut -d- -f1)
+
+env | grep ISIS | sort</code></pre> 
+            </div> 
+           </div> 
+           <div class="colist arabic"> 
+            <table> 
+             <tbody>
+              <tr> 
+               <td><i class="conum" data-value="1"></i><b>1</b></td> 
+               <td><code>$ISISPAR</code> is the version of the Apache Isis 
core that will act as the archetype’s parent. Usually this is the same as 
<code>$ISISREL</code>.</td> 
+              </tr> 
+             </tbody>
+            </table> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_check-the-example-app">Check
 the example app</h5> 
+           <div class="paragraph"> 
+            <p>Update the parent <code>pom.xml</code> to reference the 
<em>released</em> version of Apache Isis core, eg:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="xml"><span 
class="tag">&lt;properties&gt;</span>
+    <span class="tag">&lt;isis.version&gt;</span>2.0.0-M1<span 
class="tag">&lt;/isis.version&gt;</span>
+    ...
+<span class="tag">&lt;/properties&gt;</span></code></pre> 
+            </div> 
+           </div> 
+           <div class="admonitionblock note"> 
+            <table> 
+             <tbody>
+              <tr> 
+               <td class="icon"> <i class="fa icon-note" title="Note"></i> 
</td> 
+               <td class="content"> 
+                <div class="paragraph"> 
+                 <p>Previously at this point we used to check for and fix any 
missing license header notices; however it doesn’t make sense for the 
archetype to include the Apache rat-plugin, so this has been removed.</p> 
+                </div> </td> 
+              </tr> 
+             </tbody>
+            </table> 
+           </div> 
+           <div class="paragraph"> 
+            <p>Finally, double check that the app</p> 
+           </div> 
+           <div class="ulist"> 
+            <ul> 
+             <li> <p>builds:</p> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">mvn 
clean install</code></pre> 
+               </div> 
+              </div> </li> 
+             <li> <p>can be run from an IDE</p> 
+              <div class="ulist"> 
+               <ul> 
+                <li> <p>mainClass=<code>org.apache.isis.WebServer</code></p> 
</li> 
+                <li> <p>args=<code>-m 
domainapp.application.manifest.DomainAppAppManifestWithFixtures</code></p> 
</li> 
+                <li> <p>run before: <code>mvn -pl module-simple 
datanucleus:enhance -o</code> in the root module</p> </li> 
+               </ul> 
+              </div> </li> 
+             <li> <p>can be run using the mvn jetty plugin:</p> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">mvn -pl 
webapp jetty:run</code></pre> 
+               </div> 
+              </div> </li> 
+             <li> <p>can be packaged and run using the mvn jetty-console 
plugin:</p> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">mvn 
install -Dmavenmixin-jettyconsole
+mvn antrun:run -Dmavenmixin-jettyconsole</code></pre> 
+               </div> 
+              </div> </li> 
+             <li> <p>can be deployed as a WAR</p> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">cp 
webapp/target/simpleapp.war $CATALINA_HOME/webapps/ROOT.war
+pushd $CATALINA_HOME/bin
+sh startup.sh
+tail -f ../logs/catalina.out</code></pre> 
+               </div> 
+              </div> 
+              <div class="paragraph"> 
+               <p>quit using:</p> 
+              </div> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">sh 
shutdown.sh
+popd</code></pre> 
+               </div> 
+              </div> </li> 
+             <li> <p>can be packaged and run using Docker:</p> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">mvn 
install -Dmavenmixin-docker -D docker-plugin.imageName=test/simpleapp
+docker container run -p 8080:8080 -d test/simpleapp</code></pre> 
+               </div> 
+              </div> 
+              <div class="admonitionblock note"> 
+               <table> 
+                <tbody>
+                 <tr> 
+                  <td class="icon"> <i class="fa icon-note" title="Note"></i> 
</td> 
+                  <td class="content"> 
+                   <div class="paragraph"> 
+                    <p>On Windows, make sure that Docker is first switched to 
using linux containers, not Windows containers (because the 
<code>Dockerfile</code> in the application references a linux base image).</p> 
+                   </div> 
+                   <div class="paragraph"> 
+                    <p>You may also need to enable the Docker daemon first, 
otherwise the "mvn install" command above will fail:</p> 
+                   </div> 
+                   <div class="imageblock"> 
+                    <div class="content"> 
+                     <a class="image" 
href="images/docker/docker-daemon.png"><img 
src="images/docker/docker-daemon.png" alt="docker daemon" width="600px"></a> 
+                    </div> 
+                   </div> 
+                   <div class="paragraph"> 
+                    <p>You might also need to ensure that the "Unidentified 
networks" are configured to be private:</p> 
+                   </div> 
+                   <div class="imageblock"> 
+                    <div class="content"> 
+                     <a class="image" 
href="images/docker/026-docker-nat-private.png"><img 
src="images/docker/026-docker-nat-private.png" alt="026 docker nat private" 
width="600px"></a> 
+                    </div> 
+                   </div> 
+                   <div class="paragraph"> 
+                    <p>This can be done using the "Local Security Policy" 
application.</p> 
+                   </div> </td> 
+                 </tr> 
+                </tbody>
+               </table> 
+              </div> </li> 
+            </ul> 
+           </div> 
+           <div class="paragraph"> 
+            <p>This too should be accessed at <a 
href="http://localhost:8080";>localhost:8080</a>.</p> 
+           </div> 
+           <div class="admonitionblock tip"> 
+            <table> 
+             <tbody>
+              <tr> 
+               <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> 
+               <td class="content"> 
+                <div class="paragraph"> 
+                 <p>The Kitematic UI tool is handy for viewing and interacting 
with running containers.</p> 
+                </div> </td> 
+              </tr> 
+             </tbody>
+            </table> 
+           </div> 
+           <div class="paragraph"> 
+            <p>In each case, check the about page and confirm has been built 
against non-SNAPSHOT versions of the Apache Isis jars.</p> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_create-the-archetype">Create
 the archetype</h5> 
+           <div class="paragraph"> 
+            <p>Make sure you are in the correct directory and environment 
variables are correct.</p> 
+           </div> 
+           <div class="paragraph"> 
+            <p>To recreate the <strong>simpleapp</strong> archetype:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">cd 
example/application/simpleapp
+env | grep ISIS | sort</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>Then, run the script:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">sh 
../../../scripts/recreate-archetype.sh $ISISJIRA</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>The script automatically commits changes; if you wish use 
<code>git log</code> and <code>git diff</code> (or a tool such as SourceTree) 
to review changes made.</p> 
+           </div> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_release-prepare">4.5.2.
 Release prepare</h4> 
+          <div class="paragraph"> 
+           <p>Switch to the <strong>archetype</strong> directory and execute 
the <code>release:prepare</code>:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code>cd 
../../../example/archetype/$ISISCPN
+rm -rf $ISISTMP/checkout
+mvn release:prepare -P apache-release \
+                -DreleaseVersion=$ISISREL \
+                -DdevelopmentVersion=$ISISDEV \
+                -Dtag=$ISISART-$ISISREL</code></pre> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_post-prepare-sanity-check">Post-prepare
 sanity check</h5> 
+           <div class="paragraph"> 
+            <p>This is a good point to test the archetype; nothing has yet 
been uploaded.</p> 
+           </div> 
+           <div class="paragraph"> 
+            <p><em>In a different session</em>, create a new app from the 
archetype. First set up environment variables:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">export 
ISISTMP=/c/tmp    # or as required
+export ISISCPN=simpleapp
+env | grep ISIS | sort</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>Then generate a new app from the archetype:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">rm -rf 
$ISISTMP/test-$ISISCPN
+
+mkdir $ISISTMP/test-$ISISCPN
+cd $ISISTMP/test-$ISISCPN
+mvn archetype:generate  \
+    -D archetypeCatalog=local \
+    -D groupId=com.mycompany \
+    -D artifactId=myapp \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=$ISISCPN-archetype</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>Build the newly generated app and test:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">cd myapp
+mvn clean install -o
+mvn -pl webapp jetty:run              # runs as mvn jetty plugin</code></pre> 
+            </div> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_simplapp_release-perform-upload">Release
 Perform (upload)</h5> 
+           <div class="paragraph"> 
+            <p>Back in the original session (in the <strong>archetype</strong> 
directory, <code>example/archetype/$ISISCPN</code>), execute 
<code>release:perform</code>:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code>mvn release:perform -P 
apache-release \
+                -DworkingDirectory=$ISISTMP/checkout</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>This will upload the artifacts to the ASF Nexus repository.</p> 
+           </div> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_setup-environment-variables">4.5.3.
 Releasing <code>helloworld</code> archetype</h4> 
+          <div class="paragraph"> 
+           <p>We now repeat the procedure for the <code>helloworld</code> 
example app.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Start by switching to the directory containing the 
<code>helloworld</code> example:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="bash">cd 
../../../example/application/helloworld</code></pre> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_setup-environment-variables">Setup
 environment variables</h5> 
+           <div class="paragraph"> 
+            <p>Update additional environment variables for the 
<code>helloworld-archetype</code> artifact:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">export 
ISISART=helloworld-archetype
+export ISISPAR=$ISISREL
+
+export ISISCPT=$(echo $ISISART | cut -d- -f2)
+export ISISCPN=$(echo $ISISART | cut -d- -f1)
+
+env | grep ISIS | sort</code></pre> 
+            </div> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_check-the-example-app">Check
 the example app</h5> 
+           <div class="paragraph"> 
+            <p>Update the parent <code>pom.xml</code> to reference the 
<em>released</em> version of Apache Isis core, eg:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="xml"><span 
class="tag">&lt;properties&gt;</span>
+    <span class="tag">&lt;isis.version&gt;</span>2.0.0-M1<span 
class="tag">&lt;/isis.version&gt;</span>
+    ...
+<span class="tag">&lt;/properties&gt;</span></code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>Finally, double check that the app</p> 
+           </div> 
+           <div class="ulist"> 
+            <ul> 
+             <li> <p>builds:</p> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">mvn 
clean install</code></pre> 
+               </div> 
+              </div> </li> 
+             <li> <p>can be run from an IDE</p> 
+              <div class="ulist"> 
+               <ul> 
+                <li> <p>mainClass=<code>org.apache.isis.WebServer</code></p> 
</li> 
+                <li> <p>args=<code>-m 
domainapp.application.HelloWorldAppManifest</code></p> </li> 
+                <li> <p>run before: <code>mvn datanucleus:enhance -o</code> in 
the root module</p> </li> 
+               </ul> 
+              </div> </li> 
+             <li> <p>can be run using the mvn jetty plugin:</p> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">mvn 
jetty:run</code></pre> 
+               </div> 
+              </div> </li> 
+             <li> <p>can be deployed as a WAR</p> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">cp 
target/helloworld.war $CATALINA_HOME/webapps/ROOT.war
+pushd $CATALINA_HOME/bin
+sh startup.sh
+tail -f ../logs/catalina.out</code></pre> 
+               </div> 
+              </div> 
+              <div class="paragraph"> 
+               <p>quit using:</p> 
+              </div> 
+              <div class="listingblock"> 
+               <div class="content"> 
+                <pre class="CodeRay highlight"><code data-lang="bash">sh 
shutdown.sh
+popd</code></pre> 
+               </div> 
+              </div> </li> 
+            </ul> 
+           </div> 
+           <div class="paragraph"> 
+            <p>This too should be accessed at <a 
href="http://localhost:8080";>localhost:8080</a>.</p> 
+           </div> 
+           <div class="paragraph"> 
+            <p>In each case, check the about page and confirm has been built 
against non-SNAPSHOT versions of the Apache Isis jars.</p> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_create-the-archetype">Create
 the archetype</h5> 
+           <div class="paragraph"> 
+            <p>Make sure you are in the correct directory and environment 
variables are correct.</p> 
+           </div> 
+           <div class="paragraph"> 
+            <p>To recreate the <strong>helloworld</strong> archetype:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">cd 
example/application/helloworld
+env | grep ISIS | sort</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>Then, run the script:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">sh 
../../../scripts/recreate-archetype.sh $ISISJIRA</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>The script automatically commits changes; if you wish use 
<code>git log</code> and <code>git diff</code> (or a tool such as SourceTree) 
to review changes made.</p> 
+           </div> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_release-prepare">4.5.4.
 Release prepare</h4> 
+          <div class="paragraph"> 
+           <p>Switch to the <strong>archetype</strong> directory and execute 
the <code>release:prepare</code>:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code>cd 
../../../example/archetype/$ISISCPN
+rm -rf $ISISTMP/checkout
+mvn release:prepare -P apache-release \
+                -DreleaseVersion=$ISISREL \
+                -DdevelopmentVersion=$ISISDEV \
+                -Dtag=$ISISART-$ISISREL</code></pre> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_post-prepare-sanity-check">Post-prepare
 sanity check</h5> 
+           <div class="paragraph"> 
+            <p>This is a good point to test the archetype; nothing has yet 
been uploaded.</p> 
+           </div> 
+           <div class="paragraph"> 
+            <p><em>In a different session</em>, create a new app from the 
archetype. First set up environment variables:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">export 
ISISTMP=/c/tmp    # or as required
+export ISISCPN=helloworld
+env | grep ISIS | sort</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>Then generate a new app from the archetype:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">rm -rf 
$ISISTMP/test-$ISISCPN
+
+mkdir $ISISTMP/test-$ISISCPN
+cd $ISISTMP/test-$ISISCPN
+mvn archetype:generate  \
+    -D archetypeCatalog=local \
+    -D groupId=com.mycompany \
+    -D artifactId=myapp \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=$ISISCPN-archetype</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>Build the newly generated app and test:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code data-lang="bash">cd myapp
+mvn clean install -o
+mvn jetty:run</code></pre> 
+            </div> 
+           </div> 
+          </div> 
+          <div class="sect4"> 
+           <h5 
id="__cgcom_cutting-a-release_releasing-the-archetypes_simplapp_release-perform-upload">Release
 Perform (upload)</h5> 
+           <div class="paragraph"> 
+            <p>Back in the original session (in the <strong>archetype</strong> 
directory, <code>example/archetype/$ISISCPN</code>), execute 
<code>release:perform</code>:</p> 
+           </div> 
+           <div class="listingblock"> 
+            <div class="content"> 
+             <pre class="CodeRay highlight"><code>mvn release:perform -P 
apache-release \
+                -DworkingDirectory=$ISISTMP/checkout</code></pre> 
+            </div> 
+           </div> 
+           <div class="paragraph"> 
+            <p>This will upload the artifacts to the ASF Nexus repository.</p> 
+           </div> 
+          </div> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="__cgcom_cutting-a-release_check-close-staging-repo">4.6. 
Check/Close Staging Repo</h3> 
+         <div class="paragraph"> 
+          <p>The <code>mvn release:perform</code> commands will have put 
release artifacts for both <code>core</code> and the <code>simpleapp</code> 
archetype into a newly created staging repository on the ASF Nexus repository 
server.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Log onto <a 
href="http://repository.apache.org";>repository.apache.org</a> (using your ASF 
LDAP account):</p> 
+         </div> 
+         <div class="imageblock"> 
+          <div class="content"> 
+           <a class="image" 
href="images/release-process/nexus-staging-0.png"><img 
src="images/release-process/nexus-staging-0.png" alt="nexus staging 0" 
width="600px"></a> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>And then check that the release has been staged (select 
<code>staging repositories</code> from left-hand side):</p> 
+         </div> 
+         <div class="imageblock"> 
+          <div class="content"> 
+           <a class="image" 
href="images/release-process/nexus-staging-1.png"><img 
src="images/release-process/nexus-staging-1.png" alt="nexus staging 1" 
width="600px"></a> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>If nothing appears in a staging repo you should stop here and 
work out why.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Assuming that the repo has been populated, make a note of its 
repo id; this is needed for the voting thread. In the screenshot above the id 
is <code>org.apache.isis-008</code>.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>After checking that the staging repository contains the artifacts 
that you expect you should close the staging repository. This will make it 
available so that people can check the release.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Press the Close button and complete the dialog:</p> 
+         </div> 
+         <div class="imageblock"> 
+          <div class="content"> 
+           <a class="image" 
href="images/release-process/nexus-staging-2.png"><img 
src="images/release-process/nexus-staging-2.png" alt="nexus staging 2" 
width="600px"></a> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Nexus should start the process of closing the repository.</p> 
+         </div> 
+         <div class="imageblock"> 
+          <div class="content"> 
+           <a class="image" 
href="images/release-process/nexus-staging-2a.png"><img 
src="images/release-process/nexus-staging-2a.png" alt="nexus staging 2a" 
width="600px"></a> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>All being well, the close should (eventually) complete 
successfully (keep hitting refresh):</p> 
+         </div> 
+         <div class="imageblock"> 
+          <div class="content"> 
+           <a class="image" 
href="images/release-process/nexus-staging-3.png"><img 
src="images/release-process/nexus-staging-3.png" alt="nexus staging 3" 
width="600px"></a> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The Nexus repository ma

<TRUNCATED>

Reply via email to