You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/07/10 09:41:35 UTC
[12/15] isis-site git commit: ISIS-1133: contributors guide
http://git-wip-us.apache.org/repos/asf/isis-site/blob/e6efa093/content/guides/cg.html
----------------------------------------------------------------------
diff --git a/content/guides/cg.html b/content/guides/cg.html
new file mode 100644
index 0000000..822ef36
--- /dev/null
+++ b/content/guides/cg.html
@@ -0,0 +1,6910 @@
+<!doctype html>
+<html class="no-js" lang="en">
+<head>
+ <meta charset="utf-8"/>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+
+ <title>Contributors Guide</title>
+
+ <!--
+ 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.
+ -->
+
+ <!-- No caching headers -->
+ <meta http-equiv="cache-control" content="no-cache" />
+ <meta http-equiv="pragma" content="no-cache" />
+ <meta http-equiv="expires" content="-1" />
+
+
+ <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
+ <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet" />
+ <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script>
+ <link href="../css/asciidoctor/colony.css" rel="stylesheet">
+ <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
+
+
+
+
+ <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet" />
+ <!--[if lt IE 9]>
+ <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.ie.css" rel="stylesheet" />
+ <![endif]-->
+
+
+ <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{font-weight: normal}
+table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
+table.CodeRay td{vertical-align: top}
+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:#00}
+.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}
+
+ pre.CodeRay code {
+ background-color: inherit;
+ border-style: none;
+ }
+
+ pre.CodeRay code > span:first-child {
+ margin-left: -5px;
+ }
+
+ .literalblock pre,
+ .listingblock pre:not(.highlight),
+ .listingblock pre[class="highlight"],
+ .listingblock pre[class^="highlight "],
+ .listingblock pre.CodeRay,
+ .listingblock pre.prettyprint {
+ background: rgb(253, 250, 246);
+ }
+ .sidebarblock .literalblock pre,
+ .sidebarblock .listingblock pre:not(.highlight),
+ .sidebarblock .listingblock pre[class="highlight"],
+ .sidebarblock .listingblock pre[class^="highlight "],
+ .sidebarblock .listingblock pre.CodeRay,
+ .sidebarblock .listingblock pre.prettyprint {
+ background: rgb(253, 250, 246);
+ }
+
+ <style>
+
+ <style>
+ .github-fork-ribbon-wrapper.right {
+ position: fixed;
+ }
+ .github-fork-ribbon {
+ background: #090;
+ }
+ .github-fork-ribbon a:hover {
+ background:#0D0;
+ color:#fff;
+ font-size: 1.1em;
+ }
+ </style>
+
+ <style>
+ @media only screen and (min-width: 40.063em) {
+ .top-bar {
+ .contain-to-grid .top-bar {
+ max-width: 80rem;
+ }
+ }
+ }
+ .row {
+ max-width: 80rem;
+ }
+ </style>
+
+ <style>
+ .extended-quote,
+ .extended-quote-first {
+ margin-left: 40px;
+ margin-right: 40px;
+ font-style: italic;
+ }
+ .extended-quote-attribution {
+ text-align: right;
+ margin-right: 100px;
+ color: #10B061;
+ }
+
+ .extended-quote-first:before {
+ content: "\201c";
+ float: left;
+ font-size: 2.75em;
+ font-weight: bold;
+ line-height: 0.6em;
+ margin-left: -0.6em;
+ color: #003b6b;
+ text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
+ }
+ </style>
+
+ <style>
+ body {
+ position: relative;
+ }
+
+ *:not(pre) a > code {
+ color: #210DDC;
+ }
+
+ *:not(pre) > code {
+ background-color: inherit;
+ border: none;
+ font-weight: normal;
+ }
+
+ body div#toc li,
+ body div#toc2 li {
+ list-style-type: none;
+ }
+
+ div#doc-content {
+ margin-top: 30px;
+ }
+
+ body div#toc li.active-region:before,
+ body div#toc2 li.active-region:before {
+ content: "\00BB \0020";
+ margin-left: -12px;
+ }
+
+ body div#toc li a.active,
+ body div#toc2 li a.active {
+ color: red;
+ }
+
+ body div#toc.toc,
+ body div#toc.toc2 {
+ position: fixed;
+ left: auto;
+ padding-top: 60px;
+ z-index: auto;
+ background-color: white;
+ border-left-color: #eee;
+ border-left-style: solid;
+ border-right: none;
+ min-height: 2000px;
+ }
+
+ </style>
+
+ <style>
+
+ @media only screen and (min-width: 768px) {
+ #toc.toc2 ul ul { margin-left: -10px; }
+ }
+
+
+ body div#toc .tocify-subheader ul {
+ margin-bottom: 0px;
+ }
+
+ body div#toc .tocify-subheader li {
+ font-size: 14px;
+ }
+ .tocify li.tocify-item, .tocify ul.tocify-item {
+ line-height: 24px;
+ }
+
+ body div#toc li.tocify-item.active:before,
+ body div#toc2 li.tocify-item.active:before {
+ content: "\00BB \0020";
+ margin-left: -12px;
+ }
+
+ body div#toc li.tocify-item.active a,
+ body div#toc2 li.tocify-item.active a {
+ color: red;
+ }
+ </style>
+
+ <style>
+ footer {
+ margin-top: 1000px;
+ }
+ </style>
+
+ <style>
+ /* overriding colony.css stylesheet */
+ .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] {
+ /*padding: 1.25em 1.5625em 1.125em 1.5625em;*/
+ padding: 0.3em 0.6em 0.25em 0.6em;
+ }
+ @media only screen and (min-width: 1280px)
+ #toc.toc2 {
+ /*width: 20em;*/
+ width: 25em;
+ }
+
+ #doc-content a {
+ color: #210DDC;
+ }
+
+ .top-bar h1 {
+ border-bottom: inherit;
+ }
+
+ h2 {
+ margin-top: 80px;
+ }
+ h3 {
+ margin-top: 40px;
+ }
+ h4,h5 {
+ margin-top: 30px;
+ }
+
+ .admonitionblock.tip > table td.content {
+ color: #10B061;
+ }
+ .admonitionblock.note > table td.content {
+ color: #B509AB;
+ }
+ .admonitionblock.important > table td.content {
+ color: #D5810A;
+ }
+
+ .admonitionblock .title {
+ font-size: larger;
+ font-style: italic;
+ }
+
+ .imageblock img {
+ margin-bottom: 10px;
+ }
+ </style>
+
+ <style>
+ /* from http://ben.balter.com/2014/03/13/pages-anchor-links/ */
+ .header-link {
+ position: absolute;
+ left: -0.5em;
+ opacity: 0;
+
+ /*
+ -webkit-transition: opacity 0.2s ease-in-out 0.1s;
+ -moz-transition: opacity 0.2s ease-in-out 0.1s;
+ -ms-transition: opacity 0.2s ease-in-out 0.1s;
+ */
+ }
+
+ h2:hover .header-link,
+ h3:hover .header-link,
+ h4:hover .header-link,
+ h5:hover .header-link,
+ h6:hover .header-link {
+ opacity: 1;
+ }
+ </style>
+
+ <style>
+ .top-bar
+ {
+ -webkit-transition-duration: .5s;
+ transition-duration: .5s;
+
+ -webkit-transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 );
+ transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 );
+
+ -webkit-transition-property: -webkit-transform;
+ transition-property: transform;
+ }
+
+ /*
+ http://osvaldas.info/auto-hide-sticky-header
+ MIT license
+ */
+ .header--hidden
+ {
+ -webkit-transform: translateY( -100% );
+ -ms-transform: translateY( -100% );
+ transform: translateY( -100% );
+
+ transition-duration: .5s;
+ transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 );
+ -webkit-transition-property: -webkit-transform;
+ transition-property: transform;
+ }
+ </style>
+
+ <style>
+ #doc-content a.guide {
+ color: white;
+ }
+ </style>
+
+ <style>
+ .tocify {
+ margin-top: 80px;
+ }
+ </style>
+
+
+</script>
+
+</head>
+<body>
+
+<<div class="github-fork-ribbon-wrapper right" style="position: fixed;">
+ <div class="github-fork-ribbon">
+ <a href="https://github.com/apache/isis/fork">Fork me on GitHub</a>
+ </div>
+</div>
+
+
+<div class="row">
+
+ <div class="fixed contain-to-grid header">
+ <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
+ <ul class="title-area">
+ <li class="name">
+ <h1>
+ <a href="/index.html">Apache Isis™</a>
+ </h1>
+ </li>
+ <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
+ <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
+ </ul>
+
+ <section class="top-bar-section">
+ <ul class="right">
+
+ <li class="has-form">
+ <FORM class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
+ <div class="row collapse">
+ <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
+ <INPUT type="hidden" name="cof" value="FORID:0">
+ <INPUT class="form-control" name="q" type="text" placeholder="Search">
+ </div>
+ </FORM>
+ </li>
+
+ </ul>
+
+ <!-- Left Nav Section -->
+ <ul class="left">
+
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/downloads.html">Downloads</a></li>
+ <li><a href="/help.html">Help</a></li>
+ <li><a href="/asf.html">@ASF</a></li>
+
+ </ul>
+
+ </section>
+ </nav>
+ </div>
+</div>
+
+<div class="row">
+
+ <div id="doc-content-left" class="large-9 medium-9 columns">
+
+
+ <div id="doc-content">
+ <div class="sect1">
+<h2 id="_cg">1. Contributors' Guide</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>This contributors' guide has three related audiences:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>programmers who want to just use Apache Isis to build applications, and want help setting up their development environment or to build their code from the command line (eg to execute within a continuous integration server such as Jenkins)</p>
+</li>
+<li>
+<p>programmers who want to contribute back patches (bug fixes, new features) either to the codebase or the framework’s documentation</p>
+</li>
+<li>
+<p>committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The developer' guide is <em>not</em> intended as a reference manual; for that see the <strong><a href="rg.html#<em>rg">Reference Guide</a></strong>. This guide also does _not</em> describe how to actually build an Apache Isis application; for that see the <strong><a href="ug.html#_ug">Users' Guide</a></strong>.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cg_ide">2. Using an IDE</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do like wise as you develop your Apache Isis applications using an IDE. Apache Isis is built with Maven, and all modern IDEs can import Maven projects.</p>
+</div>
+<div class="paragraph">
+<p>This chapter shows how to setup and use two of the most popular IDEs, IntelliJ IDEA and Eclipse.</p>
+</div>
+<div class="sect2">
+<h3 id="_cg_ide_intellij">2.1. Developing using IntelliJ IDEA</h3>
+<div class="paragraph">
+<p>This section describes how to install and setup IntelliJ, then how to import an application into IntelliJ and run it.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>This document relates to IntelliJ Community Edition 14.1.x, with screenshots taken for Windows.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect3">
+<h4 id="_installing_and_setting_up">2.1.1. Installing and Setting up</h4>
+<div class="paragraph">
+<p>This section covers installation and setup.</p>
+</div>
+<div class="sect4">
+<h5 id="_download_and_install">Download and Install</h5>
+<div class="paragraph">
+<p><a href="https://www.jetbrains.com/idea/download/">Download</a> latest version of IntelliJ Community Edition, and install:</p>
+</div>
+<div class="paragraph">
+<p>Start the wizard, click through the welcome page:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png" alt="010 welcome page" width="400px">
+</div>
+<div class="title">Figure 1. IntelliJ Installation Wizard - Welcome page</div>
+</div>
+<div class="paragraph">
+<p>Choose the location to install the IDE:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png" alt="020 choose location" width="400px">
+</div>
+<div class="title">Figure 2. IntelliJ Installation Wizard - Choose Location</div>
+</div>
+<div class="paragraph">
+<p>Adjust any installation options as you prefer:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png" alt="030 installation options" width="400px">
+</div>
+<div class="title">Figure 3. IntelliJ Installation Wizard - Installation Options</div>
+</div>
+<div class="paragraph">
+<p>and the start menu:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png" alt="040 start menu folder" width="400px">
+</div>
+<div class="title">Figure 4. IntelliJ Installation Wizard - Start Menu Folder</div>
+</div>
+<div class="paragraph">
+<p>and finish up the wizard:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/010-installing/050-completing.png" alt="050 completing" width="400px">
+</div>
+<div class="title">Figure 5. IntelliJ Installation Wizard - Completing the Wizard</div>
+</div>
+<div class="paragraph">
+<p>Later on we’ll specify the Apache Isis/ASF code style settings, so for now select <code>I do not want to import settings</code>:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png" alt="060 import settings or not" width="400px">
+</div>
+<div class="title">Figure 6. IntelliJ Installation Wizard - Import Settings</div>
+</div>
+<div class="paragraph">
+<p>Finally, if you are young and trendy, set the UI theme to Darcula:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png" alt="070 set ui theme" width="600px">
+</div>
+<div class="title">Figure 7. IntelliJ Installation Wizard Set UI Theme</div>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_new_project">New Project</h5>
+<div class="paragraph">
+<p>In IntelliJ a project can contain multiple modules; these need not be physically located together. (If you are previously an Eclipse user, you can think of it as similar to an Eclipse workspace).</p>
+</div>
+<div class="paragraph">
+<p>Start off by creating a new project:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png" alt="010 new project create" width="400px">
+</div>
+<div class="title">Figure 8. IntelliJ Create New Project</div>
+</div>
+<div class="paragraph">
+<p>We want to create a new <strong>Java</strong> project:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png" alt="020 java project setup jdk" width="600px">
+</div>
+<div class="title">Figure 9. IntelliJ Create New Project - Create a Java project</div>
+</div>
+<div class="paragraph">
+<p>We therefore need to specify the JDK.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+at the time of writing Apache Isis supports only Java 7; Java 8 is scheduled for support in Apache Isis v1.9.0
+</td>
+</tr>
+</table>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png" alt="030 java project select jdk" width="300px">
+</div>
+<div class="title">Figure 10. IntelliJ Create New Java Project - Select the JDK</div>
+</div>
+<div class="paragraph">
+<p>Specify the directory containing the JDK:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png" alt="050 name and location" width="400px">
+</div>
+<div class="title">Figure 11. IntelliJ Create New Project - Select the JDK location</div>
+</div>
+<div class="paragraph">
+<p>Finally allow IntelliJ to create the directory for the new project:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png" alt="060 create dir" width="200px">
+</div>
+<div class="title">Figure 12. IntelliJ Create New Project</div>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_import_settings">Import Settings</h5>
+<div class="paragraph">
+<p>Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions. These are bundled as the <code>settings.jar</code> JAR file <a href="resources/appendices/dev-env/intellij/isis-settings.jar">download from the Apache Isis website</a>).</p>
+</div>
+<div class="paragraph">
+<p>Import using: <code>File > Import Settings</code>, and specify the directory that you have downloaded the file to:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png" alt="010 settings import jar" width="400px">
+</div>
+<div class="title">Figure 13. IntelliJ Import Settings - Specify JAR file</div>
+</div>
+<div class="paragraph">
+<p>Select all the (two) categories of settings available in the JAR file:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png" alt="020 select all" width="300px">
+</div>
+<div class="title">Figure 14. IntelliJ Import Settings - Select all categories</div>
+</div>
+<div class="paragraph">
+<p>And then restart:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png" alt="030 restart" width="200px">
+</div>
+<div class="title">Figure 15. IntelliJ Import Settings - Restart</div>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_other_settings">Other Settings</h5>
+<div class="paragraph">
+<p>There are also some other miscellaneous settings that we recommend that you adjust (though these are not critical).</p>
+</div>
+<div class="paragraph">
+<p>First, specify an up-to-date Maven installation, using <code>File > Settings</code> (or <code>IntelliJ > Preferences</code> if on MacOS):</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png" alt="010 maven installation" width="600px">
+</div>
+<div class="title">Figure 16. IntelliJ Other Settings - Maven Installation</div>
+</div>
+<div class="paragraph">
+<p>Still on the Maven settings page, configure as follows:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png" alt="020 maven configuration" width="600px">
+</div>
+<div class="title">Figure 17. IntelliJ Other Settings - Maven Configuration</div>
+</div>
+<div class="paragraph">
+<p>On the compiler settings page, ensure that <code>build automatically</code> is enabled (and optionally <code>compile independent modules in parallel</code>):</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png" alt="030 build automatically" width="600px">
+</div>
+<div class="title">Figure 18. IntelliJ Other Settings - Compiler Settings</div>
+</div>
+<div class="paragraph">
+<p>On the auto import page, check the <code>optimize imports on the fly</code> and <code>add unambiguous imports on the fly</code></p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png" alt="040 auto import" width="600px">
+</div>
+<div class="title">Figure 19. IntelliJ Other Settings - Auto Import</div>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_plugins">Plugins</h5>
+<div class="paragraph">
+<p>You might also want to set up some additional plugins, using <code>File > Settings > Plugins</code> (or equivalently <code>File > Other Settings > Configure Plugins</code>).</p>
+</div>
+<div class="paragraph">
+<p>Recommended are:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="https://plugins.jetbrains.com/plugin/7179?pr=idea">Maven Helper</a> plugin</p>
+<div class="paragraph">
+<p>More on this below.</p>
+</div>
+</li>
+<li>
+<p><a href="https://github.com/asciidoctor/asciidoctor-intellij-plugin">AsciiDoctor</a> plugin</p>
+<div class="paragraph">
+<p>Useful if you are doing any authoring of documents.</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Some others you might like to explore are:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png" alt="020 some plugins confirmation" width="600px">
+</div>
+<div class="title">Figure 20. IntelliJ Plugins</div>
+</div>
+<div class="sect5">
+<h6 id="_maven_helper_plugin">Maven Helper Plugin</h6>
+<div class="paragraph">
+<p>This plugin provides a couple of great features. One is better visualization of dependency trees (similar to Eclipse).</p>
+</div>
+<div class="paragraph">
+<p>If you open a <code>pom.xml</code> file, you’ll see an additional "Dependencies" tab:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"><img src="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png" alt="010 dependency tab" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by <code>mvn dependency:tree</code>, but filterable.</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"><img src="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png" alt="020 dependency as tree" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>The plugin also provides the ability to easily run a Maven goal on a project:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"><img src="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png" alt="030 maven run goal" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>This menu can also be bound to a keystroke so that it is available as a pop-up:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"><img src="images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png" alt="040 maven quick run" width="600px"></a>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_importing_and_managing_maven_modules">2.1.2. Importing and Managing Maven Modules</h4>
+<div class="paragraph">
+<p>Let’s load in some actual code! We do this by importing the Maven modules.</p>
+</div>
+<div class="paragraph">
+<p>First up, open up the Maven tool window (<code>View > Tool Windows > Maven Projects</code>). You can then use the 'plus' button to add Maven modules. In the screenshot you can see we’ve loaded in Apache Isis core; the modules are listed in the <em>Maven Projects</em> window and corresponding (IntelliJ) modules are shown in the <em>Projects</em> window:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png" alt="010 maven modules view" width="730px">
+</div>
+<div class="title">Figure 21. IntelliJ Maven Module Management - Importing Maven modules</div>
+</div>
+<div class="paragraph">
+<p>We can then import another module (from some other directory). For example, here we are importing the Isis Addons' todoapp example:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png" alt="020 adding another module" width="400px">
+</div>
+<div class="title">Figure 22. IntelliJ Maven Module Management - Importing another Module</div>
+</div>
+<div class="paragraph">
+<p>You should then see the new Maven module loaded in the <em>Projects</em> window and also the <em>Maven Projects</em> window:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png" alt="030 other module added" width="730px">
+</div>
+<div class="title">Figure 23. IntelliJ Maven Module Management -</div>
+</div>
+<div class="paragraph">
+<p>If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from <code>.m2/repository</code> folder). So, for example (assuming that the <code><version></code> is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.</p>
+</div>
+<div class="paragraph">
+<p>You can press F4 (or use <code>File > Project Structure</code>) to see the resolved classpath for any of the modules loaded into the project.</p>
+</div>
+<div class="paragraph">
+<p>If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you <em>could</em> remove the module; but better is to ignore those modules. This will remove from the the <em>Projects</em> window but keep them available in the <em>Maven Projects</em> window for when you next want to work on them:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png" alt="040 ignoring modules" width="730px">
+</div>
+<div class="title">Figure 24. IntelliJ Maven Module Management - Ignoring Modules</div>
+</div>
+<div class="paragraph">
+<p>Confirm that it’s ok to ignore these modules:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png" alt="050 ignoring modules 2" width="300px">
+</div>
+<div class="title">Figure 25. IntelliJ Maven Module Management - Ignoring Modules (ctd)</div>
+</div>
+<div class="paragraph">
+<p>All being well you should see that the <em>Projects</em> window now only contains the code you are working on. Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from <code>.m2/repository</code>):</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png" alt="060 ignored modules" width="730px">
+</div>
+<div class="title">Figure 26. IntelliJ Maven Module Management - Updated Projects Window</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_running">2.1.3. Running</h4>
+<div class="paragraph">
+<p>Let’s see how to run both the app and the tests.</p>
+</div>
+<div class="sect4">
+<h5 id="_running_the_app">Running the App</h5>
+<div class="paragraph">
+<p>Once you’ve imported your Isis application, we should run it. We do this by creating a Run configuration, using <code>Run > Edit Configurations</code>.</p>
+</div>
+<div class="paragraph">
+<p>Set up the details as follows:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png" alt="010 run configuration" width="600px">
+</div>
+<div class="title">Figure 27. IntelliJ Running the App - Run Configuration</div>
+</div>
+<div class="paragraph">
+<p>We specify the <code>Main class</code> to be <code>org.apache.isis.WebServer</code>; this is a wrapper around Jetty. It’s possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.</p>
+</div>
+<div class="paragraph">
+<p>Also note that <code>Use classpath of module</code> is the webapp module for your app, and that the <code>working directory</code> is <code>$MODULE_DIR$</code>.</p>
+</div>
+<div class="paragraph">
+<p>Next, and most importantly, configure the DataNucleus enhancer to run for your <code>dom</code> goal. This can be done by defining a Maven goal to run before the app:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png" alt="020 datanucleus enhancer goal" width="400px">
+</div>
+<div class="title">Figure 28. IntelliJ Running the App - Datanucleus Enhancer Goal</div>
+</div>
+<div class="paragraph">
+<p>The <code>-o</code> flag in the goal means run off-line; this will run faster.</p>
+</div>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
+if you forget to set up the enhancer goal, or don’t run it on the correct (dom) module, then you will get all sorts of errors when you startup. These usually manifest themselves as class cast exception in DataNucleus.
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>You should now be able to run the app using <code>Run > Run Configuration</code>. The same configuration can also be used to debug the app if you so need.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_running_the_unit_tests">Running the Unit Tests</h5>
+<div class="paragraph">
+<p>The easiest way to run the unit tests is just to right click on the <code>dom</code> module in the <em>Project Window</em>, and choose run unit tests. Hopefully your tests will pass (!).</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png" alt="030 running unit tests" width="600px">
+</div>
+<div class="title">Figure 29. IntelliJ Running the App - Unit Tests Run Configuration</div>
+</div>
+<div class="paragraph">
+<p>As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png" alt="040 running unit tests run configuration" width="600px">
+</div>
+<div class="title">Figure 30. IntelliJ Running the App - Unit Tests Run Configuration</div>
+</div>
+<div class="paragraph">
+<p>Thereafter, you should run units by selecting this configuration (if you use the right click approach you’ll end up with lots of run configurations, all similar).</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_running_the_integration_tests">Running the Integration Tests</h5>
+<div class="paragraph">
+<p>Integration tests can be run in the same way as unit tests, however the <code>dom</code> module must also have been enhanced.</p>
+</div>
+<div class="paragraph">
+<p>One approach is to initially run the tests use the right click on the <code>integtests</code> module; the tests will fail because the code won’t have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png" alt="050 running integration tests run configuration" width="600px">
+</div>
+<div class="title">Figure 31. IntelliJ Running the App - Integration Tests Run Configuration</div>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_hints_and_tips">2.1.4. Hints and Tips</h4>
+<div class="sect4">
+<h5 id="_keyboard_shortcuts_cheat_sheets">Keyboard Shortcuts Cheat Sheets</h5>
+<div class="paragraph">
+<p>You can download 1-page PDFs cheat sheets for IntelliJ’s keyboard shortcuts:
+* for <a href="https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf">Windows</a>
+* for MacOS:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]</p>
+</div>
+<div class="paragraph">
+<p>Probably the most important shortcut on them is for <code>Find Action</code>:
+- <code>ctrl-shift-A</code> on Windows
+- <code>cmd-shift-A</code> on MacOS.</p>
+</div>
+<div class="paragraph">
+<p>This will let you search for any action just by typing its name.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_switching_between_tool_windows_and_editors">Switching between Tool Windows and Editors</h5>
+<div class="paragraph">
+<p>The Tool Windows are the views around the editor (to left, bottom and right). It’s possible to move these around to your preferred locations.</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Use <code>alt-1</code> through <code>alt-9</code> (or <code>cmd-1</code> through <code>alt-9</code>) to select the tool windows</p>
+<div class="ulist">
+<ul>
+<li>
+<p>Press it twice and the tool window will hide itself; so can use to toggle</p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>If in the <em>Project Window</em> (say) and hit enter on a file, then it will be shown in the editor, but (conveniently) the focus remains in the tool window. To switch to the editor, just press <code>Esc</code>.</p>
+<div class="ulist">
+<ul>
+<li>
+<p>If in the <em>Terminal Window</em>, you’ll need to press <code>Shift-Esc</code>.</p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>If on the editor and want to locate the file in (say) the <em>Project Window</em>, use <code>alt-F1</code>.</p>
+</li>
+<li>
+<p>To change the size of any tool window, use <code>ctrl-shift-arrow</code></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_navigating_around">Navigating Around</h5>
+<div class="paragraph">
+<p>For all of the following, you don’t need to type every letter, typing "ab" will actually search for ".<strong>a.*b.</strong>".</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>to open classes or files or methods that you know the name of:</p>
+<div class="ulist">
+<ul>
+<li>
+<p><code>ctrl-N</code> to open class</p>
+</li>
+<li>
+<p><code>ctrl-shift-N</code> to open a file</p>
+</li>
+<li>
+<p>(bit fiddly this) <code>ctrl-shift-alt-N</code> to search for any symbol.</p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>open up dialog of recent files: <code>ctrl-E</code></p>
+</li>
+<li>
+<p>search for any file: <code>shift-shift</code></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Navigating around:
+* find callers of a method (the call hierarchy): <code>ctrl-alt-H</code>
+* find subclasses or overrides: <code>ctrl-alt-B</code>
+* find superclasses/interface/declaration: <code>ctrl-B</code></p>
+</div>
+<div class="paragraph">
+<p>Viewing the structure (ie outline) of a class
+* <code>ctrl-F12</code> will pop-up a dialog showing all members
+** hit <code>ctrl-F12</code> again to also see inherited members</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_editing">Editing</h5>
+<div class="ulist">
+<ul>
+<li>
+<p>Extend selection using <code>ctrl-W</code></p>
+<div class="ulist">
+<ul>
+<li>
+<p>and contract it down again using <code>ctrl-shift-W</code></p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>to duplicate a line, it’s <code>ctrl-D</code></p>
+<div class="ulist">
+<ul>
+<li>
+<p>if you have some text selected (or even some lines), it’ll actually duplicate the entire selection</p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>to delete a line, it’s <code>ctrl-X</code></p>
+</li>
+<li>
+<p>to move a line up or down: <code>shift-alt-up</code> and <code>shift-alt-down</code></p>
+<div class="ulist">
+<ul>
+<li>
+<p>if you have selected several lines, it’ll move them all togethe</p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p><code>ctrl-shift-J</code> can be handy for joining lines together</p>
+<div class="ulist">
+<ul>
+<li>
+<p>just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")</p>
+</li>
+</ul>
+</div>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_intentions_and_code_completion">Intentions and Code Completion</h5>
+<div class="paragraph">
+<p>Massively useful is the "Intentions" popup; IntelliJ tries to guess what you might want to do. You can activate this using`alt-enter`, whenever you see a lightbulb/tooltip in the margin of the current line.</p>
+</div>
+<div class="paragraph">
+<p>Code completion usually happens whenever you type '.'. You can also use <code>ctrl-space</code> to bring these up.</p>
+</div>
+<div class="paragraph">
+<p>In certain circumstances (eg in methods0) you can also type <code>ctrl-shift-space</code> to get a smart list of methods etc that you might want to call. Can be useful.</p>
+</div>
+<div class="paragraph">
+<p>Last, when invoking a method, use <code>ctrl-P</code> to see the parameter types.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_refactoring">Refactoring</h5>
+<div class="paragraph">
+<p>Loads of good stuff on the <code>Refactor</code> menu; most used are:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Rename (<code>shift-F6</code>)</p>
+</li>
+<li>
+<p>Extract</p>
+<div class="ulist">
+<ul>
+<li>
+<p>method: <code>ctrl-alt-M</code></p>
+</li>
+<li>
+<p>variable: <code>ctrl-alt-V</code></p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>Inline method/variable: <code>ctrl-alt-N</code></p>
+</li>
+<li>
+<p>Change signature</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>If you can’t remember all those shortcuts, just use <code>ctrl-shift-alt-T</code> (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_troubleshooting">Troubleshooting</h5>
+<div class="paragraph">
+<p>When a Maven module is imported, IntelliJ generates its own project files (suffix <code>.ipr</code>), and the application is actually built from that.</p>
+</div>
+<div class="paragraph">
+<p>Occasionally these don’t keep in sync (even if auto-import of Maven modules has been enabled).</p>
+</div>
+<div class="paragraph">
+<p>To fix the issue, try:
+* reimport module
+* rebuild selected modules/entire project
+* remove and then re-add the project
+* restart, invalidating caches
+* hit StackOverflow (!)</p>
+</div>
+<div class="paragraph">
+<p>One thing worth knowing; IntelliJ actively scans the filesystem all the time. It’s therefore (almost always) fine to build the app from the Maven command line; IntelliJ will detect the changes and keep in sync. If you want to force that, use <code>File > Synchronize</code>, <code>ctrl-alt-Y</code>.</p>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_advanced">2.1.5. Advanced</h4>
+<div class="paragraph">
+<p>In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.</p>
+</div>
+<div class="sect4">
+<h5 id="_setting_up_dynamic_reloading">Setting up Dynamic Reloading</h5>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+TODO - see <a href="http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/">IntelliJ blog</a>.
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_setting_up_jrebel">Setting up JRebel</h5>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+TODO
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_cg_ide_eclipse">2.2. Developing using Eclipse</h3>
+<div class="paragraph">
+<p>If you are an <a href="http://www.eclipse.org">Eclipse</a> user, then we recommend you download the "Eclipse JEE package" configuration.</p>
+</div>
+<div class="paragraph">
+<p>When running an Apache Isis application, it’s necessary to setup the development environment so that the Java bytecode can be enhanced by the <a href="http://www.datanucleus.org">DataNucleus</a> enhancer. If working in Eclipse, then JDO enhancement is most easily done by installing the <a href="http://www.datanucleus.org/products/datanucleus/jdo/guides/eclipse.html">DataNucleus' Eclipse plugin</a>. This hooks the bytecode enhancement of your domain objects into Eclipse’s normal incremental compilation.</p>
+</div>
+<div class="paragraph">
+<p>This plugin needs to be configured for each of your domain modules (usually just one in any given app). The steps are therefore:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>import the project into Eclipse</p>
+</li>
+<li>
+<p>configure the DataNucleus enhancer</p>
+</li>
+<li>
+<p>run the app from the <code>.launch</code> file</p>
+</li>
+</ul>
+</div>
+<div class="sect3">
+<h4 id="_screencast">2.2.1. Screencast</h4>
+<div class="paragraph">
+<p>The following screencast shows how to import an Apache Isis maven-based application into Eclipse and configure to use with the JDO Objectstore</p>
+</div>
+<div class="videoblock">
+<div class="content">
+<iframe width="640px" height="480px" src="//www.youtube.com/embed/RgcYfjQ8yJA?rel=0" frameborder="0" allowfullscreen></iframe>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_importing_the_project">2.2.2. Importing the Project</h4>
+<div class="paragraph">
+<p>Use File > Import, then Maven > Existing Maven Projects.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_add_datanucleus_support">2.2.3. Add DataNucleus support</h4>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>In Eclipse, for the <em>domain object model</em> project, first add DataNucleus support:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/appendices/dev-env/eclipse/eclipse-100-project-support.png"><img src="images/appendices/dev-env/eclipse/eclipse-100-project-support.png" alt="eclipse 100 project support" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>Then turn on Auto-Enhancement:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/appendices/dev-env/eclipse/eclipse-110-project-support.png"><img src="images/appendices/dev-env/eclipse/eclipse-110-project-support.png" alt="eclipse 110 project support" width="600px"></a>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_update_the_classpath">Update the classpath</h5>
+<div class="paragraph">
+<p>DataNucleus' enhancer uses the domain object model’s own classpath to reference DataNucleus JARs. So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.</p>
+</div>
+<div class="paragraph">
+<p>See the earlier section on <a href="ug.html#_ug_getting-started_datanucleus-enhancer">DataNucleus enhancer</a> for details of the contents of the <code>pom.xml</code>. Chances are it is already set up from running the <a href="ug.html#_ug_getting-started_simpleapp-archetype">SimpleApp archetype</a>.</p>
+</div>
+<div class="paragraph">
+<p>Then, tell DataNucleus to use the project classpath:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images//appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"><img src="images//appendices/dev-env/eclipse/eclipse-010-windows-preferences.png" alt="eclipse 010 windows preferences" width="750px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>When the enhancer runs, it will print out to the console:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images//appendices/dev-env/eclipse/eclipse-120-console.png"><img src="images//appendices/dev-env/eclipse/eclipse-120-console.png" alt="eclipse 120 console" width="500px"></a>
+</div>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_workaround_for_path_limits_the_dn_plugin_to_use_the_persistence_xml">Workaround for path limits (the DN plugin to use the persistence.xml)</h5>
+<div class="paragraph">
+<p>If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.</p>
+</div>
+<div class="paragraph">
+<p>To fix this, we configure the enhancer to read from the <code>persistence.xml</code> file.</p>
+</div>
+<div class="paragraph">
+<p>As a prerequisite, first make sure that your domain object model has a <code>persistence.xml</code> file. Then specify the <code>persistence-unit</code> in the project properties:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images//appendices/dev-env/eclipse/eclipse-025-project-properties.png"><img src="images//appendices/dev-env/eclipse/eclipse-025-project-properties.png" alt="eclipse 025 project properties" width="750px"></a>
+</div>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_workaround_if_the_enhancer_fails">Workaround: If the enhancer fails</h5>
+<div class="paragraph">
+<p>On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we’ve noticed multiple entries in the Eclipse’s <code>Debug</code> view:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images//appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"><img src="images//appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png" alt="eclipse 210 enhancer fails duplicates" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>At any rate, you’ll know you’ve encountered this error if you see the following in the console:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images//appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"><img src="images//appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png" alt="eclipse 200 enhancer fails duplicates" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>The best solution is to remove DataNucleus support and then to re-add it:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images//appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"><img src="images//appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png" alt="eclipse 220 enhancer fails duplicates" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.</p>
+</div>
+<div class="paragraph">
+<p>Not ideal, we know. Please feel free to contribute a better solution :-)</p>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_running_the_app_2">2.2.4. Running the App</h4>
+<div class="paragraph">
+<p>The simpleapp archetype automatically provides a <code>.launch</code> configurations in the <code>webapp</code> module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The screencast above shows this in action.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_other_domain_projects">2.2.5. Other domain projects.</h4>
+<div class="paragraph">
+<p>There is nothing to prevent you having multiple domain projects. You might want to do such that each domain project corresponds to a <a href="http://www.methodsandtools.com/archive/archive.php?id=97p2">DDD module</a>, thus guaranteeing that there are no cyclic dependencies between your modules.</p>
+</div>
+<div class="paragraph">
+<p>If you do this, make sure that each project has its own <code>persistence.xml</code> file.</p>
+</div>
+<div class="paragraph">
+<p>And, remember also to configure Eclipse’s DataNucleus plugin for these other domain projects.</p>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cg_ide-templates">3. IDE Templates</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>We provide IDE templates (for IntelliJ and Eclipse) for writing Apache Isis domain objects, and also for unit tests (JUnit and JMock).</p>
+</div>
+<div class="sect2">
+<h3 id="_download">3.1. Download</h3>
+<div class="paragraph">
+<p>The following table lists the templates to download</p>
+</div>
+<table class="tableblock frame-all grid-all spread">
+<colgroup>
+<col style="width: 25%;">
+<col style="width: 25%;">
+<col style="width: 25%;">
+<col style="width: 25%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Template</th>
+<th class="tableblock halign-left valign-top">Prefix</th>
+<th class="tableblock halign-left valign-top">IntelliJ</th>
+<th class="tableblock halign-left valign-top">Eclipse</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>Apache Isis Domain Objects</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>is</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p><a href="./resources/templates/isis-templates-idea.xml">Download</a></p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p><a href="./resources/templates/isis-templates.xml">Download</a></p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>JUnit tests</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>ju</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p><a href="./resources/templates/junit4-templates-idea.xml">Download</a></p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p><a href="./resources/templates/junit4-templates.xml">Download</a></p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>JMock tests</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>jm</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p><a href="./resources/templates/jmock2-templates-idea.xml">Download</a></p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p><a href="./resources/templates/jmock2-templates.xml">Download</a></p>
+</div></div></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph">
+<p>The most commonly used Apache Isis domain objects templates are also listed on the <a href="./cheat-sheet.html">Apache Isis cheat sheet</a>.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_installation">3.2. Installation</h3>
+<div class="sect3">
+<h4 id="_intellij">3.2.1. IntelliJ</h4>
+<div class="paragraph">
+<p>To install in IntelliJ, copy to the relevant <code>config/templates</code> directory, eg:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Windows <code><User home>\.IntelliJIdea14\config\templates</code></p>
+</li>
+<li>
+<p>Linux <code>~/.IntelliJIdea14/config/templates</code></p>
+</li>
+<li>
+<p>Mac OS <code>~/Library/Preferences/IntelliJIdea14/templates</code></p>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_eclipse">3.2.2. Eclipse</h4>
+<div class="paragraph">
+<p>To install in Eclipse, go to <code>Windows > Preferences > Java > Editor > Templates</code> and choose <code>Import</code>.</p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_usage">3.3. Usage</h3>
+<div class="paragraph">
+<p>Enter the prefix (<code>is</code>, <code>ju</code>, <code>jm</code>) and the IDE will list all available templates in that category.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cg_cmd-line">4. Command Line and CI</h2>
+<div class="sectionbody">
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+TODO
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cg_isis-maven-plugin">5. Apache Isis Maven Plugin</h2>
+<div class="sectionbody">
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+TODO
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cg_building-isis">6. Building Apache Isis</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_git">6.1. Git</h3>
+<div class="paragraph">
+<p>The Apache Isis source code lives in a git repo.</p>
+</div>
+<div class="sect3">
+<h4 id="_installation_2">6.1.1. Installation</h4>
+<div class="paragraph">
+<p>The easiest place to get hold of command-line git is probably the <a href="http://git-scm.com/downloads">github download page</a>.</p>
+</div>
+<div class="paragraph">
+<p>On Windows, this also installs the rather good mSysGit Unix shell. We recommend that you enable git for both the mSysgit and the Windows command prompt:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/building-isis/setting-up-git.png"><img src="images/building-isis/setting-up-git.png" alt="setting up git" width="350px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>Once git is installed, the two main command line tools to note are:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>git</code> command line tool</p>
+</li>
+<li>
+<p><code>gitk</code> for viewing the commit history</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>If using Windows, note that github also have a dedicated <a href="https://help.github.com/articles/set-up-git">Windows client</a>. With a little <a href="http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx">hacking around</a>, it can also be made to work with non-github repositories.</p>
+</div>
+<div class="paragraph">
+<p>If using Mac, you might also want to check out Atlassian’s <a href="http://www.atlassian.com/software/sourcetree/overview">Sourcetree</a>.</p>
+</div>
+<div class="sect4">
+<h5 id="_cloning_the_apache_isis_repo">Cloning the Apache Isis repo</h5>
+<div class="paragraph">
+<p>First, clone the Apache Isis repo.</p>
+</div>
+<div class="paragraph">
+<p>If you are a <strong>committer</strong>, then clone from the Apache read/write repo:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">git clone https://git-wip-us.apache.org/repos/asf/isis.git</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If you are <strong>not a committer</strong>, please see the <a href="#_cg_contributing">contributing</a> page for details on which repo to clone from.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_configuring_git">Configuring Git</h5>
+<div class="paragraph">
+<p>Next up is to configure your user name and password; see also <a href="https://git-wip-us.apache.org/">Apache’s git</a> docs:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">git config user.name "<i>My Name Here</i>"
+git config user.email <i>myusername@apache.org</i></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Next, configure the <code>core.autocrlf</code> so that line endings are normalized to LF (Unix style) in the rep; again see <a href="https://git-wip-us.apache.org/">Apache’s git</a> page:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>on Windows, use:<br></p>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">git config core.autocrlf true</code></pre>
+</div>
+</div>
+</li>
+<li>
+<p>on Mac/Linux, use:<br></p>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">git config core.autocrlf input</code></pre>
+</div>
+</div>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The Windows setting means that files are converted back to CRLF on checkout; the Mac/Linux setting means that the file is left as LF on checkout.</p>
+</div>
+<div class="paragraph">
+<p>We also recommend setting <code>core.safecrlf</code>, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">git config core.safecrlf true</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Note that these settings are supplemented in the repo by the <code>.gitattributes</code> file and that explicitly specifies line handling treatment for most of the common file types that we have.</p>
+</div>
+<div class="paragraph">
+<p>Next, we recommend you setup this a refspec so that you can distinguish remote tags from local ones. To do that, locate the <code>[remote "origin"]</code> section in your <code>.git/config</code> and add the third entry shown below:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">[remote "origin"]
+ url = ... whatever ...
+ fetch = ... whatever ...
+ fetch = +refs/tags/*:refs/tags/origin/*</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This will ensure that a <code>git fetch</code> or <code>git pull</code> places any remote tags under <code>origin/xxx. For example, the`isis-1.0.0`tag on the origin will appear under`origin/isis-1.0.0</code>.</p>
+</div>
+<div class="paragraph">
+<p>If you don’t use git outside of Apache, you can add the <code>--global</code> flag so that the above settings apply for all repos managed by git on your PC.</p>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_getting_help">6.1.2. Getting help</h4>
+<div class="paragraph">
+<p>Three commands of git that in particular worth knowing:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>git help <em>command</em></code><br></p>
+<div class="paragraph">
+<p>will open the man page in your web browser</p>
+</div>
+</li>
+<li>
+<p><code>git gui</code><br></p>
+<div class="paragraph">
+<p>will open up a basic GUI client to staging changes and making commits.</p>
+</div>
+</li>
+<li>
+<p><code>gitk --all</code><br></p>
+<div class="paragraph">
+<p>will open the commit history for all branches. In particular, you should be able to see the local <code>master</code>, which branch you are working on (the <code>HEAD</code>), and also the last known position of the <code>master</code> branch from the central repo, called <code>origin/master</code>.</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>You might also want to explore using a freely available equivalent such as <a href="https://www.sourcetreeapp.com/">Atlassian SourceTree</a>.</p>
+</div>
+<div class="paragraph">
+<p>For further reading, see:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="http://www.kernel.org/pub/software/scm/git/docs/git-config.html">git config man page</a></p>
+</li>
+<li>
+<p><a href="http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html">.gitattributes man page</a></p>
+</li>
+<li>
+<p><a href="http://git-scm.com/docs/gitattributes">.gitattributes git-scm.com docs</a></p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_installing_maven">6.2. Installing Maven</h3>
+<div class="paragraph">
+<p>Install Maven 3.0.x, downloadable <a href="http://maven.apache.org/download.html">here</a>.</p>
+</div>
+<div class="paragraph">
+<p>Set <code>MAVEN_OPTS</code> environment variable:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="ini">MAVEN_OPTS=-Xms512m -Xmx1024m -XX:MaxPermSize=256m</code></pre>
+</div>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Previously we suggested <code>128m</code> for the <code>MaxPermSize</code>, but that would no longer seem to be sufficient.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_building_all_of_apache_isis">6.3. Building all of Apache Isis</h3>
+<div class="paragraph">
+<p>To build the source code from the command line, simply go to the root directory and type:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">mvn clean install</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The first time you do this, you’ll find it takes a while since Maven needs to download all of the Apache Isis prerequisites.</p>
+</div>
+<div class="paragraph">
+<p>Thereafter you can speed up the build by adding the <code>-o</code> (offline flag):</p>
+</div>
+<div class="paragraph">
+<p>For the most part, though, you may want to rely on an IDE such as Eclipse to build the codebase for you. Both Eclipse and Idea (12.0+) support incremental background compilation.</p>
+</div>
+<div class="paragraph">
+<p>When using Eclipse, a Maven profile is configured such that Eclipse compiles to <code>target-ide</code> directory rather than the usual <code>target</code> directory. You can therefore switch between Eclipse and Maven command line without one interfering with the other.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cg_contributing">7. Contributing</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>This page explains how you can contribute to Apache Isis. You’ll probably also want <a href="#_cg_ide">set up your IDE</a> and learn <a href="#_cg_building-isis">how to build Apache Isis</a>.</p>
+</div>
+<div class="paragraph">
+<p>Thanks for considering to help out, your contributions are appreciated!</p>
+</div>
+<div class="sect2">
+<h3 id="_recommended_workflow_github">7.1. Recommended Workflow (github)</h3>
+<div class="paragraph">
+<p>Apache Isis' source code is hosted in an Apache git repo (<a href="https://git-wip-us.apache.org/repos/asf/isis.git">https</a>, <a href="http://git-wip-us.apache.org/repos/asf/isis.git">http</a>), with a clone on github (<a href="https://github.com/apache/isis.git">https</a>, or ssh: <code>git@github.com:apache/isis.git</code>.</p>
+</div>
+<div class="paragraph">
+<p>As you might imagine, only committers are permitted to push changes to the central git repo. As a contributor, we recommend that you fork the <a href="https://github.com/apache/isis.git">apache/isis</a> repo in github, and then use your fork as a way of publishing your patches for the Apache Isis committers to apply.</p>
+</div>
+<div class="paragraph">
+<p>The diagram below illustrates the process:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/contributing/git-workflow.png"><img src="images/contributing/git-workflow.png" alt="git workflow" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>That is:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>as a one-time activity, you fork the <a href="https://github.com/apache/isis.git">github.com/apache/isis</a> repo into your own fork on github.com</p>
+</li>
+<li>
+<p>as a one-time activity, you clone your fork to your local computer</p>
+</li>
+<li>
+<p>you set the <a href="https://github.com/apache/isis.git">github.com/apache/isis</a> as your upstream branch; this will allow you to keep your local clone up-to-date with new commits</p>
+<div class="ulist">
+<ul>
+<li>
+<p>note the asymmetry here: the <code>upstream</code> repo (the Apache github repo) is <strong>not</strong> the same as the <code>origin</code> repo (your fork).</p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>you work on your changes locally; when done, you push them to your github fork</p>
+</li>
+<li>
+<p>to contribute back a change, raise a <a href="https://issues.apache.org/jira/browse/ISIS">JIRA</a> ticket, and ensure your commit message is in the form: <code>ISIS-nnnn: …​</code> so that changes can be tracked (more discussion on this point below). In any case, before you decide to start hacking with Apache Isis, it’s always worth creating a ticket in JIRA and then have a discussion about it on the <a href="http://isis.apache.org/support.html">mailing lists</a>.</p>
+</li>
+<li>
+<p>Use github to raise a <a href="https://help.github.com/articles/using-pull-requests/">pull request</a> for your feature</p>
+</li>
+<li>
+<p>An Apache Isis committer will review your change, and apply it if suitable.</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_alternative_workflow_jira_patches">7.2. Alternative Workflow (JIRA patches)</h3>
+<div class="paragraph">
+<p>As an alternative, you may decide to clone directly from <a href="https://github.com/apache/isis.git">github.com/apache/isis</a> rather than create your own fork:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/contributing/git-workflow-2.png"><img src="images/contributing/git-workflow-2.png" alt="git workflow 2" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>In this case your <code>upstream</code> repo is the same as your <code>origin</code> repo, which might seem more straightforward. On the other hand, if you go this route then you’ll need create patches locally and attach them to the JIRA ticket.</p>
+</div>
+<div class="paragraph">
+<p>For the Apache Isis committers it really doesn’t matter which route you take, so go with whatever’s most comfortable.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_setting_up_your_fork_clone">7.3. Setting up your fork/clone</h3>
+<div class="paragraph">
+<p>If you choose to create your own fork then you’ll need an account on <a href="https://github.com">github.com</a>. You then fork simply by pressing the "Fork" button:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/contributing/github-forking.png"><img src="images/contributing/github-forking.png" alt="github forking" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>An account isn’t needed if you just clone straight from the <a href="http://github.com/apache/isis">github.com/apache/isis</a>.</p>
+</div>
+<div class="paragraph">
+<p>Whether you’ve forked or not, you then need to clone the repo onto your computer. Github makes this very easy to do:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>for Windows users, we suggest you use github’s 'Clone in Windows' feature</p>
+</li>
+<li>
+<p>for Mac/Linux users, create a clone from the command line:</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Again, the info is easily found in the github page:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/contributing/github-cloning.png"><img src="images/contributing/github-cloning.png" alt="github cloning" width="600px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>If you’ve created your own fork, then you need to add the <code>upstream</code> remote to the <a href="https://github.com/apache/isis">github.com/apache/isis</a>. This remote is traditionally called <code>upstream</code>. You should then arrange for your <code>master</code> branch to track the <code>upstream/master</code> remote branch:</p>
+</div>
+<div class="paragraph">
+<p>If you didn’t create your own fork, you can omit the above step. Either way around, you can now fetch new commits using simply:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">git fetch</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>For more info on tracking branches <a href="http://git-scm.com/book/en/Git-Branching-Remote-Branches">here</a> and <a href="http://gitready.com/beginner/2009/03/09/remote-tracking-branches.html">here</a>.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_commit_messages">7.4. Commit messages</h3>
+<div class="paragraph">
+<p>Although with git your commits are always performed on your local repo, those commit messages become public when the patch is applied by an Apache Isis committer. You should take time to write a meaningful commit message that helps explain what the patch refers to; if you don’t then there’s a chance that your patch may be rejected and not applied. No-one likes hard work to go to waste!</p>
+</div>
+<div class="paragraph">
+<p>We therefore recommend that your commit messages are as follows [1]:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="other">ISIS-999: Make the example in CONTRIBUTING imperative and concrete
+
+Without this patch applied the example commit message in the CONTRIBUTING
+document is not a concrete example. This is a problem because the
+contributor is left to imagine what the commit message should look like
+based on a description rather than an example. This patch fixes the
+problem by making the example concrete and imperative.
+
+The first line is a real life imperative statement with a ticket number
+from our issue tracker. The body describes the behavior without the patch,
+why this is a problem, and how the patch fixes the problem when applied.</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Once your git repo is setup, the next thing you’ll most likely want to do is to setup your development environment. See <a href="development-environment.html">here</a> for more details.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_creating_the_patch_file">7.5. Creating the patch file</h3>
+<div class="paragraph">
+<p>If you are working without a github fork of Apache Isis, then you can create the patches from your own local git repository.</p>
+</div>
+<div class="paragraph">
+<p>As per <a href="http://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit">this stackoverflow question</a>, create the patch using <code>git format-patch</code>:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">git format-patch -10 HEAD --stdout > 0001-last-10-commits.patch</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Here <code>-10</code> is the last 10 commits you have done. You need to change that integer according to the commits you need to apply into the patch.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_sample_contribution_workflow">7.6. Sample Contribution Workflow</h3>
+<div class="paragraph">
+<p>Assuming you’re development environment is all setup, let’s walk through how you might make contribute a patch. In this example, suppose that you’ve decided to work on JIRA ticket #123, an enhancement to support Blob/Clob datatypes.</p>
+</div>
+<div class="sect3">
+<h4 id="_update_your_master_branch">7.6.1. Update your master branch</h4>
+<div class="paragraph">
+<p>The first thing to do is to make sure your local clone is up-to-date. We do this by retrieving new commits from upstream repo and then merging them as a fast-forward into your local branch.</p>
+</div>
+<div class="paragraph">
+<p>Irrespective of whether you are using a github fork, the upstream for your local <code>master</code> branch will be tracking the appropriate remote’s <code>master</code> branch. So n either case, the same commands work:</p>
+</div>
+<div class="paragraph">
+<p>Alternatively, you can combine the <code>git fetch</code> and <code>git merge</code> and just use <code>git pull</code>:
+<pre>
+git checkout master
+git pull –ff-only
+</pre></p>
+</div>
+<div class="paragraph">
+<p>If the <code>merge</code> or <code>pull</code> fails, it means that you must have made commits and there have been changes meanwhile on the remote <code>master’s branch. You can use `gitk --all</code> to confirm. If this fails, see our <a href="git-cookbook.html">git cookbook</a> page for a procedure to retrospectively sort out this situation.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_create_a_topic_branch">7.6.2. Create a topic branch</h4>
+<div class="paragraph">
+<p>We recommend you name topic branches by the JIRA ticket, ie <tt>ISIS-nnn-description</tt>. So let’s create a new branch based off <code>master</code> and call it "ISIS-123-blobs"</p>
+</div>
+<div class="paragraph">
+<p>You can confirm the branch is there and is your new <code>HEAD</code> using either <code>gitk --all</code>. Alternatively, use the command line:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">$ git checkout -b ISIS-123-blobs</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The command line prompt should also indicate you are on a branch, isolated from any changes that might happen on the <code>master</code> branch.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_make_file_changes_and_commit">7.6.3. Make File Changes and Commit</h4>
+<div class="paragraph">
+<p>Next, make changes to your files using the usual commands (see also our <a href="#_cg_git-cookbook">git cookbook</a> section):</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>git add</code></p>
+</li>
+<li>
+<p><code>git mv</code></p>
+</li>
+<li>
+<p><code>git rm</code></p>
+</li>
+<li>
+<p><code>git commit</code></p>
+</li>
+<li>
+<p><code>git status</code></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>and so on.</p>
+</div>
+<div class="paragraph">
+<p>Continue this way until happy with the change. Remember to run all your tests on the topic branch (including a full <code>mvn clean install</code>).</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_rebasing_with_code_master_code">7.6.4. Rebasing with <code>master</code></h4>
+<div class="paragraph">
+<p>Before you can share your change, you should rebase (in other words replay) your changes on top of the <code>master</code> branch.</p>
+</div>
+<div class="paragraph">
+<p>The first thing to do is to pull down any changes made in upstream remote’s <code>master</code> since you started your topic branch:</p>
+</div>
+<div class="paragraph">
+<p>These are the same commands that you would have run before you created your topic branch. If you use <code>gitk --all</code>, there’s a good chance that new commits have come in.</p>
+</div>
+<div class="paragraph">
+<p>Next, we reintegrate our topic branch by rebasing onto <code>master</code>:
+<pre>
+git checkout ISIS-123-blobs
+git rebase master
+</pre></p>
+</div>
+<div class="paragraph">
+<p>This takes all of the commits in your branch, and applies them on top of the new <code>master</code> branch. When your change is eventually integrated back in, it will result in a nice clear linear history on the public repo.</p>
+</div>
+<div class="paragraph">
+<p>If the rebase fails because of a conflict, then you’ll be dumped into REBASE mode. Edit the file that has the conflict, and make the appropriate edits. Once done:</p>
+</div>
+<div class="paragraph">
+<p>Once the rebase has completed, re-run your tests to confirm that everything is still good.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_raising_a_pull_request">7.6.5. Raising a pull request</h4>
+<div class="paragraph">
+<p>If you have your own fork, you can now simply push the changes you’ve made locally to your fork:</p>
+</div>
+<div class="paragraph">
+<p>This will create a corresponding branch in the remote github repo. If you use <code>gitk --all</code>, you’ll also see a <code>remotes/origin/ISIS-123-blobs</code> branch.</p>
+</div>
+<div class="paragraph">
+<p>Then, use github to raise a <a href="https://help.github.com/articles/using-pull-requests/">pull request</a>. Pull requests sent to the Apache GitHub repositories will forward a pull request e-mail to the <a href="../support.html">dev mailing list</a>. You’ll probably want to sign up to the dev mailing list first before issuing your first pull request (though that isn’t mandatory).</p>
+</div>
+<div class="paragraph">
+<p>The process to raise the pull request, broadly speaking:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Open a web browser to your github fork of isis</p>
+</li>
+<li>
+<p>Select your topic branch (pushed in the previous step) so that the pull request references the topic branch.</p>
+</li>
+<li>
+<p>Click the <code>Pull Request</code> button.</p>
+</li>
+<li>
+<p>Check that the Apache Isis mailing list email came through.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_if_your_pull_request_is_accepted">7.7. If your pull request is accepted</h3>
+<div class="paragraph">
+<p>To double check that your pull request is accepted, update your <code>master</code> branch from the <code>upstream</code> remote:</p>
+</div>
+<div class="paragraph">
+<p>You can then use <code>gitk --all</code> (or <code>git log</code> if you prefer the command line) to check your contribution has been added.</p>
+</div>
+<div class="paragraph">
+<p>You can now delete your topic branch and remove the branch in your github:</p>
+</div>
+<div class="paragraph">
+<p>Finally, you might want to push the latest changes in master back up to your github fork. If so, use:</p>
+</div>
+<div class="sect3">
+<h4 id="_if_your_pull_request_is_rejected">7.7.1. If your pull request is rejected</h4>
+<div class="paragraph">
+<p>If your pull request is rejected, then you’ll need to update your branch from the main repository and then address the rejection reason.</p>
+</div>
+<div class="paragraph">
+<p>You’ll probably also want to remove the remote branch on github:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="bash">git push origin –delete ISIS-123-blobs</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>… and continue as before until you are ready to resubmit your change.</p>
+</div>
+<div class="paragraph">
+<p>[1] inspiration for the recommended commit format comes from the <a href="https://github.com/puppetlabs/puppet">puppet</a> project’s <a href="https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md">contributing</a> page.</p>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cg_policies">8. Policies</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>This chapter pulls together various policy documents relating to the development of Apache Isis'.</p>
+</div>
+<div class="sect2">
+<h3 id="_cg_committers_versioning-policy">8.1. Versioning Policy</h3>
+<div class="sect3">
+<h4 id="_semantic_versioning">8.1.1. Semantic Versioning</h4>
+<div class="paragraph">
+<p>Starting from v1.0.0, Apache Isis has adopted <a href="http://semver.org">semantic versioning</a> for its versioning policy.</p>
+</div>
+<div class="paragraph">
+<p>Version numbers are in the form <code>x.y.z</code>:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>x is bumped up whenever there a breaking API change</p>
+</li>
+<li>
+<p>y is bumped up whenever there is a new feature that does not break API</p>
+</li>
+<li>
+<p>z is bumped up for minor bug fixes.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>This scheme would be adopted for both core and components.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_version_ranges">8.1.2. Version ranges</h4>
+<div class="paragraph">
+<p>Version ranges may not be used. If necessary, end-users can use <code><dependencyManagement</code> elements to have combine components built against different versions of core.</p>
+</div>
+<div class="paragraph">
+<p>That said, this can introduce instability and so generally we recommend that end-users configure the <code>maven-enforcer-plugin</code> and its <a href="http://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html">DependencyConvergence</a> rule. This will help avoid "jar hell" (components having conflicting dependencies of core).</p>
+</div>
+<div class="paragraph">
+<p>If there is a conflict, we would ask that end-users engage with Apache Isis committers to have an updated version of the component(s) pushed out.</p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_cg_policies_git-policy">8.2. Git Policy</h3>
+<div class="paragraph">
+<p>These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>git commits form an acyclic graph, with each commit pointing to its parent commit (or commit<strong>s</strong>, if a merge)</p>
+</li>
+<li>
+<p>a branch is merely a pointer to one of these commits; git calls the main branch <code>master</code></p>
+</li>
+<li>
+<p>git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>For more background reading, see:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="http://git-scm.com/book">Pro Git</a> book (free in electronic form)</p>
+</li>
+<li>
+<p><a href="https://github.s3.amazonaws.com/media/book.pdf">Git community book</a></p>
+</li>
+<li>
+<p><a href="http://git-scm.com/2011/07/11/reset.html">git reset demystified</a> - differentiating the working directory vs index/staging area</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>And, of course, there is lo
<TRUNCATED>