[01/10] isis git commit: ISIS-1171: if missing, default datanucleus.schema.autoCreateAll to false, not true (to avoid accidental modification of a target database).

[da...@apache.org]

Repository: isis
Updated Branches:
  refs/heads/master 4111aac65 -> 8ad6101af


ISIS-1171: if missing, default datanucleus.schema.autoCreateAll to false, not true (to avoid accidental modification of a target database).


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/f1f9b239
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/f1f9b239
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/f1f9b239

Branch: refs/heads/master
Commit: f1f9b239a1cd44ade5eb3164d23923064e76cd0f
Parents: 4111aac
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jul 9 18:36:00 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jul 9 18:36:00 2015 +0100

----------------------------------------------------------------------
 ...ation-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc | 16 ++++++++++++----
 .../DataNucleusApplicationComponents.java           |  6 ++----
 .../DataNucleusPersistenceMechanismInstaller.java   | 13 ++++++++-----
 3 files changed, 22 insertions(+), 13 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/f1f9b239/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
index 4235cea..e6f01d0 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
@@ -202,7 +202,15 @@ isis.persistor.datanucleus.impl.datanucleus.schema.validateTables=true
 isis.persistor.datanucleus.impl.datanucleus.schema.validateConstraints=true
 ----
 
-and change:
+[NOTE]
+====
+Previously Apache Isis would automatically add the auto-create property if they were absent from `isis.properties`, set to "true".  The framework does still add the property, but now sets it to "false".  This is to prevent the framework from unexpectedly modifying a target database if the application was misconfigured and the auto-create property not defined.
+
+The framework will also automatically add the auto-validate property.  Previously this was set to "true" and it is _still_ set to "true"; there is no risk of the target database being modified as a result of this auto-validate property being defaulted by the framework.
+====
+
+
+In addition, change:
 
 [source,ini]
 ----
@@ -217,15 +225,15 @@ isis.persistor.datanucleus.impl.datanucleus.identifier.case=MixedCase
 ----
 
 
-[WARNING]
-====
+
+== Run `mvn clean` !
+
 Be careful to ensure that your classes are only enhanced by the DataNucleus 4 enhancer, and _not_ by the DataNucleus 3 enhancer.  Or even, be careful that they are not doubly enhanced.  One of our committers had this situation and it led to all sorts of bizarre issues.  The solution, it turned out, was actually just to do a full `mvn clean`.
 
 If you are struggling and suspect you may have misconfigured the enhancer plugin, then you can decompile the bytecode (eg in IntelliJ) and take a look:
 
 * A class enhanced with DataNucleus 3 would implement `javax.jdo.spi.PersistenceCapable` interface
 * A class enhanced with DataNucleus 4 will implement `org.datanucleus.enhancer.Persistable`.
-====
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/f1f9b239/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusApplicationComponents.java
----------------------------------------------------------------------
diff --git a/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusApplicationComponents.java b/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusApplicationComponents.java
index 63821dc..50b2c2e 100644
--- a/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusApplicationComponents.java
+++ b/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusApplicationComponents.java
@@ -154,11 +154,9 @@ public class DataNucleusApplicationComponents implements ApplicationScopedCompon
 
             final MetaDataManager metaDataManager = nucleusContext.getMetaDataManager();
 
-            // rather than reinvent too much of the wheel, we reuse the same properties that DN would check
+            // rather than reinvent too much of the wheel, we reuse the same property that DN would check
             // for if it were doing the auto-creation itself (read from isis.properties)
-            final boolean createSchema =
-                    isSet(this.datanucleusProps, PropertyNames.PROPERTY_SCHEMA_AUTOCREATE_SCHEMA) ||
-                            isSet(this.datanucleusProps, PropertyNames.PROPERTY_SCHEMA_AUTOCREATE_ALL);
+            final boolean createSchema = isSet(this.datanucleusProps, PropertyNames.PROPERTY_SCHEMA_AUTOCREATE_ALL);
             if (!createSchema) {
                 return;
             }

http://git-wip-us.apache.org/repos/asf/isis/blob/f1f9b239/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusPersistenceMechanismInstaller.java
----------------------------------------------------------------------
diff --git a/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusPersistenceMechanismInstaller.java b/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusPersistenceMechanismInstaller.java
index 7736bf4..357f2cb 100644
--- a/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusPersistenceMechanismInstaller.java
+++ b/core/runtime/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/DataNucleusPersistenceMechanismInstaller.java
@@ -26,6 +26,7 @@ import java.util.Set;
 import com.google.common.collect.Sets;
 
 import org.datanucleus.PropertyNames;
+import org.datanucleus.api.jdo.JDOPersistenceManagerFactory;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -140,15 +141,17 @@ public class DataNucleusPersistenceMechanismInstaller extends PersistenceMechani
             final Map<String, String> props) {
         
         // new feature in DN 3.2.3; enables dependency injection into entities
-        putIfNotPresent(props, PropertyNames.PROPERTY_OBJECT_PROVIDER_CLASS_NAME, "org.apache.isis.objectstore.jdo.datanucleus.JDOStateManagerForIsis");
+        putIfNotPresent(props, PropertyNames.PROPERTY_OBJECT_PROVIDER_CLASS_NAME, JDOStateManagerForIsis.class.getName());
         
-        putIfNotPresent(props, "javax.jdo.PersistenceManagerFactoryClass", "org.datanucleus.api.jdo.JDOPersistenceManagerFactory");
+        putIfNotPresent(props, "javax.jdo.PersistenceManagerFactoryClass", JDOPersistenceManagerFactory.class.getName());
 
-        putIfNotPresent(props, PropertyNames.PROPERTY_SCHEMA_AUTOCREATE_SCHEMA, "true");
-        putIfNotPresent(props, PropertyNames.PROPERTY_SCHEMA_VALIDATE_ALL, "true");
+        // previously we defaulted this property to "true", but that could cause the target database to be modified
+        putIfNotPresent(props, PropertyNames.PROPERTY_SCHEMA_AUTOCREATE_SCHEMA, Boolean.FALSE.toString());
+
+        putIfNotPresent(props, PropertyNames.PROPERTY_SCHEMA_VALIDATE_ALL, Boolean.TRUE.toString());
         putIfNotPresent(props, PropertyNames.PROPERTY_CACHE_L2_TYPE, "none");
 
-        putIfNotPresent(props, PropertyNames.PROPERTY_PERSISTENCE_UNIT_LOAD_CLASSES, "true");
+        putIfNotPresent(props, PropertyNames.PROPERTY_PERSISTENCE_UNIT_LOAD_CLASSES, Boolean.TRUE.toString());
 
         String connectionFactoryName = props.get(PropertyNames.PROPERTY_CONNECTION_FACTORY_NAME);
         if(connectionFactoryName != null) {

[09/10] isis git commit: ISIS-1133: pulling together the contributors guide.

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_cutting-a-release.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_cutting-a-release.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_cutting-a-release.adoc
new file mode 100644
index 0000000..2569b4d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_cutting-a-release.adoc
@@ -0,0 +1,1046 @@
+[[_cg_committers_cutting-a-release]]
+= Cutting a Release
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+This page details the process for formally releasing Isis modules.
+
+If you've done this before and just want the bare essentials, see this xref:cg.adoc#_cg_committers_cutting-a-release-one-pager[one-pager]
+(that also parameterizes some of the steps listed here 'long-hand'. There is also an experimental
+link:http://isis.apache.org/resources/release.sh[script] for automating the latter part of the process.
+
+See also the xref:cg.adoc#_cg_committers_release-checklist[release checklist] for keeping track of where you are while releasing Apache Isis component(s).
+
+
+
+== Intro
+
+Apache Isis consists of two separately releasable modules. Relative to the root of the
+https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=tree[source code repo], these are:
+
+* `core`
+* `component/example/archetypes/simpleapp`
+
+Previously there were many other components, but these have either been mothballed or moved into core. The only
+remaining component that is not in core (though has not yet been released) is `component/viewer/scimpi`. There is
+currently no plan to release this component.
+
+
+
+== Process Prerequisites
+
+Before releasing `core`, ensure there is consensus on the link:../support.html[dev mailing list] that this is the right
+time for a release. The discussion should include confirming the version number to be used, and to confirm content.
+
+Once agreed, the formal release can begin. The steps are:
+
+* create a branch locally in which to prepare the release
+* use `mvn release:prepare` to generate the signed artifacts and create a tag in the source code control system
+* use `mvn release:perform` to upload the signed artifacts to the Apache staging repository
+* vote on the staged artifacts (in particular, the signed source release ZIP from which the remaining artifacts are derivable)
+* on a successful vote:
+* promote the staged artifacts
+* distribute the source zip
+* merge in the branch back to into master
+* on a failed vote:
+* drop the staging repository
+* delete the branch and tag
+* fix the problems and go round round the loop again.
+
+Before any of this can happen, there are a number of prerequisites, in terms of (a) the codebase itself,
+(b) the community process, and (c) the committer acting as release manager and performing the release.
+
+
+
+
+=== Set up local environment
+
+==== Public/private key
+
+The most important configuration you require is to set up public/private key pair. This is used by the `maven-release-plugin` to sign the code artifacts. See the page on xref:cg.adoc#_cg_committers_key-generation[key generation] for more details.
+
+In order to prepare the release, you'll (need to) have a `~/.gnupg` directory with the relevant files (`gpg.conf`, `pubring.gpg`, `secring.gpg` etc), and have `gpg` on your operating system PATH.
+
+
+[NOTE]
+====
+If on Windows, the equivalent directory is `c:\users\xxx\appdata\roaming\gnupg`. For `gpg`, use either http://cygwin.com[cygwin.com] or http://www.gpg4win.org[gpg4win.org]. Note also that the mSysGit version of `gpg` (as provided by GitHub's bash client) is not compatible with that provided by cygwin; move it to one side and check that `gpg.exe` being used is that from gpg4win.
+
+====
+
+
+
+==== Maven `settings.xml`
+
+During the release process the `maven-deploy-plugin` uploads the generated artifacts to a staging repo on the http://repository.apache.org[Apache repository manager]. This requires your Apache LDAP credentials to be specified in your `~/.m2/settings.xml` file:
+
+[source,xml]
+----
+<settings>
+  <servers>
+    <server>
+      <id>apache.releases.https</id>
+      <username>xxxxxxx</username>
+      <password>yyyyyyy</password>
+    </server>
+    ...
+  </servers>
+  ...
+</settings>
+----
+
+where `xxxxxxx` and `yyyyyyy` are your Apache LDAP username and password. For more information, see these http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env[ASF docs].
+
+
+[NOTE]
+====
+It is also possible to configure to use `.ssh` secure keys, and thereby avoid hardcoding your Apache LDAP password into your `.m2/settings.xml` file. A description of how to do this can be found, for example, http://bval.apache.org/release-setup.html[here].
+====
+
+
+Also, set up keyphrase for `gpg`; this avoids being prompted during release:
+
+[source,xml]
+----
+<profiles>
+  <profile>
+    <id>gpg</id>
+    <properties>
+      <gpg.executable>gpg2</gpg.executable>
+      <gpg.passphrase>this is not really my passphrase</gpg.passphrase>
+    </properties>
+  </profile>
+  ...
+</profiles>
+
+<activeProfiles>
+  <activeProfile>gpg</activeProfile>
+  ...
+</activeProfiles>
+----
+
+
+==== Pull down code to release
+
+Set the HEAD of your local git repo to the commit to be released. In many cases this will be the tip of the origin's `master` branch:
+
+[source,bash]
+----
+git checkout master
+git pull --ff-only
+----
+
+Then, determine/confirm the version number of the module being released. This should be in line with our xref:cg.adoc#_cg_committers_versioning-policy[semantic versioning policy].
+
+Next, create a release branch in your local Git repo, using the version number determined and as per link:release-branch-and-tag-names.html[these standards]. For example, to prepare release candidate #1 for a release 1.9.0 of `core`, use:
+
+[source,bash]
+----
+git checkout -b isis-1.9.0
+----
+
+All release preparation is done locally; if we are successful, this branch will be pushed back to master.
+
+Finally, make sure you have a JIRA ticket open against which to perform all commits.
+
+
+
+
+== Set Environment Variables
+
+If you are releasing `core`:
+
+[source,bash]
+----
+cd core
+
+export ISISTMP=/c/tmp              # or whatever
+export ISISART=isis
+export ISISDEV=1.10.0-SNAPSHOT
+export ISISREL=1.9.0
+export ISISRC=RC1
+
+export ISISCOR="Y"
+env | grep ISIS | sort
+----
+
+== Code Prerequisites
+
+{note
+Unless otherwise stated, you should assume that all remaining steps should be performed in the base directory of the module being released.
+}
+
+Before making any formal release, there are a number of prerequisites that should always be checked.
+
+=== Update the version number
+
+The version number of the parent pom should reflect the branch name that you are now on (with a `-SNAPSHOT` suffix). In many cases this will have been done already during earlier development; but confirm that it has been updated. If it has not, make the change.
+
+For example, if releasing `core` version `1.9.0`, the POM should read:
+
+[source,xml]
+----
+<groupId>org.apache.isis.core</groupId>
+<artifactId>isis</artifactId>
+<version>1.9.0</version>
+----
+
+=== Update parent (Apache Isis Core)
+
+If releasing Apache Isis Core, check (via link:http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache%22%20a%3A%22apache%22[search.maven.org]) whether there is a newer version of the Apache parent `org.apache:apache`.
+
+
+If there is, update the `&lt;version&gt;` in the `&lt;parent&gt;` element in the parent POM to match the newer version:
+
+[source,xml]
+----
+<parent>
+    <groupId>org.apache</groupId>
+    <artifactId>apache</artifactId>
+    <version>NN</version>
+    <relativePath />
+</parent>
+----
+
+where `NN` is the updated version number.
+
+=== Check no SNAPSHOT dependencies
+
+There should be no snapshot dependencies; the only mention of `SNAPSHOT` should be for the Isis modules about to be released. 
+
+As a quick check, do a grep for `SNAPSHOT`:
+
+[source,bash]
+----
+grep SNAPSHOT `/bin/find . -name pom.xml | grep -v target | sort`
+----
+
+Or, for a more thorough check, load up each `pom.xml` and inspect manually:
+
+[source,bash]
+----
+vi `/bin/find . -name pom.xml | grep -v target | sort`
+----
+
+... and search for `SNAPSHOT`.
+
+
+[TIP]
+====
+Obviously, don't update Apache Isis' `SNAPSHOT` references; these get updated by the `mvn release:prepare` command we run later.
+====
+
+
+
+=== Update plugin versions
+
+The `maven-versions-plugin` should be used to determine if there are newer versions of any of the plugins used to build Apache Isis. Since this goes off to the internet, it may take a minute or two to run:
+
+[source,bash]
+----
+mvn versions:display-plugin-updates > /tmp/foo
+grep "\->" /tmp/foo | /bin/sort -u
+----
+
+Review the generated output and make updates as you see fit. (However, if updating, please check by searching for known issues with newer versions).
+
+
+
+=== Update dependency versions
+
+The `maven-versions-plugin` should be used to determine if there are newer versions of any of Isis' dependencies. Since this goes off to the internet, it may take a minute or two to run:
+
+[source,bash]
+----
+mvn versions:display-dependency-updates > /tmp/foo
+grep "\->" /tmp/foo | /bin/sort -u
+----
+
+Update any of the dependencies that are out-of-date. That said, do note that some dependencies may show up with a new dependency, when in fact the dependency is for an old, badly named version. Also, there may be new dependencies that you do not wish to move to, eg release candidates or milestones.
+
+For example, here is a report showing both of these cases:
+
+[source,bash]
+----
+[INFO]   asm:asm ..................................... 3.3.1 -> 20041228.180559
+[INFO]   commons-httpclient:commons-httpclient .......... 3.1 -> 3.1-jbossorg-1
+[INFO]   commons-logging:commons-logging ......... 1.1.1 -> 99.0-does-not-exist
+[INFO]   dom4j:dom4j ................................. 1.6.1 -> 20040902.021138
+[INFO]   org.datanucleus:datanucleus-api-jdo ................ 3.1.2 -> 3.2.0-m1
+[INFO]   org.datanucleus:datanucleus-core ................... 3.1.2 -> 3.2.0-m1
+[INFO]   org.datanucleus:datanucleus-jodatime ............... 3.1.1 -> 3.2.0-m1
+[INFO]   org.datanucleus:datanucleus-rdbms .................. 3.1.2 -> 3.2.0-m1
+[INFO]   org.easymock:easymock ................................... 2.5.2 -> 3.1
+[INFO]   org.jboss.resteasy:resteasy-jaxrs ............. 2.3.1.GA -> 3.0-beta-1
+----
+
+For these artifacts you will need to search http://search.maven.org[Maven central repo] directly yourself to confirm there are no newer dependencies not shown in this list.
+
+=== Code cleanup / formatting
+
+Make sure that all source code has been cleaned up and formatted according to the Apache Isis and ASF conventions. Use link:resources/Apache-code-style-formatting.xml[this] Eclipse template and link:resources/isis.importorder[this] import order.
+
+=== License header notices (RAT tool)
+
+The Apache Release Audit Tool `RAT` (from the http://creadur.apache.org[Apache Creadur] project) checks for missing license header files. The parent `pom.xml` of each releasable module specifies the RAT Maven plugin, with a number of custom exclusions.
+
+To run the RAT tool, use:
+
+[source,bash]
+----
+mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o
+----
+
+where `rat.numUnapprovedLicenses` 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. 
+
+
+[WARNING]
+====
+Do _not_ use `mvn rat:check`; depending on your local Maven configuratoin this may bring down the obsolete `mvn-rat-plugin` from the Codehaus repo.
+====
+
+
+All being well the command should complete. For each failing submodule, it will have written out a `target\rat.txt`; missing license notes are indicated using the key `!???`. You can collate these together using something like:
+
+[source,bash]
+----
+for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done
+----
+
+Investigate and fix any reported violations, typically by either:
+
+* adding genuinely missing license headers from Java (or other) source files, or
+* updating the `&lt;excludes&gt;` element for the `apache-rat-plugin` plugin to ignore test files, log files and any other non-source code files
+* also look to remove any stale `&lt;exclude&gt;` entries
+
+To add missing headers, you can if you wish use the groovy script `addmissinglicenses.groovy` (in the `scripts` directory) to automatically insert missing headers for certain file types. The actual files checked are those with extensions specified in the line `def fileEndings = [&quot;.java&quot;, &quot;.htm&quot;]`:
+
+Run this in dry run mode first (shown here relative to the `core` module):
+
+[source,bash]
+----
+groovy ../scripts/addmissinglicenses.groovy
+----
+
+When happy, perform the updates by specifying the `-x` (execute) flag:
+
+[source,bash]
+----
+groovy addmissinglicenses.groovy -x
+----
+
+Once you've fixed all issues, confirm once more that `apache-rat-plugin` no longer reports any license violations, this time leaving the `rat.numUnapprovedLicenses` property to its default, 0:
+
+[source,bash]
+----
+mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=0 -o
+for a in `find . -name rat.txt -print`; do grep '!???' $a; done
+----
+
+=== Missing License Check
+
+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 `DEPENDENCIES` file and generated Maven site indicating dependencies as having "unknown" licenses.
+
+Fortunately, Maven allows the missing information to be provided by configuring the `maven-remote-resources-plugin`. This is stored in the `src/main/appended-resources/supplemental-models.xml` file, relative to the root of each releasable module.
+
+To capture the missing license information, use:
+
+[source,bash]
+----
+mvn license:download-licenses
+----
+
+This Maven plugin creates a `license.xml` file in the `target/generated-resources` directory of each module.
+
+Then, run the following script (shown here relative to the `core` module).
+
+[source,bash]
+----
+groovy ../scripts/checkmissinglicenses.groovy
+----
+
+This searches for all `licenses.xml` files, and compares them against the contents of the `supplemental-models.xml` file. For example, the output could be something like:
+
+[source,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]
+----
+
+If any missing entries are listed or are spurious, then update `supplemental-models.xml` and try again.
+
+
+[NOTE]
+====
+Ignore any missing license warnings for the TCK modules; this is a result of the TCK modules for the viewers (eg `isis-viewer-bdd-concordion-tck`) depending on the TCK dom, fixtures etc.
+====
+
+
+
+== Sanity check
+
+Before you cut the release, perform one last sanity check on the codebase.
+
+=== Sanity check for `core`
+
+First, check that there are _NO SNAPSHOT_ dependencies in any of the `pom.xml` of the modules of the core.
+
+Next, delete all Isis artifacts from your local Maven repo:
+
+[source,bash]
+----
+rm -rf ~/.m2/repository/org/apache/isis
+----
+
+Next, check that `core` builds independently, using the `-o` offline flag:
+
+[source,bash]
+----
+mvn clean install -o
+----
+
+Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
+
+=== Sanity check for non-`core` components
+
+You should already have changed the parent POM of the releasable module to reference a released version of `org.apache.isis.core:isis`. Now, also check that there are remaining _NO SNAPSHOT_ dependencies in any of the `pom.xml` of the modules of the component.
+
+Next, delete all Isis artifacts from your local Maven repo:
+
+[source,bash]
+----
+rm -rf ~/.m2/repository/org/apache/isis
+----
+
+Next, build the component, though without the offline flag. Maven should pull down the component's dependencies from the Maven central repo, including the non-spshot of Apache Isis core:
+
+[source,bash]
+----
+mvn clean install
+----
+
+Confirm that the versions of the Isis artifacts now cached in your local repository are correct (both those pulled down from Maven central repo, as well as those of the component built locally). The versions of `core` should not be a SNAPSHOT.
+
+
+
+== Commit changes
+
+Before going any further, remember to commit any changes from the preceding steps:
+
+[source,bash]
+----
+git commit -am "ISIS-nnn: updates to pom.xml etc for release"
+----
+
+== Preparing a Release (`mvn release:prepare`)
+
+Most of the work is done using the `mvn release:prepare` 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.
+
+=== Dry-run
+
+Run the dry-run as follows:
+
+[source,bash]
+----
+mvn release:prepare -P apache-release -D dryRun=true \
+    -DreleaseVersion=$ISISREL \
+    -Dtag=$ISISART-$ISISREL \
+    -DdevelopmentVersion=$ISISDEV
+----
+
+where:
+
+* `releaseVersion` just strip off the `-SNAPSHOT` suffix:
+* `tag` should follow our link:release-branch-and-tag-names.html[standard] (concatenation of the `artifactId` and the version entered above _without a `-RCn` suffix_)
+* `developmentVersion` should increment as required, and have `-SNAPSHOT` appended.
+
+This is not quite fully automated; you may be prompted for the gpg passphrase. (Experiments in using `--batch-mode -Dgpg.passphrase=&quot;...&quot;` to fully automate this didn't work; for more info, see http://maven.apache.org/plugins/maven-gpg-plugin/sign-mojo.html[here] (maven release plugin docs) and http://maven.apache.org/maven-release/maven-release-plugin/examples/non-interactive-release.html[here] (maven gpg plugin docs).
+
+Or, if you want to be prompted for the versions, you can omit the properties, eg:
+
+[source,bash]
+----
+mvn release:prepare -P apache-release -D dryRun=true
+----
+
+Some modules might have additional profiles to be activated. For example, the (now mothballed) SQL ObjectStore required `-P apache-release,integration-tests` so that its integration tests are also run.
+
+This should generate something like:
+
+[source,bash]
+----
+$ mvn release:prepare -P apache-release -D dryRun=true
+[INFO] Scanning for projects...
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Build Order:
+[INFO]
+[INFO] Apache Isis Core
+[INFO] Apache Isis Core AppLib
+[INFO] Apache Isis Core Unit Test Support
+[INFO] Apache Isis Core MetaModel
+[INFO] Apache Isis Core Runtime
+[INFO] Apache Isis Core WebServer
+       ...
+[INFO] Apache Isis Core Integration Testing Support
+[INFO]
+[INFO] ------------------------------------------------------------------------
+[INFO] Building Apache Isis Core 1.9.0
+[INFO] ------------------------------------------------------------------------
+[INFO]
+[INFO] --- maven-release-plugin:2.3.2:prepare (default-cli) @ isis ---
+[INFO] Resuming release from phase 'map-release-versions'
+What is the release version for "Apache Isis Core"? (org.apache.isis.core:isis)
+1.9.0: :
+----
+
+If you didn't provide the `releaseVersion`, `tag` and `developmentVersion` tags, then you'll be prompted for them. You can generally accept the defaults that Maven offers.
+
+Assuming this completes successfully, re-run the command, but without the `dryRun` flag and specifying `resume=false` (to ignore the generated `release.properties` file that gets generated as a side-effect of using `git`). You can also set the `skipTests` flag since they would have been run during the previous dry run:
+
+[source,bash]
+----
+mvn release:prepare -P apache-release -D resume=false -DskipTests=true
+        -DreleaseVersion=$ISISREL \
+        -Dtag=$ISISART-$ISISREL \
+        -DdevelopmentVersion=$ISISDEV
+----
+
+
+[TIP]
+====
+If any issues here, then explicitly delete the generated `release.properties` file first.
+====
+
+
+
+=== Post-prepare sanity check
+
+You should end up with artifacts in your local repo with the new version `1.9.0`. There are then a couple of sanity checks that you can perform:
+
+* unzip the source-release ZIP and check it builds. +
++
+For example, if building core, then the ZIP file will be called `isis-1.9.0-source-release.zip` and should reside in `~/.m2/repository/org/apache/isis/core/isis/1.9.0` directory. +
++
+Unzip in a new directory, and build.
+
+* Inspect the `DEPENDENCIES` file. +
++
+This file should be in the root of the extracted ZIP. In particular, check that there are no category-x dependencies.
+
+If you find problems and the release was performed on a branch, then just delete the branch and start over.
+
+
+
+
+== Upload Release for Voting
+
+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).
+
+The Apache staging repository runs on Nexus server, hosted at https://repository.apache.org[repository.apache.org]. 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.
+
+Before you start, make sure you've defined the staging repo in your local `~/.m2/settings.xml` file (see earlier on this page).
+
+
+=== Perform the Release
+
+If running on *nix, then the command to stage the release is:
+
+[source,bash]
+----
+mvn release:perform -P apache-release
+----
+
+but if using mSysGit on windows, specify a different working directory:
+
+[source,bash]
+----
+mvn release:perform -P apache-release \
+    -DworkingDirectory=$ISISTMP/$ISISART-$ISISREL/checkout
+----
+
+You may (again) be prompted for gpg passphrase.
+
+The command starts off by checking out the codebase from the tag (hence different working directory under Windows to avoid 260 char path limit). It then builds the artifacts, then uploads them to the Apache staging repository:
+
+[source,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 isis-1.9.0 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 isis-1.9.0 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 isis-1.9.0"
+[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'...
+...
+----
+
+All being well this command will complete successfully. Given that it is uploading code artifacts, it could take a while to complete. 
+
+=== Check the Repository
+
+If the `mvn release:perform` has worked then it will have put release artifacts into a newly created staging repository .
+
+Log onto http://repository.apache.org[repository.apache.org] (using your ASF LDAP account):
+
+image::{_imagesdir}release-process/nexus-staging-0.png[width="600px",link="{_imagesdir}release-process/nexus-staging-0.png"]
+
+And then check that the release has been staged (select `staging repositories` from left-hand side):
+
+image::{_imagesdir}release-process/nexus-staging-1.png[width="600px",link="{_imagesdir}release-process/nexus-staging-1.png"]
+
+If nothing appears in a staging repo you should stop here and work out why.
+
+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 `org.apache.isis-008`.
+
+=== Close the Repository
+
+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.
+
+Press the Close button and complete the dialog:
+
+image::{_imagesdir}release-process/nexus-staging-2.png[width="600px",link="{_imagesdir}release-process/nexus-staging-2.png"]
+
+Nexus should start the process of closing the repository.
+
+image::{_imagesdir}release-process/nexus-staging-2a.png[width="600px",link="{_imagesdir}release-process/nexus-staging-2a.png"]
+
+All being well, the close should (eventually) complete successfully (keep hitting refresh):
+
+image::{_imagesdir}release-process/nexus-staging-3.png[width="600px",link="{_imagesdir}release-process/nexus-staging-3.png"]
+
+The Nexus repository manager will also email you with confirmation of a successful close.
+
+If Nexus has problems with the key signature, however, then the close will be aborted:
+
+image::{_imagesdir}release-process/nexus-staging-4.png[width="600px",link="{_imagesdir}release-process/nexus-staging-4.png"]
+
+Use `gpg --keyserver hkp://pgp.mit.edu --recv-keys nnnnnnnn` to confirm that the key is available.
+
+
+[NOTE]
+====
+Unfortunately, Nexus does not seem to allow subkeys to be used for signing. See xref:cg.adoc#_cg_committers_key-generation[Key Generation] for more details.
+====
+
+
+=== Push changes
+
+Finally, push both the branch and the tag created locally to the central origin server. For the tag, we append an `-RCn` suffix until the vote succeeds. 
+
+To push the branch, for example:
+
+[source,bash]
+----
+git checkout prepare/$ISISART-$ISISREL
+git push -u origin prepare/$ISISART-$ISISREL
+----
+
+To push the tag, with the `-RCn` suffix, for example:
+
+[source,bash]
+----
+git push origin refs/tags/$ISISART-$ISISREL:refs/tags/$ISISART-$ISISREL-$ISISRC
+git fetch
+----
+
+The remote tag isn't visible locally (eg via `gitk --all`), but can be seen https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=summary[online].
+
+
+
+== Voting
+
+Once the artifacts have been uploaded, you can call a vote.
+
+In all cases, votes last for 72 hours and require a +3 (binding) vote from members.
+
+=== Start voting thread on link:mailto:&#100;e&#118;&#x40;&#x69;&#x73;&#x69;&#115;&#x2e;&#x61;p&#97;&#x63;&#104;e&#46;&#111;&#114;g[&#100;e&#118;&#x40;&#x69;&#x73;&#x69;&#115;&#x2e;&#x61;p&#97;&#x63;&#104;e&#46;&#111;&#114;g]
+
+The following boilerplate is for a release of the Apache Isis Core. Adapt as required:
+
+Use the following subject:
+
+[source,bash]
+----
+[VOTE] Apache Isis Core release 1.8.0 RC1
+----
+
+And use the following body:
+
+[source,bash]
+----
+I've cut a release for Apache Isis Core and the simpleapp archetype:
+* Core 1.8.0
+* SimpleApp Archetype 1.8.0
+
+The source code artifacts have been uploaded to staging repositories on repository.apache.org:
+
+* http://repository.apache.org/content/repositories/orgapacheisis-10xx/org/apache/isis/core/isis/1.9.0/isis-1.9.0-source-release.zip
+* http://repository.apache.org/content/repositories/orgapacheisis-10xx/org/apache/isis/archetype/simpleapp-archetype/1.9.0/simpleapp-archetype-1.9.0-source-release.zip
+
+For each zip there is a corresponding signature file (append .asc to the zip's url).
+
+In the source code repo the code has been tagged as isis-1.8.0-RC1 and simpleapp-archetype-1.8.0-RC1.
+
+For instructions on how to verify the release (build from binaries and/or use in Maven directly), see xref:cg.adoc#_cg_committers_verifying-releases[here]
+
+Please verify the release and cast your vote.  The vote will be open for a minimum of 72 hours.
+
+[ ] +1
+[ ]  0
+[ ] -1
+----
+
+Remember to update:
+
+* the version number (1.9.0 or whatever)
+* the release candidate number (`RC1` or whatever)
+* the repository id, as provided by Nexus earlier (`orgapacheisis-10xx` or whatever)
+
+Note that the email also references the procedure for other committers to xref:cg.adoc#_cg_committers_verifying-releases[verify the release].
+
+== After the vote
+
+Once the vote has completed, post the results to the isis-dev mailing list.
+
+For example, use the following subject for a vote on Apache Isis Core:
+
+[source,bash]
+----
+[RESULT] [VOTE] Apache Isis Core release 1.9.0
+----
+
+using the body (alter last line as appropriate):
+
+[source,bash]
+----
+The vote has completed with the following result :
+
+  +1 (binding): <i>list of names</i>
+  +1 (non binding): <i>list of names</i>
+
+  -1 (binding): <i>list of names</i>
+  -1 (non binding): <i>list of names</i>
+
+The vote is (UN)SUCCESSFUL.
+----
+
+=== For a successful vote
+
+If the vote has been successful, then replace the `-RCn` tag with another without the qualifier.
+
+You can do this using the `scripts/promoterctag.sh` script; for example:
+
+[source,bash]
+----
+sh scripts/promoterctag isis-1.9.0 RC1    # $ISISART-$SISREL $ISISRC
+----
+
+Or, if you like to execute the steps in that script by hand:
+
+* add the new remote tag, for example: +
++
+[source,bash]
+----
+git push origin refs/tags/isis-1.9.0:refs/tags/isis-1.9.0
+git fetch
+----
+
+* delete the `-RCn` remote tag, for example: +
++
+[source,bash]
+----
+git push origin –delete refs/tags/isis-1.9.0-RC1 # $ISISART-$SISREL-$ISISRC
+git fetch
+----
+
+
+* delete the `-RCn` local tag, for example: +
++
+[source,bash]
+----
+git tag -d isis-1.9.0-RC1 # $ISISART-$SISREL-$ISISRC
+git fetch
+----
+
+
+
+Then, continue onto the next section for the steps to promote and announce the release.
+
+=== For an unsuccessful vote
+
+If the vote has been unsuccessful, then:
+
+* delete the remote branch, for example: +
++
+[source,bash]
+----
+git push origin –delete isis-1.9.0 # $ISISART-$SISREL
+----
+
+
+
+* delete your local branch, for example: +
++
+[source,bash]
+----
+git branch -D isis-1.9.0 # $ISISART-$SISREL
+----
+
+
+* delete the remote origin server's tag, for example: +
++
+[source,bash]
+----
+git push origin –delete refs/tags/isis-1.9.0-RC1
+----
+
+
+* delete the tag that was created locally, for example: +
++
+[source,bash]
+----
+git tag -d isis-1.9.0 # $ISISART-$SISREL
+----
+
+
+* drop the staging repository in http://repository.apache.org[Nexus]
+
+Address the problems identified in the vote, and go again.
+
+
+
+
+== Promoting Release to Distribution
+
+=== Release Binaries to Maven Central Repo
+
+From the Nexus pages, select the staging repository and select 'release' from the top menu.
+
+
+image::{_imagesdir}release-process/nexus-release-1.png[width="600px",link="{_imagesdir}release-process/nexus-release-1.png"]
+
+This moves the release artifacts into an Apache releases repository; from there they will be automatically moved to the Maven repository.
+
+=== Release Source Zip
+
+As described in the http://www.apache.org/dev/release-publishing.html#distribution_dist[Apache documentation], each Apache TLP has a `release/TLP-name` directory in the distribution Subversion repository at https://dist.apache.org/repos/dist[https://dist.apache.org/repos/dist]. Once a release vote passes, the release manager should `svn add` the artifacts (plus signature and hash files) into this location. The release is then automatically pushed to http://www.apache.org/dist/[http://www.apache.org/dist/] by `svnpubsub`. Only the most recent release of each supported release line should be contained here, old versions should be deleted.
+
+Each project is responsible for the structure of its directory. The directory structure of Apache Isis reflects the directory structure in our git source code repo:
+
+[source]
+----
+isis/
+  core/
+  component/
+    objectstore/  # empty, JDO now part of core
+    security/     # empty, Shiro now part of core
+    viewer/       # empty, Restful and Wicket viewers now part of core
+  example/
+    archetype/
+      simpleapp/
+  tool/
+    maven-isis-plugin/   # not yet released
+----
+
+If necessary, checkout this directory structure:
+
+[source,bash]
+----
+svn co https://dist.apache.org/repos/dist/release/isis isis-dist
+----
+
+Next, add the new release into the appropriate directory, and delete any previous release. You can use link:upd_sh[the upd.sh script] to help; this downloads the artefacts from the Nexus release repository, adds the artefacts to subsversion and deletes the previous version.
+
+At the end, commit the changes:
+
+[source]
+----
+svn commit -m "publishing isis source releases to dist.apache.org"
+----
+
+== Update JIRA and generate Release notes
+
+=== Close All JIRA tickets for the release
+
+Close all JIRA tickets for the release, or moved to future releases if not yet addressed. Any tickets that were partially implemented should be closed, and new tickets created for the functionality on the ticket not yet implemented.
+
+=== Generate Release Notes in JIRA
+
+Use JIRA to http://confluence.atlassian.com/display/JIRA/Creating+Release+Notes[generate release notes]:
+
+image::{_imagesdir}release-process/jira-create-release-notes.png[width="400px",link="{_imagesdir}release-process/jira-create-release-notes.png"]
+<img src="resources/jira-create-release-notes.png" width="400px"></img>
+
+If any of the tickets closed are tasks/subtasks, then please edit the contents of the file to associate them back together again.
+
+=== Mark the JIRA versions as released
+
+In JIRA, go to the administration section for the Apache Isis project and update the versions as released.
+
+=== Update ISIS website
+
+Update the Apache Isis CMS website:
+
+* Using the JIRA-generated release notes as a guide, update the relevant page of the Apache Isis site. +
++
+Use this regex to convert links.  From:
++
+[source,bash]
+----
+<li>\[<a href='(.+)?'>(.+?)<\/a>\].*-[\s]*(.*)$
+----
++
+to:
++
+[source,bash]
+----
+* link:$1[$2] - $3
+----
++
+and use this regex to convert headings.  From:
++
+[source,bash]
+----
+<h2>\s+(\S+)\n</h2>
+----
++
+to:
++
+[source,bash]
+----
+=== $1
+----
+
+
+
+Typically this be will a new page in the core section or for one of the components. Make a note of the URL of this new page (for use in the mailing list announcement).
+
+For example, a new release of Apache Isis Core would require:
+
+* Do a search for `x.y.0-SNAPSHOT` and replace with `x.y.0`
+
+* Update the version number on the link:./index.html[home (index)] pages.
+
+* Update the version number on the link:./simpleapp-archetype.html[simpleapp archetype] pages.
+
+
+In addition:
+
+* Update the link:./download.html[download page] with a link to the source release zip file (under https://dist.apache.org/repos/dist/release/isis[https://dist.apache.org/repos/dist/release/isis])
+
+* The link:./doap_isis.rdf[DOAP RDF] file (which provides a machine-parseable description of the project) should also be updated with details of the new release. Validate using the http://www.w3.org/RDF/Validator/[W3C RDF Validator] service.
+
+For more information on DOAP files, see these http://projects.apache.org/doap.html[Apache policy docs].
+
+* The `STATUS` file (in root of Apache Isis' source) should be updated with details of the new release.
+
+
+
+== Announce the release
+
+Announce the release to link:mailto:users@isis.apache.org[users mailing list].
+
+For example, for a release of Apache Isis Core, use the following subject:
+
+[source,bash]
+----
+[ANN] Apache Isis version 1.9.0 Released
+----
+
+And use the following body (summarizing the main points as required):
+
+[source]
+----
+The Apache Isis team is pleased to announce the release of:
+* Apache Isis Core version 1.9.0
+* SimpleApp Archetype 1.9.0
+
+New features in this release include:
+- ...
+
+Full release notes are available on the Apache Isis website at [1].
+
+Note that:
+* ...
+
+You can access this release directly from the Maven central repo [2],
+or download the release and build it from source [3].
+
+Enjoy!
+
+--The Apache Isis team
+
+[1] http://isis.apache.org/core/release-notes/isis-1.9.0.html
+[2] http://search.maven.org
+[3] http://isis.apache.org/download.html
+----
+
+=== Blog post
+
+Finally, https://blogs.apache.org/roller-ui/login.rol[log onto] the http://blogs.apache.org/isis/[Apache blog] and create a new post. Copy-n-paste the above mailing list announcement should suffice.
+
+== Prepare for next iteration
+
+=== Merge changes from branch back into `master` branch
+
+Because we release from a branch, the changes made in the branch (changes to `pom.xml` made by the `maven-release-plugin`, or any manual edits) should be merged back from the release branch back into the `master` branch:
+
+[source,bash]
+----
+git checkout master                   # update master with latest
+git pull
+git merge isis-1.9.0                  # merge branch onto master
+git branch -d isis-1.9.0              # branch no longer needed
+git push origin --delete isis-1.9.0   # remote branch no longer needed
+----
+
+If the core was updated, then you'll most likely need to update other POMs to the new `-SNAPSHOT`.
+
+Next, do a sanity check that everything builds ok:
+
+[source,bash]
+----
+rm -rf ~/.m2/repository/org/apache/isis
+mvn clean install
+----
+
+... and run up an Isis application.
+
+=== Update `STATUS` file
+
+The trunk holds a https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=blob_plain;f=STATUS;hb=HEAD[STATUS] file which is a brief summary of the current status of the project. Update this file with details of the release.
+
+=== Push changes
+
+Finally, push the changes up to origin:
+
+[source,bash]
+----
+git fetch    # check no new commits on origin/master
+git push
+----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_key-generation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_key-generation.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_key-generation.adoc
new file mode 100644
index 0000000..80b3e93
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_key-generation.adoc
@@ -0,0 +1,571 @@
+[[_cg_committers_key-generation]]
+= Key Generation
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+In order that a contributor can make a release it is necessary for them to have generated a key and had that key recognized by other members of the Apache Software Foundation. 
+
+For further background information on this topic, see the http://www.apache.org/dev/release-signing.html[release signing page] and the http://www.apache.org/dev/openpgp.html#generate-key[openpgp page] on the Apache wiki.
+
+
+
+== Install and Configure gpg
+
+Download and install GnuPG (gpg), version 1.4.10 or higher.
+
+Then, edit `~/.gnupg/gpg.conf` (on Windows, the file to edit is `C:\Users\xxx\AppData\Roaming\gnupg\gpg.conf`) so that the default is to generate a strong key:
+
+[source,bash]
+----
+personal-digest-preferences SHA512
+cert-digest-algo SHA512
+default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
+----
+
+
+
+
+== Key Generation
+
+The Apache Software Foundation requires that keys are signed with a key (or subkey) based on RSA 4096 bits. To do this:
+
+[source]
+----
+$ gpg --gen-key
+gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Please select what kind of key you want:
+   (1) RSA and RSA (default)
+   (2) DSA and Elgamal
+   (3) DSA (sign only)
+   (4) RSA (sign only)
+Your selection?
+----
+
+Specify RSA key:
+
+[source]
+----
+Your selection? 1
+
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048)
+----
+
+Specify key length as 4096 bits:
+
+[source]
+----
+What keysize do you want? (2048) 4096
+Requested keysize is 4096 bits
+
+Please specify how long the key should be valid.
+         0 = key does not expire
+      <n>  = key expires in n days
+      <n>w = key expires in n weeks
+      <n>m = key expires in n months
+      <n>y = key expires in n years
+Key is valid for? (0)
+----
+
+Specify key as non-expiring:
+
+[source]
+----
+Key is valid for? (0) 0
+Key does not expire at all
+Is this correct? (y/N) y
+
+You need a user ID to identify your key; the software constructs the user ID
+from the Real Name, Comment and Email Address in this form:
+    "Heinrich Heine (Der Dichter) <he...@duesseldorf.de>"
+
+Real name: 
+----
+
+Enter your name, email and comment:
+
+* use your apache.org email
+* the comment should be "CODE SIGNING KEY"
+
+Real name: Xxx Xxxxxxxxx
+Email address: link:mailto:&#x78;&#120;&#120;&#64;&#97;&#x70;&#97;&#99;&#104;&#x65;&#46;&#111;&#x72;&#103;[&#x78;&#120;&#120;&#64;&#97;&#x70;&#97;&#99;&#104;&#x65;&#46;&#111;&#x72;&#103;]
+Comment: CODE SIGNING KEY
+You selected this USER-ID:
+ "Xxx Xxxxxxxxx (CODE SIGNING KEY) link:mailto:&#x78;&#x78;&#x78;&#x40;&#97;&#x70;&#97;&#99;h&#101;&#x2e;&#x6f;r&#x67;[&#x78;&#x78;&#x78;&#x40;&#97;&#x70;&#97;&#99;h&#101;&#x2e;&#x6f;r&#x67;]"
+
+Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
+
+You need a Passphrase to protect your secret key.
+Enter passphrase:
+
+Provide a passphrase to secure your key.
+
+[source]
+----
+Enter passphrase:
+Repeat passphrase:
+----
+
+GPG will goes on to generate your key:
+
+[source]
+----
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+...+++++
+.........................+++++
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+....+++++
+...+++++
+gpg: key nnnnnnnn marked as ultimately trusted
+public and secret key created and signed.
+
+gpg: checking the trustdb
+gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
+pub   4096R/nnnnnnnn yyyy-mm-dd
+      Key fingerprint = xxxx xxxx xxxx xxxx xxxx  xxxx xxxx xxxx xxxx xxxx
+uid                  Xxx Xxxxxx <xx...@apache.org>
+sub   4096R/kkkkkkkk yyyy-mm-dd
+----
+
+The public key with id nnnnnnnn should now be stored in `~/.gnupg/pubring.pgp` (on Windows 7, this is in `c:/Users/xxx/AppData/Roaming/gnupg/pubring.pgp`).
+
+To confirm the key has been generated, use:
+
+[source]
+----
+$ gpg --list-keys --fingerprint
+----
+
+The key Id is the one true way to identify the key, and is also the last 8 digits of the fingerprint. The corresponding secret key for id `nnnnnnnn` is stored in `~/.gnupg/secring.pgp` (on Windows 7, this is in `c:/Users/xxx/AppData/Roaming/gnupg/secring.pgp`).
+
+It's also worth confirming the key has the correct preference of algorithms (reflecting the initial configuration we did earlier). For this, enter the gpg shell for your new key:
+
+[source]
+----
+$ gpg --edit-key nnnnnnnnn
+>gpg
+----
+
+where `nnnnnnnn` is your key id. Now, use the 'showpref' subcommand to list details:
+
+[source]
+----
+gpg> showpref
+[ultimate] (1). Xxx Xxxxxxxx (CODE SIGNING KEY) <xx...@apache.org>
+     Cipher: AES256, AES192, AES, CAST5, 3DES
+     Digest: SHA512, SHA384, SHA256, SHA224, SHA1
+     Compression: ZLIB, BZIP2, ZIP, Uncompressed
+     Features: MDC, Keyserver no-modify
+
+gpg>
+----
+
+The Digest line should list SHA-512 first and SHA-1 last. If it doesn't, use the "setpref" command:
+
+[source]
+----
+setpref SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
+----
+
+Finally, remember to take a backup of your key and the keyring (ie, backup the `.gnupg` directory and its contents).
+
+== Subkey Generation
+
+It's recommended to use a subkey with an expiry date to sign releases, rather than your main, non-expiring key. If a subkey is present, then gpg will use it for signing in preference to the main key.
+
+[NOTE]
+====
+After (binary) release artifacts are created, they are deployed to the ASF's Nexus staging repository. However, Nexus seems unable to retrieve a subkey from the public key server. Until we find a fix/workaround for this, all releases should be signed just with a regular non-expiring main key.
+====
+
+
+
+To create a subkey Enter the gpg shell using (the identifier of) your main key:
+
+[source]
+----
+gpg --edit-key xxxxxxxx
+gpg>
+----
+
+Type 'addkey' to create a subkey, and enter your passphrase for the main key:
+
+[source]
+----
+gpg> addkey
+Key is protected.
+[enter your secret passphrase]
+
+You need a passphrase to unlock the secret key for
+user: "Dan Haywood (CODE SIGNING KEY) <da...@apache.org>"
+4096-bit RSA key, ID xxxxxxxx, created 2011-02-01
+
+Please select what kind of key you want:
+   (3) DSA (sign only)
+   (4) RSA (sign only)
+   (5) Elgamal (encrypt only)
+   (6) RSA (encrypt only)
+Your selection?
+----
+
+Select (6) to choose an RSA key for encryption:
+
+[NOTE]
+====
+It would seem that Nexus repository manager does not recognize RSA subkeys with an 'S'ign usage; see this discussion on a mailing list and this issue on Sonatype's JIRA
+====
+
+
+[source]
+----
+Your selection? 6
+
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048) 4096
+
+Requested keysize is 4096 bits
+
+Please specify how long the key should be valid.
+         0 = key does not expire
+      <n>  = key expires in n days
+      <n>w = key expires in n weeks
+      <n>m = key expires in n months
+      <n>y = key expires in n years
+Key is valid for?
+----
+
+Specify that the key is valid for 1 year:
+
+[source]
+----
+Key is valid for? (0) 1y
+
+Key expires at yy/MM/dd hh:mm:ss
+Is this correct? (y/N) y
+Really create? (y/N) y
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+...+++++
+.+++++
+
+pub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: never       usage: SC
+                     trust: ultimate      validity: ultimate
+sub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: yyYY-mm-dd  usage: E
+[ultimate] (1). Dan Haywood (CODE SIGNING KEY) <da...@apache.org>
+
+gpg>
+----
+
+Quit the gpg shell; you now have a subkey.
+
+== Generate a Revocation Certificate
+
+It's good practice to generate a number of revocation certificates so that the key can be revoked if it happens to be compromised. See the http://www.apache.org/dev/openpgp.html#revocation-certs[gpg page] on the Apache wiki for more background on this topic.
+
+First, generate a "no reason specified" key:
+
+[source]
+----
+$ gpg --output revoke-nnnnnnnn-0.asc --armor --gen-revoke nnnnnnnn
+
+sec  4096R/nnnnnnnn yyyy-mm-dd Xxx Xxxxxxx (CODE SIGNING KEY) <xx...@apache.org>
+Create a revocation certificate for this key? (y/N) Y
+
+Please select the reason for the revocation:
+  0 = No reason specified
+  1 = Key has been compromised
+  2 = Key is superseded
+  3 = Key is no longer used
+  Q = Cancel
+(Probably you want to select 1 here)
+Your decision?
+----
+
+Select 0.
+
+[source]
+----
+Your decision? 0
+
+Enter an optional description; end it with an empty line:
+----
+
+Provide a description:
+
+[source]
+----
+> Generic certificate to revoke key, generated at time of key creation.
+>
+Reason for revocation: No reason specified
+Generic certificate to revoke key, generated at time of key creation.
+Is this okay? (y/N)
+----
+
+Confirm this is ok.
+
+[source]
+----
+Is this okay? y
+
+You need a passphrase to unlock the secret key for
+user: "Xxx Xxxxxxx (CODE SIGNING KEY) <xx...@apache.org>"
+4096-bit RSA key, ID nnnnnnnn, created yyyy-mm-dd
+
+Enter passphrase:
+</pre>
+
+Enter a passphrase:
+
+<pre>
+Enter passphrase:
+Revocation certificate created.
+
+Please move it to a medium which you can hide away; if Mallory gets
+access to this certificate he can use it to make your key unusable.
+It is smart to print this certificate and store it away, just in case
+your media become unreadable.  But have some caution:  The print system of
+your machine might store the data and make it available to others!
+----
+
+The file `revoke-nnnnnnnn-0.asc` should be created: Then, backup this file.
+
+Now repeat the process to create two further revocation certificates:
+
+[source,bash]
+----
+gpg --output revoke-nnnnnnnn-1.asc --armor --gen-revoke nnnnnnnn
+----
+
+Specify reason as "1 = Key has been compromised"
+
+and:
+
+[source,bash]
+----
+gpg --output revoke-nnnnnnnn-3.asc --armor --gen-revoke nnnnnnnn
+----
+
+Specify reason as "3 = Key is no longer used"
+
+Backup these files also.
+
+
+
+
+
+== Publish Key
+
+It is also necessary to publish your key. There are several places where this should be done. In most cases, you'll need the "armored" &quot; (ie ASCII) representation of your key. This can be generated using:
+
+[source]
+----
+$ gpg --armor --export nnnnnnnn > nnnnnnnn.asc
+----
+
+where `nnnnnnnn` is the id of your public key.
+
+You'll also need the fingerprint of your key. This can be generated using:
+
+[source]
+----
+$ gpg --fingerprint nnnnnnnn
+----
+
+The output from this command includes a line beginning "Key fingerprint", followed by a (space delimited) 40 character hexadecimal fingerprint. The last 8 characters should be the same as the key id (`nnnnnnnn`).
+
+=== Publish to a public key server
+
+To a publish your key to a public key server (eg the MIT key server hosted at http://pgp.mit.edu[http://pgp.mit.edu]), use the procedure below. Public key servers synchronize with each other, so publishing to one key server should be sufficient. For background reading on this, see the http://www.apache.org/dev/release-signing.html#keyserver-upload[release signing page] on the Apache wiki, and the http://maven.apache.org/developers/release/pmc-gpg-keys.html[gpg key page] on the Maven wiki.
+
+To send the key up to the key server:
+
+[source]
+----
+$ gpg --send-keys --keyserver pgp.mit.edu nnnnnnnn
+----
+
+where `nnnnnnnn` is the key Id.
+
+Alternatively, you can browse to the http://pgp.mit.edu/[MIT key server] and paste in the armored representation of your key.
+
+Confirm the key has been added by browsing to submitting the following URL:
+
+`http://pgp.mit.edu:11371/pks/lookup?search=0xnnnnnnnnn&amp;op=vindex`
+
+again, where `nnnnnnnn` is the key Id.
+
+=== Publish to your Apache home directory
+
+The armored representation of your public key should be uploaded to your home directory on `people.apache.org`, and renamed as `.pgpkey`. Make sure this is readable by all.
+
+=== Publish to your Apache HTML home directory
+
+The armored representation of your public key should be uploaded to your `public_html` home directory on `people.apache.org`, named `nnnnnnnn.asc`. Make sure this is readable by all.
+
+Check the file is accessible by browsing to:
+
+`http://people.apache.org/~xxxxxxxx/nnnnnnnn.asc`
+
+where
+
+* `xxxxxxxx` is your apache LDAP user name
+* `nnnnnnnn` is your public key id.
+
+=== FOAF
+
+First, check out the committers/info directory:
+
+Go to Apache http://people.apache.org/foaf/foafamatic.html[FOAF-a-matic] web page to generate the FOAF file text (we copy this text out in a minute):
+
+* enter ASF LDAP user name
+* enter First name, Last name
+* for PGP key fingerprints, add Key
+* paste in the key id
+* paste in the fingerprint
+* press "Create"
+
+In the box below, you should have a FOAF file, something like:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<rdf:RDF
+      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+      xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
+      xmlns:foaf="http://xmlns.com/foaf/0.1/"
+      xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
+      xmlns:pm="http://www.web-semantics.org/ns/pm#"
+      xmlns:wot="http://xmlns.com/wot/0.1/"
+      xmlns:rss="http://purl.org/rss/1.0/"
+      xmlns:dc="http://purl.org/dc/elements/1.1/"
+      xmlns:ical="http://www.w3.org/2002/12/cal/ical#"
+      xmlns:doap="http://usefulinc.com/ns/doap#">
+  <foaf:Person rdf:ID="danhaywood">
+    <foaf:name>Xxx Xxxxxxxx</foaf:name>
+    <foaf:givenname>Xxx</foaf:givenname>
+    <foaf:family_name>Xxxxxxxx</foaf:family_name>
+    <wot:hasKey>
+      <wot:PubKey>
+        <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
+        <wot:hex_id>nnnnnnnn</wot:hex_id>
+      </wot:PubKey>
+    </wot:hasKey>
+  </foaf:Person>
+</rdf:RDF>
+----
+
+(If you are creating the FOAF file for the first time, you may want to add additional details).
+
+From this, copy out the `wot:key`, and paste into your FDF file in `committers/info`:
+
+[source,xml]
+----
+<wot:hasKey>
+  <wot:PubKey>
+    <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
+    <wot:hex_id>nnnnnnnn</wot:hex_id>
+  </wot:PubKey>
+</wot:hasKey>
+----
+
+Then, manually add in a `&lt;wot:pubkeyAddress&gt;` element within `&lt;wot:PubKey&gt;`:
+
+[source,xml]
+----
+<wot:hasKey>
+  <wot:PubKey>
+    <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
+    <wot:hex_id>nnnnnnnn</wot:hex_id>
+    <wot:pubkeyAddress rdf:resource="http://people.apache.org/~username/nnnnnnnn.asc/">
+  </wot:PubKey>
+</wot:hasKey>
+----
+
+ie, referencing your publically exported public key
+
+Finally, commit your changes.
+
+=== Save to `KEYS`
+
+The armored representation of the public key should be saved to Apache Isis' `KEYS` file, http://www.apache.org/dist/isis/KEYS[http://www.apache.org/dist/isis/KEYS] (that is, in the ASF distribution directory for Apache Isis).
+
+First, in a new directory, checkout this file:
+
+[source]
+----
+svn -N co https://svn.apache.org/repos/asf/isis/ .
+----
+
+This should bring down the `KEYS` file.
+
+Then, export your signature and armored representation.
+
+[source]
+----
+gpg --list-sigs nnnnnnnn >>KEYS
+gpg --armor --export nnnnnnnn >>KEYS
+----
+
+Then commit.
+
+=== id.apache.org
+
+Log onto `id.apache.org` and ensure that the finger print of your public key is correct.
+
+== Attend Key Signing Party (Apache web of trust)
+
+It is strongly advised that the contributor attend a key signing party at an Apache event, in order that other Apache committers/members can in person verify their identity against the key. The process for this is described http://www.apache.org/dev/release-signing.html#key-signing-party[here] and http://wiki.apache.org/apachecon/PgpKeySigning[here].
+
+== Update Maven Settings file (`~/.m2/settings.xml`)
+
+The Maven release plugin will automatically sign the release, however it is necessary to update the `~/.m2/settings.xml` file with your GPG acronym passphrase in order that it can use your secret key. This is defined under a profile so that it is activated only when we perform a release (as defined by `[org,apache:apache]` parent POM.
+
+Therefore, make the following edits:
+
+[source,xml]
+----
+<settings>
+  ...
+  <profiles>
+    <profile>
+      <id>apache-release</id>
+      <properties>
+        <gpg.passphrase>xxx xxx xxx xxx xxx xxx xxx</gpg.passphrase>
+      </properties>
+    </profile>
+  </profiles>
+</settings>
+----
+
+In addition, to allow the release plugin to tag SVN changes, you must either add in your LDAP username/password or configure `.ssh`:
+
+[source,xml]
+----
+<settings>
+  ...
+  <servers>
+    ...
+    <server>
+      <id>apache.releases.https</id>
+      <username>xxxx</username>
+      <password>xxxx</password>
+    </server>
+  </servers>
+</settings>
+----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_pmc-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_pmc-notes.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_pmc-notes.adoc
new file mode 100644
index 0000000..c12b57c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_pmc-notes.adoc
@@ -0,0 +1,71 @@
+[[_cg_committers_pmc-notes]]
+= Project Management Committee (PMC)
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+Every ASF project has a Project Management Committee, or PMC.  This committee is ultimately responsible for the long-term management of the framework.  More information about PMCs can be found link:http://www.apache.org/dev/pmc.html[here]
+
+In Apache Isis, every committer is a member of the PMC.
+
+This page contains some general notes on maintenance activities required by PMC members.
+
+
+
+== Accessing `people.apache.org`
+
+Must be accessed via ssh.
+
+eg:
+
+[source,bash]
+----
+ssh danhaywood@people.apache.org
+----
+
+and when prompted, provide passphrase for private key... though I've forgotten what I did to set this up in the first place, though :-(
+
+
+
+
+== LDAP Access (UNIX groups)
+
+Whenever we get a new committer, the ASF LDAP entries must be maintained to grant access to our repos and various other 'karma'.
+
+Log onto `people.apache.org`, then use:
+
+[source]
+----
+list_unix_group.pl isis
+----
+
+to list committers
+
+[source]
+----
+list_committee.pl isis
+----
+
+to list the PMC committee members (in Apache Isis, every committer should be on the PMC committee)
+
+To change membership of either the committers or the PMC, use:
+
+[source]
+----
+modify_unix_group.pl isis --add joebloggs
+modify_unix_group.pl isis --remove joebloggs
+----
+
+and
+
+[source]
+----
+modify_committee.pl gump --add joebloggs
+modify_committee.pl gump --remove joebloggs
+----
+
+respectively.
+
+Further details are in http://www.apache.org/dev/pmc.html#SVNaccess[these ASF docs]. (They talk about SVN access, but really it is LDAP access).
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_recreating-an-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_recreating-an-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_recreating-an-archetype.adoc
new file mode 100644
index 0000000..0a35e55
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_recreating-an-archetype.adoc
@@ -0,0 +1,335 @@
+[[_cg_committers_recreating-an-archetype]]
+= Recreating an Archetype
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+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.
+
+
+
+== Setup environment variables
+
+To recreate the *simpleapp* archetype:
+
+[source,bash]
+----
+cd example/application/simpleapp
+
+export ISISTMP=/c/tmp   # or as required
+export ISISART=simpleapp-archetype
+export ISISDEV=1.9.0-SNAPSHOT
+export ISISREL=1.8.0
+export ISISPAR=1.8.0
+export ISISRC=RC1
+
+export ISISCPT=$(echo $ISISART | cut -d- -f2)
+export ISISCPN=$(echo $ISISART | cut -d- -f1)
+
+env | grep ISIS | sort
+----
+
+nb: `$ISISPAR` is the version of the Apache Isis core that will act as the archetype's parent. Usually this is the same as `$ISISREL`.
+
+
+
+== Check the example app
+
+Make sure you are in the correct directory, and update the parent `pom.xml` to reference the _released_ version of Apache Isis core:
+
+[source,xml]
+----
+<properties>
+    <isis.version>1.8.0</isis.version>
+    ...
+</properties>
+----
+
+Alternatively, you could just load up each `pom.xml` and inspect manually:
+
+[source,bash]
+----
+vi `/bin/find . -name pom.xml | grep -v target`
+----
+
+... and search for `SNAPSHOT`.
+
+Next, check for and fix any missing license header notices:
+
+[source,bash]
+----
+mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o
+for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done
+----
+
+Finally, double check that the app is running satisfactorily:
+
+first, as self-hosted webconsole (browse to http://localhost:8080[http://localhost:8080]):
+
+[source,bash]
+----
+mvn clean install
+mvn antrun:run -P self-host
+----
+
+then using mvn jetty plugin:
+
+[source,bash]
+----
+cd webapp
+mvn jetty:run     
+----
+
+Browse to http://localhost:8080/simpleapp-webapp/[http://localhost:8080/simpleapp-webapp/].
+
+Check the about page and confirm built against non-SNAPSHOT versions of the Apache Isis jars.
+
+
+
+=== Create the archetype (manual)
+
+[IMPORTANT]
+====
+The archetype can be created either by hand or with a script. The section describes the manual approach; the scripted approach is in the section after.
+====
+
+
+Before we generate the archetype, we clear out all non source code artifacts.
+
+Start by doing the regular `mvn clean`:
+
+[source,bash]
+----
+mvn clean
+----
+
+To view the remaining files/directories that needs removing, use:
+
+[source,bash]
+----
+for a in .project .classpath .settings bin .idea target-ide; do /bin/find . -name $a -print; done
+/bin/find . -name "*.iml" -print
+/bin/find . -name "*.log" -print
+/bin/find . -name "pom.xml.*" -print
+----
+
+To actually delete these files, use:
+
+[source,bash]
+----
+for a in .project .classpath .settings bin .idea target-ide; do /bin/find . -name $a -exec rm -r {} \;; done
+/bin/find . -name "*.iml" -exec rm {} \;
+/bin/find . -name "*.log" -exec rm {} \;
+/bin/find . -name "pom.xml.*" -exec rm {} \;
+----
+
+Quickly check that the remaining files are all source files:
+
+[source,bash]
+----
+/bin/find .
+----
+
+Now we can create the archetype.
+
+[source,bash]
+----
+mvn archetype:create-from-project
+----
+
+and then update the generated files:
+
+[source,bash]
+----
+groovy ../../../scripts/updateGeneratedArchetypeSources.groovy -n $ISISCPN -v $ISISPAR
+----
+
+where:
+
+* `$ISISCPN` is the component name set earlier (`simpleapp`)
+* `$ISISPAR` is the version of Apache isis core that is to be the parent of the generated archetype,
+** this will usually be the same as `$ISISREL` unless a patch/interim release of the archetype.
+
+
+
+
+=== Test the archetype
+
+First, build the archetype:
+
+[source,bash]
+----
+cd target/generated-sources/archetype
+mvn clean install
+cd ../../..
+----
+
+Then, _in a different session_, create a new app from the archetype:
+
+Set up environment variables:
+
+To test the *simpleapp* archetype:
+
+[source,bash]
+----
+export ISISTMP=/c/tmp    # or as required
+export ISISCPN=simpleapp
+env | grep ISIS | sort
+----
+
+Then recreate:
+
+[source,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
+----
+
+Build the newly generated app and test:
+
+[source,bash]
+----
+cd myapp
+mvn clean install
+mvn antrun:run -P self-host    # runs as standalone app using webconsole
+cd webapp
+mvn jetty:run                  # runs as mvn jetty plugin
+----
+
+
+=== Check the archetype source code into git
+
+Back in the _original session_ (at `example/application/simpleapp`), we are ready to check the archetype source code into git:
+
+[source,bash]
+----
+git rm -rf ../../archetype/$ISISCPN
+rm -rf ../../archetype/$ISISCPN
+----
+
+In either case make sure that the `archetype/$ISISCPN` directory was fully removed, otherwise the next command will not copy the regenerated source into the correct location.
+
+Then, copy over the generated source of the archetype:
+
+[source,bash]
+----
+mv target/generated-sources/archetype ../../archetype/$ISISCPN
+git add ../../archetype/$ISISCPN
+----
+
+Next, confirm that the `-SNAPSHOT` version of the archetype is correct:
+
+[source,bash]
+----
+vi ../../archetype/$ISISCPN/pom.xml
+----
+
+If this a new archetype, then add a reference to the archetype to the root `pom.xml`, eg:
+
+[source,xml]
+----
+<modules>
+    ...
+    <module>example/archetype/newapp</module>
+    ...
+</modules>
+----
+
+Finally, commit the changes:
+
+[source,bash]
+----
+git commit -am "ISIS-nnn: updating $ISISCPN archetype"
+----
+
+=== Create the archetype (scripted)
+
+[IMPORTANT]
+====
+Using the script does not generate an app from the archetype to test it works.
+====
+
+Make sure you are in the correct directory and environment variables are correct.
+
+To recreate the *simpleapp* archetype:
+
+[source,bash]
+----
+cd example/application/simpleapp
+
+env | grep ISIS | sort
+----
+
+If the environment variables look wrong, use the commands at the top of this page to setup.
+The script will also double check that all required environment variables are set.
+
+Then, run the script:
+
+[source,bash]
+----
+sh ../../../scripts/recreate-archetype.sh ISIS-nnn
+----
+
+The script automatically commits changes; if you wish use `git log` and
+`git diff` (or a tool such as SourceTree) to review changes made.
+
+=== Releasing the Archetype
+
+{note
+Releasing the archetype is performed from the *example/archetype* directory,
+NOT the _example/application_ directory.
+}
+
+The procedure for releasing the archetype is the same as for any other releasable module.
+
+First, confirm environment variables set correctly:
+
+[source,bash]
+----
+env | grep ISIS | sort
+----
+
+Then switch the correct directory and release:
+
+[source]
+----
+cd ../../../example/archetype/$ISISCPN
+
+rm -rf $ISISTMP/checkout
+
+mvn release:prepare -P apache-release \
+                -DreleaseVersion=$ISISREL \
+                -DdevelopmentVersion=$ISISDEV \
+                -Dtag=$ISISART-$ISISREL
+mvn release:perform -P apache-release \
+                -DworkingDirectory=$ISISTMP/checkout
+----
+
+Next, log onto http://repository.apache.org[repository.apache.org] and close the staging repo.
+
+Then push branch:
+
+[source,bash]
+----
+git push -u origin prepare/$ISISART-$ISISREL
+----
+
+and push tag:
+
+[source]
+----
+git push origin refs/tags/$ISISART-$ISISREL-$ISISRC:refs/tags/$ISISART-$ISISREL-$ISISRC
+git fetch
+----
+
+See the link:release-process.html[release process] for full details.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-checklist.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-checklist.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-checklist.adoc
new file mode 100644
index 0000000..4d09c59
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-checklist.adoc
@@ -0,0 +1,86 @@
+[[_cg_committers_release-checklist]]
+= Release Checklist
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+This page contains a release checklist to support the xref:cg.adoc#_cg_committers_cutting-a-release[full release process] and xref:cg.adoc#_cg_committers_cutting-a-release-one-pager[one-pager].
+
+
+
+
+.Prepare
+[cols="1,1,1,1,1,1,1,1,1,1", options="header"]
+|===
+
+
+|Artifact
+|Env?
+|Update parent POM ver.
+|Newer plugin versions
+|Newer deps
+|Formatting
+|License headers (RAT)
+|License check
+|Recreate archetype
+|Commit changes
+
+|isis
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|n/a
+|&nbsp;
+
+|simpleapp-archetype
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+
+|===
+
+
+
+.Release
+[cols="1,1,1,1,1,1,1", options="header"]
+|===
+
+|Artifact
+|prepare dryrun
+|prepare
+|confirm
+|perform
+|stage (nexus)
+|git push
+
+|isis
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+
+|simpleapp-archetype
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+|&nbsp;
+
+|===
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-for-snapshots.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-for-snapshots.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-for-snapshots.adoc
new file mode 100644
index 0000000..cb3fa6e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process-for-snapshots.adoc
@@ -0,0 +1,96 @@
+[[_cg_committers_release-process-for-snapshots]]
+= Release Process for Snapshots
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+Apache Isis consists of a number of separately releasable modules; see the main link:release-process.html[release process] documentation for full details. All the non-core components depend on the `core`, and use the `core`'s parent `pom.xml` as their parent pom.
+
+[NOTE]
+====
+Unless otherwise stated, you should assume that the steps described here are performed in the base directory of the module being released.
+====
+
+
+== Prerequisites
+
+Before you start, make sure you've defined the snapshots repo in your local `~/.m2/settings.xml` file:
+
+[source,xml]
+----
+<settings>
+  <servers>
+    <!-- To publish a snapshot of some part of Maven -->
+    <server>
+      <id>apache.snapshots.https</id>
+      <username>xxxxxxx</username>
+      <password>yyyyyyy</password>
+    </server>
+    ...
+  </servers>
+  ...
+</settings>
+----
+
+where `xxxxxxx` and `yyyyyyy` are your Apache LDAP username and password. For more information, see these http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env[ASF docs].
+
+{note
+It is also possible to configure to use `.ssh` secure keys, and thereby avoid hardcoding your Apache LDAP password into your `.m2/settings.xml` file. A description of how to do this can be found, for example, http://bval.apache.org/release-setup.html[here].
+}
+
+
+
+== Sanity Check
+
+Before deploying the snapshot, perform a quick sanity check.
+
+First, delete all Isis artifacts from your local Maven repo:
+
+[source,bash]
+----
+rm -rf ~/.m2/repository/org/apache/isis
+----
+
+Next, check that the releasable module builds independently. The build process depends on whether the artifact is of Apache Isis core or of one of its components:
+
+* For Apache Isis core, build using the `-o` offline flag: +
++
+[source,bash]
+----
+mvn clean install -o
+----
++
+Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
+
+* For an Apache Isis component, build without the offline flag; Maven should pull down the component's dependencies from the Maven central repo: +
++
+[source,bash]
+----
+mvn clean install
+----
++
+Confirm that the versions of the Isis artifacts now cached in your local repository are correct (both those pulled down from Maven central repo, as well as those of the component built locally).
+
+
+
+== Deploy All Modules
+
+Deploy all modules using:
+
+[source,bsah]
+----
+mvn -D deploy=snapshot deploy
+----
+
+This will deploy all the modules that make up a release.
+
+To confirm that they are present, browse to Apache's https://repository.apache.org[Nexus repository manager] and search for "isis".
+
+[TIP]
+====
+Depending on the module being released, the deploy process could take a long time. Go grab a bite of lunch.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc
new file mode 100644
index 0000000..77c01ae
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc
@@ -0,0 +1,152 @@
+[[_cg_committers_verify-releases-using-a-script]]
+= Verify using a script
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+To save some time in verifying an Apache Isis release we've assembled a script to automate the process. The script is tested on Mac OSX and Linux. Windows users can use Cygwin or http://msysgit.github.io/[msysgit].
+
+It's _recommended_ that you start this process in an empty directory:
+
+[source,bash]
+----
+mkdir ~/verify-isis-release
+cd ~/verify-isis-release
+----
+
+
+
+
+== Copy the script to your local machine
+
+The script could be enhanced in many ways, feel free to do so! Copy (or link:resources/release-process/verify-isis-release.sh[download]) the `verify-isis-release.sh` script below:
+
+[source,bash]
+----
+#!/bin/bash
+# Instructions:
+# -Create an empty directory
+# -Put a .txt file in it containing a list of all the urls of the zip files
+# -Run this script
+# TODO: enhance this script so it will stop when something is broken
+_download(){
+    for fil in `cat *.txt`
+    do
+       echo 'Downloading '$fil
+       curl  -L -O $fil
+       curl  -L -O $fil.asc
+    done
+}
+_verify(){
+    for zip in *.zip
+    do 
+       echo 'Verifying '$zip 
+       gpg --verify $zip.asc $zip 
+    done
+}
+_unpack(){
+    echo 'Unpacking '
+    unzip -q '*.zip'
+}
+_build(){
+    echo 'Removing Apache Isis from local repo '$module
+    rm -rf ~/.m2/repository/org/apache/isis
+    COUNTER=0
+    for module in ./*/
+    do
+       COUNTER=$[COUNTER+1]
+       if [ $COUNTER -eq 1 ]
+       then
+         cd $module
+         echo 'Building Core '$module
+         mvn clean install -o
+         cd ..
+       else
+         cd $module
+         echo 'Building Module '$module
+         mvn clean install
+         cd ..
+       fi
+    done
+}
+# The work starts here 
+_download
+_verify
+_unpack
+_build
+----
+
+Make sure the script is executable:
+
+[source]
+----
+chmod +x verify-isis-release.sh
+----
+
+
+
+
+== Create an input file
+
+The input file is a plain `.txt` file containing all urls to the packages to be verified. Here's a sample of the release of Apache Isis 1.8.0:
+
+[source]
+----
+https://repository.apache.org/content/repositories/orgapacheisis-063/org/apache/isis/core/isis/1.8.0/isis-1.8.0-source-release.zip
+https://repository.apache.org/content/repositories/orgapacheisis-065/org/apache/isis/archetype/simpleapp-archetype/1.8.0/simpleapp-archetype-1.8.0-source-release.zip
+----
+
+The actual list of packages to be verified will be provided through the mailing list.
+
+
+
+
+== Clean out Apache Isis from your local Maven repo
+
+[source,bash]
+----
+rm -rf ~/.m2/repository/org/apache/isis
+----
+
+
+
+== Execute the script
+
+Execute...
+
+[source,bash]
+----
+./verify-isis-release.sh
+----
+
+…and get yourself a cup of coffee.
+
+
+
+
+== Test the archetype
+
+Assuming that everything builds ok, then test the archetypes (adjust version as necessary):
+
+[source,bash]
+----
+mvn archetype:generate  \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=simpleapp-archetype \
+    -D groupId=com.mycompany \
+    -D artifactId=myapp \
+    -D version=1.0-SNAPSHOT \
+    -B \
+    -o \
+    -D archetypeVersion=1.8.0   # adjust version as necessary
+
+cd myapp
+mvn clean install -o
+mvn -P self-host antrun:run
+----
+
+If it runs up ok, then it's time to xref:cg.adoc#_cg_committers_verifying-releases[vote]!
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-creadur-tools.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-creadur-tools.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-creadur-tools.adoc
new file mode 100644
index 0000000..30b758f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-creadur-tools.adoc
@@ -0,0 +1,46 @@
+[[_cg_committers_verifying-releases-using-creadur-tools]]
+= Verifying using Creadur
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+The http://creadur.apache.org[Apache Creadur] project exists to provide a set of tools to ensure compliance with Apache's licensing standards. The main release auditing tool, http://creadur.apache.org/rat[Apache RAT], is used in the preparation of the release (as documented link:release-process.html[here]). Creadur's remaining tools are to support the verification process.
+
+At the time of writing, these additional tools are quite young and haven't been formally released; so to use them will take a little bit of work. In the future we expect these tools to mature and ease the effort required to verify releases.
+
+
+
+== Using the Tentacles tool
+
+At the time of writing the Tentacles tool hasn't been released, so you'll need to build from source:
+
+[source,bash]
+----
+mkdir /tmp/verify
+cd /tmp/verify
+svn co http://svn.apache.org/repos/asf/creadur/tentacles/trunk creadur-tentacles
+cd creadur-tentacles
+mvn clean install
+----
+
+You can pull down a release, using a command such as:
+
+[source,bash]
+----
+cd /tmp/verify
+java -jar creadur-tentacles/target/apache-tentacles-0.1-SNAPSHOT.jar https://repository.apache.org/content/repositories/orgapacheisis-NNN/
+----
+
+where `NNN` is the repository that has the staged artifacts requiring verification.
+
+As per the http://creadur.apache.org/tentacles/[tentacles documentation], this command generates a report called `archives.html` (in the newly created `orgapacheisis-NNN` directory). This lists all of the top-level binaires, their `LICENSE` and `NOTICE` files and any `LICENSE` and `NOTICE` files of any binaries they may contain.
+
+Validation of the output at this point is all still manual. Things to check for include:
+
+* any binaries that contain no LICENSE and NOTICE files
+* any binaries that contain more than one LICENSE or NOTICE file
+
+In this report, each binary will have three links listed after its name '(licenses, notices, contents)'
\ No newline at end of file

[03/10] isis git commit: ISIS-1133: pulling together the contributors guide.

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/snapshot-process.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/snapshot-process.adoc b/adocs/documentation/src/main/asciidoc/snapshot-process.adoc
deleted file mode 100644
index e0ed5c6..0000000
--- a/adocs/documentation/src/main/asciidoc/snapshot-process.adoc
+++ /dev/null
@@ -1,96 +0,0 @@
-[[snapshot-release-process]]
-= Snapshot Release Process
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-Apache Isis consists of a number of separately releasable modules; see the main link:release-process.html[release process] documentation for full details. All the non-core components depend on the `core`, and use the `core`'s parent `pom.xml` as their parent pom.
-
-[NOTE]
-====
-Unless otherwise stated, you should assume that the steps described here are performed in the base directory of the module being released.
-====
-
-
-== Prerequisites
-
-Before you start, make sure you've defined the snapshots repo in your local `~/.m2/settings.xml` file:
-
-[source,xml]
-----
-<settings>
-  <servers>
-    <!-- To publish a snapshot of some part of Maven -->
-    <server>
-      <id>apache.snapshots.https</id>
-      <username>xxxxxxx</username>
-      <password>yyyyyyy</password>
-    </server>
-    ...
-  </servers>
-  ...
-</settings>
-----
-
-where `xxxxxxx` and `yyyyyyy` are your Apache LDAP username and password. For more information, see these http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env[ASF docs].
-
-{note
-It is also possible to configure to use `.ssh` secure keys, and thereby avoid hardcoding your Apache LDAP password into your `.m2/settings.xml` file. A description of how to do this can be found, for example, http://bval.apache.org/release-setup.html[here].
-}
-
-
-
-== Sanity Check
-
-Before deploying the snapshot, perform a quick sanity check.
-
-First, delete all Isis artifacts from your local Maven repo:
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-----
-
-Next, check that the releasable module builds independently. The build process depends on whether the artifact is of Apache Isis core or of one of its components:
-
-* For Apache Isis core, build using the `-o` offline flag: +
-+
-[source,bash]
-----
-mvn clean install -o
-----
-+
-Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
-
-* For an Apache Isis component, build without the offline flag; Maven should pull down the component's dependencies from the Maven central repo: +
-+
-[source,bash]
-----
-mvn clean install
-----
-+
-Confirm that the versions of the Isis artifacts now cached in your local repository are correct (both those pulled down from Maven central repo, as well as those of the component built locally).
-
-
-
-== Deploy All Modules
-
-Deploy all modules using:
-
-[source,bsah]
-----
-mvn -D deploy=snapshot deploy
-----
-
-This will deploy all the modules that make up a release.
-
-To confirm that they are present, browse to Apache's https://repository.apache.org[Nexus repository manager] and search for "isis".
-
-[TIP]
-====
-Depending on the module being released, the deploy process could take a long time. Go grab a bite of lunch.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/verifying-releases-script.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/verifying-releases-script.adoc b/adocs/documentation/src/main/asciidoc/verifying-releases-script.adoc
deleted file mode 100644
index 256990c..0000000
--- a/adocs/documentation/src/main/asciidoc/verifying-releases-script.adoc
+++ /dev/null
@@ -1,152 +0,0 @@
-[[verify-releases-using-a-script]]
-= Verify releases using a script
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-To save some time in verifying an Apache Isis release we've assembled a script to automate the process. The script is tested on Mac OSX and Linux. Windows users can use Cygwin or http://msysgit.github.io/[msysgit].
-
-It's _recommended_ that you start this process in an empty directory:
-
-[source,bash]
-----
-mkdir ~/verify-isis-release
-cd ~/verify-isis-release
-----
-
-
-
-
-== Copy the script to your local machine
-
-The script could be enhanced in many ways, feel free to do so! Copy (or link:resources/release-process/verify-isis-release.sh[download]) the `verify-isis-release.sh` script below:
-
-[source,bash]
-----
-#!/bin/bash
-# Instructions:
-# -Create an empty directory
-# -Put a .txt file in it containing a list of all the urls of the zip files
-# -Run this script
-# TODO: enhance this script so it will stop when something is broken
-_download(){
-    for fil in `cat *.txt`
-    do
-       echo 'Downloading '$fil
-       curl  -L -O $fil
-       curl  -L -O $fil.asc
-    done
-}
-_verify(){
-    for zip in *.zip
-    do 
-       echo 'Verifying '$zip 
-       gpg --verify $zip.asc $zip 
-    done
-}
-_unpack(){
-    echo 'Unpacking '
-    unzip -q '*.zip'
-}
-_build(){
-    echo 'Removing Apache Isis from local repo '$module
-    rm -rf ~/.m2/repository/org/apache/isis
-    COUNTER=0
-    for module in ./*/
-    do
-       COUNTER=$[COUNTER+1]
-       if [ $COUNTER -eq 1 ]
-       then
-         cd $module
-         echo 'Building Core '$module
-         mvn clean install -o
-         cd ..
-       else
-         cd $module
-         echo 'Building Module '$module
-         mvn clean install
-         cd ..
-       fi
-    done
-}
-# The work starts here 
-_download
-_verify
-_unpack
-_build
-----
-
-Make sure the script is executable:
-
-[source]
-----
-chmod +x verify-isis-release.sh
-----
-
-
-
-
-== Create an input file
-
-The input file is a plain `.txt` file containing all urls to the packages to be verified. Here's a sample of the release of Apache Isis 1.8.0:
-
-[source]
-----
-https://repository.apache.org/content/repositories/orgapacheisis-063/org/apache/isis/core/isis/1.8.0/isis-1.8.0-source-release.zip
-https://repository.apache.org/content/repositories/orgapacheisis-065/org/apache/isis/archetype/simpleapp-archetype/1.8.0/simpleapp-archetype-1.8.0-source-release.zip
-----
-
-The actual list of packages to be verified will be provided through the mailing list.
-
-
-
-
-== Clean out Apache Isis from your local Maven repo
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-----
-
-
-
-== Execute the script
-
-Execute...
-
-[source,bash]
-----
-./verify-isis-release.sh
-----
-
-…and get yourself a cup of coffee.
-
-
-
-
-== Test the archetype
-
-Assuming that everything builds ok, then test the archetypes (adjust version as necessary):
-
-[source,bash]
-----
-mvn archetype:generate  \
-    -D archetypeGroupId=org.apache.isis.archetype \
-    -D archetypeArtifactId=simpleapp-archetype \
-    -D groupId=com.mycompany \
-    -D artifactId=myapp \
-    -D version=1.0-SNAPSHOT \
-    -B \
-    -o \
-    -D archetypeVersion=1.8.0   # adjust version as necessary
-
-cd myapp
-mvn clean install -o
-mvn -P self-host antrun:run
-----
-
-If it runs up ok, then it's time to link:verifying-releases.html[vote]!
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/verifying-releases-using-creadur-tools.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/verifying-releases-using-creadur-tools.adoc b/adocs/documentation/src/main/asciidoc/verifying-releases-using-creadur-tools.adoc
deleted file mode 100644
index 695d324..0000000
--- a/adocs/documentation/src/main/asciidoc/verifying-releases-using-creadur-tools.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[verifying-releases-using-creadur-tools]]
-= Verifying Releases using Creadur Tools
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-The http://creadur.apache.org[Apache Creadur] project exists to provide a set of tools to ensure compliance with Apache's licensing standards. The main release auditing tool, http://creadur.apache.org/rat[Apache RAT], is used in the preparation of the release (as documented link:release-process.html[here]). Creadur's remaining tools are to support the verification process.
-
-At the time of writing, these additional tools are quite young and haven't been formally released; so to use them will take a little bit of work. In the future we expect these tools to mature and ease the effort required to verify releases.
-
-== Using the Tentacles tool
-
-At the time of writing the Tentacles tool hasn't been released, so you'll need to build from source:
-
-[source]
-----
-mkdir /tmp/verify
-cd /tmp/verify
-svn co http://svn.apache.org/repos/asf/creadur/tentacles/trunk creadur-tentacles
-cd creadur-tentacles
-mvn clean install
-----
-
-You can pull down a release, using a command such as:
-
-[source]
-----
-cd /tmp/verify
-java -jar creadur-tentacles/target/apache-tentacles-0.1-SNAPSHOT.jar https://repository.apache.org/content/repositories/orgapacheisis-NNN/
-----
-
-where `NNN` is the repository that has the staged artifacts requiring verification.
-
-As per the http://creadur.apache.org/tentacles/[tentacles documentation], this command generates a report called `archives.html` (in the newly created `orgapacheisis-NNN` directory). This lists all of the top-level binaires, their `LICENSE` and `NOTICE` files and any `LICENSE` and `NOTICE` files of any binaries they may contain.
-
-Validation of the output at this point is all still manual. Things to check for include:
-
-* any binaries that contain no LICENSE and NOTICE files
-* any binaries that contain more than one LICENSE or NOTICE file
-
-In this report, each binary will have three links listed after its name '(licenses, notices, contents)'
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/verifying-releases.adoc
deleted file mode 100644
index 680186e..0000000
--- a/adocs/documentation/src/main/asciidoc/verifying-releases.adoc
+++ /dev/null
@@ -1,146 +0,0 @@
-[[verifying-releases]]
-= Verifying Releases
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-Whenever a committer announces a vote on a release on the link:../support.html[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release. Anyone else can also vote, but only members of the Apache Isis PMC's vote are binding.
-
-This page provides some guidance on what a voter is expected to verify before casting their vote. 
-
-Per this http://www.apache.org/dev/release.html[ASF documentation], the legal requirements for an ASF release are:
-
-* a source zip file + corresponding signature (signed by the release manager, which is in the ASF web of trust and in our KEYS file)
-* all source files have the Apache license (this is ensured by the running of the rat plugin prior to release; you could run it on the unzipped source)
-* all dependencies are appropriately licensed; see the `DEPENDENCIES` file which is automatically generated from the POMs plus the supplemental-models.xml file
-
-Note that the binaries are _not_ an ASF release, they merely exist on the Maven central repo as a convenience. That said, you might also want to verify the release by pulling the binaries from the Maven staging repository. Details of how to do this are also documented below.
-
-
-
-== Prerequisites
-
-To verify the source ZIP files, you will need to have imported the public keys used for signing Apache Isis releases. These can be downloaded from the root of the Apache Isis source tree.
-
-Since the Apache Isis source is mirrored on github.com, you can just use:
-
-[source,bash]
-----
-curl http://www.apache.org/dist/isis/KEYS > /tmp/KEYS
-gpg --import /tmp/KEYS
-----
-
-
-
-
-== Verifying the source release artifacts
-
-
-[NOTE]
-====
-Note: to automate this next stage, there is also a link:/contributors/verifying-releases-script.html[script] available; but read what follows first before using the script.
-====
-
-
-Download both the ZIP and .ASC files from the location specified in the voting email. To verify that the signature is correct, use:
-
-[source,bash]
-----
-gpg --verify isis-x.y.z.zip.asc isis-x.y.z.zip
-----
-
-
-
-
-== Building the source release artifacts
-
-Assuming the ZIP file verifies, it should be unpacked, and then the artifact built from source.
-
-First, delete all Isis artifacts from your local Maven repo:
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-----
-
-
-To build Apache Isis core, first download any dependencies:
-
-[source]
-----
-mvn dependency:go-offline
-----
-
-Check that no Isis artifacts have yet been downloaded, ie there is no `~/.m2/org/repository/org/apache/isis` directory. If there are, it could indicate that the release being verified incorrectly references previous versions of Apache Isis core.
-
-Assuming all is ok, build using the `-o` offline flag:
-
-[source]
-----
-mvn clean install -o
-----
-
-Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
-
-
-
-
-
-== Verifying the binary release artifacts (using the Maven staging repository)
-
-If you wish, you can verify the binary releases by configuring your local Maven install to point to the Maven Maven staging repository (or repositories) and then using them, eg to run the link:../intro/getting-started/simpleapp-archetype.html[simpleapp archetype] and running the resultant app.
-
-Configuring your local Maven install amounts to updating the `~/.m2/settings.xml` file:
-
-[source,xml]
-----
-<profiles>
-    <profile>
-        <id>verify-isis</id>
-        <repositories>
-            <repository>
-                <id>isis-core-staging</id>
-                <name>Isis Core Staging</name>
-                <releases>
-                    <enabled>true</enabled>
-                    <updatePolicy>always</updatePolicy>
-                    <checksumPolicy>warn</checksumPolicy>
-                </releases>
-                <url>http://repository.apache.org/content/repositories/orgapacheisis-10xx</url>
-                <layout>default</layout>
-            </repository>
-            ...
-        </repositories>
-    </profile>
-    ...
-</profiles>
-<activeProfiles>
-    <activeProfile>verify-isis</activeProfile>
-    ...
-</activeProfiles>
-----
-
-where the repository URL is as provided in the VOTE email. If there is more than one repository (as is sometimes the case if multiple components have been released), then repeat the <repository> section for each.
-
-Once the vote has completed, the staging repositories will be removed and so you should deactive the profile (comment out the `&lt;activeProfile&gt;` element). If you forget to deactive the profile, there should be no adverse effects; Maven will just spend unnecessary cycles attempting to hit a non-existent repo.
-
-
-
-
-
-== Using the Creadur Tools
-
-The http://creadur.apache.org[Apache Creadur] project exists to provide a set of tools to ensure compliance with Apache's licensing standards. The main release auditing tool, http://creadur.apache.org/rat[Apache RAT], is used in the preparation of the release (as documented link:release-process.html[here]). Creadur's remaining tools are to support the verification process.
-
-At the time of writing, these additional tools are quite young and haven't been formally released; so to use them will take a little bit of work. See link:verifying-releases-using-creadur-tools.html[here] for more details.
-
-
-
-
-== Casting a Vote
-
-When you have made the above checks (and any other checks you think may be relevant), cast your vote by replying to the email thread on the mailing list. If you are casting `-1`, please provide details of the problem(s) you have found.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/versioning-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/versioning-policy.adoc b/adocs/documentation/src/main/asciidoc/versioning-policy.adoc
deleted file mode 100644
index 33bca0f..0000000
--- a/adocs/documentation/src/main/asciidoc/versioning-policy.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[versioning-policy]]
-= Versioning Policy
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-
-## Semantic Versioning
-
-Starting from v1.0.0, Apache Isis has adopted link:http://semver.org[semantic versioning] for its versioning policy.
-
-Version numbers are in the form `x.y.z`:
-
-- x is bumped up whenever there a breaking API change
-- y is bumped up whenever there is a new feature that does not break API
-- z is bumped up for minor bug fixes.
-
-This scheme would be adopted for both core and components.  
-
-
-
-
-
-
-## Version numbers may not be used
-
-Version ranges may not be used.  If necessary, end-users can use `<dependencyManagement` elements to have combine components built against different versions of core.
-
-That said, this can introduce instability and so generally we recommend that end-users configure the `maven-enforcer-plugin` and its link:http://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html[DependencyConvergence] rule.  This will help avoid "jar hell" (components having conflicting dependencies of core).
-
-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.

[06/10] isis git commit: ISIS-1133: pulling together the contributors guide.

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
new file mode 100644
index 0000000..819f6f6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_stop-scaffolding-start-coding.adoc
@@ -0,0 +1,683 @@
+[[_ug_tutorials_stop-scaffolding-start-coding]]
+= Stop scaffolding, start coding
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This is a half-day tutorial on developing domain-driven apps using Apache Isis.  Actually, you could probably spend a full day working through this tutorial if you wanted to, so pick and choose the bits that look interesting.
+
+There's a bit of overlap with the xref:ug.adoc#_ug_tutorials_pet-clinic[Pet Clinic] tutorial initially, but it then sets off on its own.
+
+
+
+== Prerequisites
+
+You'll need:
+
+* Java 7 JDK
+* http://maven.apache.org/[Maven] 3.2.x
+* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
+
+
+
+== Run the archetype
+
+Run the simpleapp archetype to build an empty Isis application:
+
+[source,bash]
+----
+mvn archetype:generate  \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=simpleapp-archetype \
+    -D archetypeVersion=1.8.0 \
+    -D groupId=com.mycompany \
+    -D artifactId=myapp \
+    -D version=1.0-SNAPSHOT \
+    -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+    -B
+----
+
+
+
+
+== Build and run
+
+Start off by building the app from the command line:
+
+[source,bash]
+----
+cd myapp
+mvn clean install
+----
+
+Once that's built then run using:
+
+[source,bash]
+----
+mvn antrun:run -P self-host
+----
+
+A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
+
+Alternatively, you can run using the mvn-jetty-plugin:
+
+[source,bash]
+----
+mvn jetty:run
+----
+
+This will accomplish the same thing, though the webapp is mounted at a slightly different URL
+
+
+
+
+== Using the app
+
+Navigate to the Wicket UI (eg link:http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
+
+Once at the home page:
+
+* install fixtures
+* list all objects
+* create a new object
+* list all objects
+
+Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
+
+
+
+
+== Dev environment
+
+Set up xref:cg.adoc#_cg_ide[an IDE] and import the project to be able to run and debug the app.
+
+Then set up a launch configuration and check that you can:
+
+* Run the app from within the IDE
+* Run the app in debug mode
+* Run with different deploymentTypes; note whether prototype actions (those annotated xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action(restrictTo=PROTOTYPING`]) are available or not:
+* `--type SERVER_PROTOTYPE`
+* `--type SERVER`
+
+
+
+
+== Explore codebase
+
+Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
+
+* `myapp` : parent module
+* `myapp-dom`: domain objects module
+* entity: `dom.simple.SimpleObject`
+* repository: `dom.simple.SimpleObjects`
+* `myapp-fixture`: fixtures module
+* fixture script:`fixture.simple.SimpleObjectsFixture`
+* `myapp-integtests`: integration tests module
+* `myapp-webapp`: webapp module
+* (builds the WAR file)
+
+
+
+
+== Testing
+
+Testing is of course massively important, and Apache Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
+
+* `myapp-dom` unit tests
+* run
+* inspect, eg
+ - `SimpleObjectTest`
+* `myapp-integtests` integration tests
+* run
+* inspect, eg:
+** `integration.tests.smoke.SimpleObjectsTest`
+** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
+* generated report, eg
+ - `myapp/integtests/target/cucumber-html-report/index.html`
+** change test in IDE, re-run (in Maven)
+
+If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
+
+
+
+
+== Prototyping
+
+Although testing is important, in this tutorial we want to concentrate on how to write features and to iterate quickly. So for now, exclude the `integtests` module. Later on in the tutorial we'll add the tests back in so you can learn how to write automated tests for the features of your app.
+
+In the parent `pom.xml`:
+
+[source,xml]
+----
+<modules>
+    <module>dom</module>
+    <module>fixture</module>
+    <module>integtests</module>
+    <module>webapp</module>
+</modules>
+----
+
+change to:
+
+[source,xml]
+----
+<modules>
+    <module>dom</module>
+    <module>fixture</module>
+    <!--
+    <module>integtests</module>
+    -->
+    <module>webapp</module>
+</modules>
+----
+
+
+
+
+== Build a domain app
+
+The remainder of the tutorial provides guidance on building a domain application. We don't mandate any particular design, but we suggest one with no more than 3 to 6 domain entities in the first instance. If you're stuck for ideas, then how about:
+
+* a todo app (``ToDoItem``s)
+* a pet clinic (`Pet`, `Owner`, `PetSpecies`, `Visit`)
+* a library (`Book`, `Title`, `LibraryMember`, `Loan`, `Reservation`)
+* a holiday cottage rental system
+* a scrum/kanban system (inspired by Trello)
+* a meeting planner (inspired by Doodle)
+* (the domain model for) a CI server (inspired by Travis/Jenkins)
+* a shipping system (inspired by the example in the DDD "blue" book)
+* a system for ordering coffee (inspired by Restbucks, the example in "Rest in Practice" book)
+
+Hopefully one of those ideas appeals or sparks an idea for something of your own.
+
+
+
+
+== Domain entity
+
+Most domain objects in Apache Isis applications are persistent entities. In the simpleapp archetype the `SimpleObject` is an example. We can start developing our app by refactoring that class:
+
+* rename the `SimpleObject` class
+** eg rename to `Pet`
+* if required, rename the `SimpleObject` class' `name` property
+** for `Pet`, can leave `name` property as is
+* specify a xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[title]
+* specify an xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[icon]
+* make the entity bookmarkable by adding the xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`] attribute.
+* confirm is available from bookmark panel (top-left of Wicket UI)
+
+
+
+
+== Domain service
+
+Domain services often act as factories or repositories to entities; more generally can be used to "bridge across" to other domains/bounded contexts. Most are application-scoped, but they can also be request-scoped if required.
+
+In the simpleapp archetype the `SimpleObjects` service is a factory/repository for the original `SimpleObject` entity. For our app it therefore makes sense to refactor that class into our own first service:
+
+* rename the `SimpleObjects` class
+** eg rename to `Pets`
+* review `create` action (acting as a factory)
+** as per the docs describing xref:ug.adoc#_ug_how-tos_crud[how to create or delete objects]
+* rename if you wish
+** eg `newPet(...)` or `addPet(...)`
+* review `listAll` action (acting as a repository)
+* as per the docs describing xref:ug.adoc#_ug_how-tos_crud[how to write a custom repository]
+* note the annotations on the corresponding domain class (originally called `SimpleObject`, though renamed by now, eg to `Pet`)
+* rename if you wish
+** eg `listPets()`
+* note the xref:rg.adoc#_rg_annotations_manpage-DomainService[`@DomainService`] annotation
+* optional: add an action to a return subset of objects
+** use the JDO `@Query` annotation
+** see for example the Isisaddons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF), see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L93[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItems.java#L63[here]
+
+
+
+
+== Fixture scripts
+
+Fixture scripts are used to setup the app into a known state. They are great for demo's and as a time-saver when implementing a feature, and they can also be reused in automated integration tests. We usually also have a fixture script to zap all the (non-reference) data (or some logical subset of the data)
+
+* rename the `SimpleObjectsTearDownFixture` class
+* and update to delete from the appropriate underlying database table(s)
+* use the injected xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] domain service.
+* refactor/rename the fixture script classes that create instances your entity:
+* `RecreateSimpleObjects`, which sets up a set of objects for a given scenario
+* `SimpleObjectCreate` which creates a single object
+* note that domain services can be injected into these fixture scripts
+
+
+
+
+== Actions
+
+Most business functionality is implemented using actions� basically a `public` method accepting domain classes and primitives as its parameter types. The action can return a domain entity, or a collection of entities, or a primitive/String/value, or void. If a domain entity is returned then that object is rendered immediately; if a collection is returned then the Wicket viewer renders a table. Such collections are sometimes called "standalone" collections.
+
+* write an action to update the domain property (originally called `SimpleObject#name`, though renamed by now)
+* use the xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`@ParameterLayout(named=...)`] annotation to specify the name of action parameters
+* use the xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action(semanticsOf=...)`]  annotation to indicate the semantics of the action (safe/query-only, idempotent or non-idempotent)
+* annotate safe action as bookmarkable using xref:rg.adoc#_rg_annotations_manpage-ActionLayout_bookmarking[`@ActionLayout(bookmarking=...)`]
+* confirm is available from bookmark panel (top-left of Wicket UI)
+* optional: add an action to clone an object
+
+
+
+
+== REST API
+
+As well as exposing the Wicket viewer, Isis also exposes a REST API (an implementation of the http://restfulobjects.org[Restful Objects spec]). All of the functionality of the domain object model is available through this REST API.
+
+* add Chrome extensions
+* install https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Postman]
+* install https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en[JSON-View]
+* browse to Wicket viewer, install fixtures
+* browse to the http://localhost:8080/restful[http://localhost:8080/restful] API
+* invoke the service to list all objects
+* services
+* actions
+* invoke (invoking 0-arg actions is easy; the Restful Objects spec defines how to invoke N-arg actions)
+
+
+
+
+== Specify Action semantics
+
+The semantics of an action (whether it is safe/query only, whether it is idempotent, whether it is neither) can be specified for each action; if not specified then Isis assumes non-idempotent. In the Wicket viewer this matters in that only query-only actions can be bookmarked or used as contributed properties/collections. In the RESTful viewer this matters in that it determines the HTTP verb (GET, PUT or POST) that is used to invoke the action.
+
+* experiment changing xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action(semantics=...)`] on actions
+* note the HTTP methods exposed in the REST API change
+* note whether the non-safe actions are bookmarkable (assuming that it has been annotated with `@ActionLayout(bookmarking=...)`, that is).
+
+
+
+
+== Value properties
+
+Domain entities have state: either values (primitives, strings) or references to other entities. In this section we explore adding some value properties
+
+* add some xref:ug.adoc#_ug_how-tos_class-structure_properties[value properties]; also:
+* for string properties
+** use the xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_multiLine[`@Property(multiLine=...)`] annotation to render a text area instead of a text box
+** use the xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
+** use joda date/time properties, bigdecimals and blob/clob properties
+* use the xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Column(allowsNull=...)`] annotation specify whether a property is optional or mandatory
+* use enums for properties (eg as used in the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp], see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L207[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L266[here])
+* update the corresponding domain service for creating new instances
+* for all non-optional properties will either need to prompt for a value, or calculate some suitable default
+* change the implementation of title, if need be
+* revisit the title, consider whether to use the xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`] annotation
+** rather than the xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] `title()` method
+* order the properties using the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
+** see also the docs on xref:rg.adoc#_rg_object-layout_static[static layouts]
+* use the xref:rg.adoc#_rg_annotations_manpage-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
+** do the same for parameters using xref:rg.adoc#_rg_annotations_manpage-ParameterLayout[`@ParameterLayout`]
+
+
+
+
+== Reference properties
+
+Domain entities can also reference other domain entities. These references may be either scalar (single-valued) or vector (multi-valued). In this section we focus on scalar reference properties.
+
+* add some xref:ug.adoc#_ug_how-tos_class-structure_properties[reference properties]
+* update the corresponding domain service (for creation actoin)
+* use different techniques to obtain references (shown in drop-down list box)
+** use the xref:rg.adoc#_rg_annotations_manpage-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
+** use a xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`] supporting method
+*** on a property
+*** on an action parameter
+** use a xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method
+*** on a property
+*** on an action parameter
+
+
+
+
+== Usability: Defaults
+
+Quick detour: often we want to set up defaults to go with choices. Sensible defaults for action parameters can really improve the usability of the app.
+
+* Add xref:ug.adoc#_ug_how-tos_drop-downs-and-defaults[defaults] for action parameters
+
+
+
+
+== Collections
+
+Returning back to references, Isis also supports vector (multi-valued) references to another object instances� in other words collections. We sometimes called these "parented" collections (to distinguish from a "standalone" collection as returned from an action)
+
+* Ensure that all domain classes implement `java.lang.Comparable`
+** use the xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
+*** you can also `equals()`, `hashCode()`, `toString()`
+* Add a xref:ug.adoc#_ug_how-tos_class-structure_collections[collection] to one of the entities
+** Use `SortedSet` as the class
+** Use the xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
+* optional: use the xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
+
+
+
+
+
+== Actions and Collections
+
+The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
+
+* Add domain actions to add/remove from the collection
+* to create objects, xref:ug.adoc#_ug_how-tos_class-structure_inject-services[inject] associated domain service
+** generally we recommend using the xref:rg.adoc#_rg_annotations_manpage-Inject[`@Inject`] annotation with either private or default visibility
+* the service itself should use xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
+* use the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
+
+
+
+
+== CSS UI Hints
+
+CSS classes can be associated with any class member (property, collection, action). But for actions in particular:
+
+* the bootstrap "btn" CSS classes can be used using the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout(cssClass=...)`] annotation
+
+*  the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
+
+It's also possible to use Font Awesome icons for the xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[domain object icon].
+
+So:
+- for some of the actions of your domain services or entities, annotate using `@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`
+
+
+
+
+== Dynamic Layout
+
+Up to this point we've been using annotations (`@MemberOrder`, `@MemberGroupLayout`, `@Named`, `@PropertyLayout`, `@ParameterLayout`, `@ActionLayout` and so on) for UI hints. However, the feedback loop is not good: it requires us stopping the app, editing the code, recompiling and running again. So instead, all these UI hints (and more) can be specified dynamically, using a corresponding `.layout.json` file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run&gt;Reload Changed Classes):
+
+* Delete the various hint annotations and instead specify layout hints using a xref:rg.adoc#_rg_object-layout_dynamic[.layout.json] file.
+
+
+
+
+== Business rules
+
+Apache Isis excels for domains where there are complex business rules to enforce. The UI tries not to constrain the user from navigating around freely, however the domain objects nevertheless ensure that they cannot change into an invalid state. Such rules can be enforced either declaratively (using annotations) or imperatively (using code). The objects can do this in one of three ways:
+
+* visibility: preventing the user from even seeing a property/collection/action
+* usability: allowing the user to view a property/collection/action but not allowing the user to change it
+* validity: allowing the user to modify the property/invoke the action, but validating that the new value/action arguments are correct before hand.
+
+Or, more pithily: "see it, use it, do it"
+
+
+=== See it!
+
+* Use the xref:rg.adoc#_rg_annotations_manpage-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
+** likewise xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[`@Collection(hidden=...)`] for collections
+** the xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`]  annotation can also be used and in many cases is to be preferred; the difference is that the latter means the member is not part of the Apache Isis metamodel.
+* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
+
+
+=== Use it!
+
+* Use the xref:rg.adoc#_rg_annotations_manpage-Property_editing[`Property(editing=...)`] annotation to make property read-only
+** likewise xref:rg.adoc#_rg_annotations_manpage-Collection_editing[`@Collection(editing=...)`] for collections
+** alternatively, use xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`@DomainObject(editing=...)`] to disable editing for all properties/collections
+* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
+
+
+=== Do it!
+
+* use the xref:rg.adoc#_rg_annotations_manpage-Property_regexPattern[`@Property(regexPattern=...)`] annotation to specify a regex pattern for properties, and use xref:rg.adoc#_rg_annotations_manpage-Parameter_regexPattern[`@Parameter(regexPattern=...)`] for parameters
+* use the xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a maxmum number of characters, and xref:rg.adoc#_rg_annotations_manpage-Parameter_maxLength[`@Parameter(maxLength=...)`] for parameters
+* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] supporting method on properties or action parameter
+* optional: for any data type:
+** use the xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
+
+
+
+
+== Home page
+
+The Wicket UI will automatically invoke the "home page" action, if available. This is a no-arg action of one of the domain services, that can return either an object (eg representing the current user) or a standalone action.
+
+* Add the xref:rg.adoc#_rg_annotations_manpage-HomePage[`@HomePage`] annotation to one (no more) of the domain services' no-arg actions
+
+
+
+
+== Clock Service
+
+To ensure testability, there should be no dependencies on system time, for example usage of `LocalDate.now()`. Instead the domain objects should delegate to the provided `ClockService`.
+
+* remove any dependencies on system time (eg defaults for date/time action parameters)
+* inject xref:rg.adoc#_rg_services-api_manpage-ClockService[`ClockService`]
+* call `ClockService.now()` etc where required.
+
+
+
+
+== Using Contributions
+
+One of Apache Isis' most powerful features is the ability for the UI to combine functionality from domain services into the representation of an entity. The effect is similar to traits or mix-ins in other languages, however the "mixing in" is done at runtime, within the Apache Isis metamodel. In Apache Isis' terminology, we say that the domain service action is contributed to the entity.
+
+Any action of a domain service that has a domain entity type as one of its parameter types will (by default) be contributed. If the service action takes more than one argument, or does not have safe semantics, then it will be contributed as an entity action. If the service action has precisely one parameter type (that of the entity) and has safe semantics then it will be contributed either as a collection or as a property (dependent on whether it returns a collection of a scalar).
+
+Why are contributions so useful? Because the service action will match not on the entity type, but also on any of the entity's supertypes (all the way up to `java.lang.Object`). That means that you can apply the http://en.wikipedia.org/wiki/Dependency_inversion_principle[dependency inversion principle] to ensure that the modules of your application have acyclic dependencies; but in the UI it can still appear as if there are bidirectional dependencies between those modules. The lack of bidirectional dependencies can help save your app degrading into a http://en.wikipedia.org/wiki/Big_ball_of_mud[big ball of mud].
+
+Finally, note that the layout of contributed actions/collections/properties can be specified using the `.layout.json` file (and it is highly recommended that you do so).
+
+=== Contributed Actions
+
+* Write a new domain service
+** by convention, called "XxxContributions"
+** annotate with xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)`]
+*** indicates that all of the service's actions should _not_ be included in the main application menu bar
+*** should be rendered "as if" an action of the entity
+* Write an action accepting &gt;1 args:
+** one being a domain entity
+** other being a primitive or String
+
+=== Contributed Collections
+
+* Write a new domain service (or update the one previously)
+* Write a query-only action accepting exactly 1 arg (a domain entity)
+* returning a collection, list or set
+* For this action:
+** add the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
+** should be rendered in the UI "as if" a collection of the entity
+* use `.layout.json` to position as required
+
+
+=== Contributed Properties
+
+* As for contributed collections, write a new domain service with a query-only action accepting exactly 1 arg (a domain entity); except:
+** returning a scalar value rather than a collection
+* For this action:
+** add the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
+* should be rendered in the UI "as if" a property of the entity
+* use `.layout.json` to position as required
+
+
+
+== Using the Event Bus
+
+Another way in which Apache Isis helps you keep your application nicely modularized is through its event bus. Each action invocation, or property modification, can be used to generate a succession of events that allows subscribers to veto the interaction (the see it/use it/do it rules) or, if the action is allowed, to perform work prior to the execution of the action or after the execution of the action.
+
+Under the covers Apache Isis uses the https://code.google.com/p/guava-libraries/wiki/EventBusExplained[Guava event bus] and subscribers (always domain services) subscribe by writing methods annotated with `@com.google.common.eventbus.Subscribe` annotation.
+
+By default the events generated are `ActionDomainEvent.Default` (for actions) and `PropertyDomainEvent.Default` (for properties). Subclasses of these can be specified using the xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action(domainEvent=...)`] or xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`Property(domainEvent=...)`] for properties.
+
+
+Using the guidance in the docs for the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]:
+
+* write a domain service subscriber to subscribe to events
+* use the domain service to perform log events
+* use the domain service to veto actions (hide/disable or validate)
+
+
+
+== Bulk actions
+
+Bulk actions are actions that can be invoked on a collection of actions, that is on collections returned by invoking an action. Actions are specified as being bulk actions using the xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@action(invokeOn=OBJECT_AND_COLLECTION)`] annotation.
+
+[NOTE]
+====
+Note that currently (1.8.0) only no-arg actions can be specified as bulk actions.
+====
+
+Thus:
+* Write a no-arg action for your domain entity, annotate with `@Action(invokeOn=...)`
+* Inject the xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`ActionInteractionContext`] (request-scoped) service
+* Use the `ActionInteractionContext` service to determine whether the action was invoked in bulk or as a regular action.
+* return null if invoked on a collection; the Wicket viewer will go back to the original collection
+** (if return non-null, then Wicket viewer will navigate to the object of the last invocation� generally not what is required)
+
+The similar xref:rg.adoc#_rg_services-api_manpage-Scratchpad[`Scratchpad`] (request-scoped) domain service is a good way to share information between bulk action invocations:
+
+* Inject the `Scratchpad` domain service
+* for each action, store state (eg a running total)
+* in the last invoked bulk action, perform some aggregate processing (eg calculate the average) and return
+
+
+
+
+== Performance tuning
+
+The xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`QueryResultsCache`] (request-scoped) domain service allows arbitrary objects to be cached for the duration of a request.
+
+This can be helpful for "naive" code which would normally make the same query within a loop.
+
+* optional: inject the `QueryResultsCache` service, invoke queries "through" the cache API
+* remember that the service is request-scoped, so it only really makes sense to use this service for code that invokes queries within a loop
+
+
+
+
+== Extending the Wicket UI
+
+Each element in the Wicket viewer (entity form, properties, collections, action button etc) is a component, each created by a internal API (`ComponentFactory`, described xref:ug.adoc#_ug_extending_wicket-viewer[here]). For collections there can be multiple views, and the Wicket viewer provides a view selector drop down (top right of each collection panel).
+
+Moreover, we can add additional views. In this section we'll explore some of these, already provided through http://www.isisaddons.org/[Isis addons] (not ASF).
+
+=== Excel download
+
+The https://github.com/isisaddons/isis-wicket-excel[Excel download add-on] allows the collection to be downloaded as an Excel spreadsheet (`.xlsx`).
+
+* Use the instructions on the add-on module's README to add in the excel download module (ie: update the POM).
+
+=== Fullcalendar2
+
+The https://github.com/isisaddons/isis-wicket-fullcalendar2[Fullcalendar2 download add-on] allows entities to be rendered in a full-page calendar.
+
+* Use the instructions on the add-on module's README to add in the fullcalendar2 module (ie: update the POM).
+* on one of your entities, implement either the `CalendarEventable` interface or the (more complex) `Calendarable` interface.
+* update fixture scripts to populate any new properties
+* when the app is run, a collection of the entities should be shown within a calendar view
+
+=== gmap3
+
+The https://github.com/isisaddons/isis-wicket-gmap3[Gmap3 download add-on] allows entities that implement certain APIs to be rendered in a full-page gmap3.
+
+* Use the instructions on the add-on module's README to add in the gmap3 module (ie: update the POM).
+* on one of your entities, implement the `Locatable` interface
+* update fixture scripts to populate any new properties
+* when the app is run, a collection of the entities should be shown within a map view
+
+
+
+
+== Add-on modules (optional)
+
+In addition to providing Wicket viewer extensions, http://www.isisaddons.org/[Isis addons] also has a large number of modules. These address such cross-cutting concerns as security, command (profiling), auditing and publishing.
+
+* (optional): follow the https://github.com/isisaddons/isis-module-security[security module] README or http://youtu.be/bj8735nBRR4[screencast]
+* (optional): follow the https://github.com/isisaddons/isis-module-command[command module] README or http://youtu.be/g01tK58MxJ8[screencast]
+* (optional): follow the https://github.com/isisaddons/isis-module-audit[auditing module] README or (the same) http://youtu.be/g01tK58MxJ8[screencast]
+
+
+
+
+== View models
+
+In most cases users can accomplish the business operations they need by invoking actions directly on domain entities. For some high-volume or specialized uses cases, though, there may be a requirement to bring together data or functionality that spans several entities.
+
+Also, if using Apache Isis' REST API then the REST client may be a native application (on a smartphone or tablet, say) that is deployed by a third party. In these cases exposing the entities directly would be inadvisable because a refactoring of the domain entity would change the REST API and probably break that REST client.
+
+To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
+
+* build a view model summarizing the state of the app (a "dashboard")
+* write a new `@HomePage` domain service action returning this dashboard viewmodel (and remove the `@HomePage` annotation from any other domain service if present)
+
+
+
+
+== Testing
+
+Up to this point we've been introducing the features of Isis and building out our domain application, but with little regard to testing. Time to fix that.
+
+
+=== Unit testing
+
+Unit testing domain entities and domain services is easy; just use JUnit and mocking libraries to mock out interactions with domain services.
+
+https://code.google.com/p/mockito/[Mockito] seems to be the current favourite among Java developers for mocking libraries, but if you use JMock then you'll find we provide a `JUnitRuleMockery2` class and a number of other utility classes, documented xref:ug.adoc#_ug_testing_unit-test-support[here].
+
+* write some unit tests (adapt from the unit tests in the `myapp-dom` Maven module).
+
+
+
+=== Integration testing
+
+Although unit tests are easy to write and fast to execute, integration tests are more valuable: they test interactions of the system from the outside-in, simulating the way in which the end-users use the application.
+
+Earlier on in the tutorial we commented out the `myapp-integtests` module. Let's commented it back in. In the parent `pom.xml`:
+
+[source,xml]
+----
+<modules>
+    <module>dom</module>
+    <module>fixture</module>
+    <!--
+    <module>integtests</module>
+    -->
+    <module>webapp</module>
+</modules>
+----
+
+change back to:
+
+[source,xml]
+----
+<modules>
+    <module>dom</module>
+    <module>fixture</module>
+    <module>integtests</module>
+    <module>webapp</module>
+</modules>
+----
+
+There will probably be some compile issues to fix up once you've done this; comment out all code that doesn't compile.
+
+Isis has great support for writing xref:ug.adoc#_ug_testing_integ-test-support[integration tests]; well-written integration tests should leverage fixture scripts and use the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`@WrapperFactory`] domain service.
+
+* use the tests from the original archetype and the documentation on the website to develop integration tests for your app's functionality.
+
+
+
+
+== Customising the REST API
+
+The REST API generated by Apache Isis conforms to the Restful Objects specification. Apache Isis 1.8.0 provides experimental support to allow the representations to be customized.
+
+* as per xref:ug.adoc#_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
++
+[source,ini]
+----
+isis.viewer.restfulobjects.objectPropertyValuesOnly=true
+----
+
+
+
+
+== Configuring to use an external database
+
+If you have an external database available, then update the `pom.xml` for the classpath and update the JDBC properties in `WEB-INF\persistor.properties` to point to your database.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc
index 8c92324..ab84c1b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc
@@ -26,7 +26,7 @@ Apache Isis is a Java based framework, so in terms of prerequisites, you'll need
 * Java 7 or 8 JDK
 * link:http://maven.apache.org[Apache Maven] 3.0.5 or later
 
-You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the link:dg.adoc[Developers' Guide] we have detailed setup instructions for using these two IDEs.  If you're a NetBeans user you should have no problems as it too has strong support for Maven.
+You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:cg.adoc#_cg_ide[Contributors' Guide] we have detailed setup instructions for using these two IDEs.  If you're a NetBeans user you should have no problems as it too has strong support for Maven.
 
 When building and running within an IDE, you'll also need to configure the Datanucleus enhancer.  This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required. It should be just as straightforward for NetBeans too.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc
index f3f8be1..5e13ea5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc
@@ -103,5 +103,5 @@ Again, the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archet
 ====
 If running on Windows, then there's a good chance you'll hit the http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath[maximum path length limit].   In this case the `persistence.xml` file is mandatory rather than optional.
 
-This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven.  More information can be found link:dg.adoc#_dg_eclipse[here].
+This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven.  More information can be found xref:cg.adoc#_cg_ide_eclipse[here].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
index 29514d4..00378ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
@@ -87,7 +87,7 @@ where `myapp` is the `artifactId` entered above.
 
 == Running the App
 
-The `simpleapp` archetype generates a single WAR file, configured to run both the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer].  The archetype also configures the [JDO Objectstore](../../components/objectstores/jdo/about.html) to use an in-memory HSQLDB connection.
+The `simpleapp` archetype generates a single WAR file, configured to run both the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer].  The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
 
 Once you've built the app, you can run the WAR in a variety of ways.
 
@@ -123,7 +123,7 @@ cd webapp
 mvn jetty:run
 ----
 
-If you use `mvn jetty:run`, then the context path changes; check the console output (eg link:[http://localhost:8080/myapp-webapp] [http://localhost:8080/myapp-webapp]).
+If you use `mvn jetty:run`, then the context path changes; check the console output (eg link:http://localhost:8080/myapp-webapp [http://localhost:8080/myapp-webapp]).
 
 
 You can also provide a system property to change the port:
@@ -143,7 +143,7 @@ You can also take the built WAR file and deploy it into a standalone servlet con
 
 === From within the IDE
 
-Most of the time, though, you'll probably want to run the app from within your IDE.  The mechanics of doing this will vary by IDE; see the link:dg.adoc[Developers' Guide] for details of setting up Eclipse or IntelliJ IDEA.  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
+Most of the time, though, you'll probably want to run the app from within your IDE.  The mechanics of doing this will vary by IDE; see the xref:cg.adoc#_cg_ide[Contributors' Guide] for details of setting up Eclipse or IntelliJ IDEA.  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
 
 Here's what the setup looks like in IntelliJ IDEA:
 
@@ -252,49 +252,50 @@ which when invoked (with an HTTP GET) will return a representation of the domain
 image::{_imagesdir}getting-started/using-simple-app/250-list-all-results.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/250-list-all-results.png"]
 
 
+To log in, use `sven/pass`.
 
 
 
 
 
+== Modifying the App
 
+Once you are familiar with the generated app, you'll want to start modifying it.  There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main link:../documentation.html[documentation] page first).
 
+If you use Eclipse or IntelliJ IDEA, do also install the xref:cg.adoc#_cg_ide-templates[IDE templates]; these will help you follow the Apache Isis naming conventions.
 
 
 
 
 
+== App Structure
 
+As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
 
 
 
-To log in, use `sven/pass`.
-
-
-
-
-
-== Modifying the App
-
-Once you are familiar with the generated app, you'll want to start modifying it.  There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main [documentation](../../documentation.html) page first).
+[cols="1,3", options="header"]
+|===
+| Module
+| Description
 
-If you use Eclipse or IntelliJ IDEA, do also install the [Eclipse templates](../resources/editor-templates.html); these will help you follow the Apache Isis naming conventions.
+|`myapp`
+|The parent (aggregator) module
 
+|`myapp-dom`
+|The domain object model, consisting of `SimpleObject` and `SimpleObjects` (repository) domain service.
 
+|`myapp-fixture`
+|Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
 
+|`myapp-integtests`
+|End-to-end xref:ug.adoc#_ug_testing_integ-test-support[integration tests] that exercise from the UI through to the database
 
+|`myapp-webapp`
+|Run as a webapp (from `web.xml`) hosting the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and/or the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]
 
-== App Structure
+|===
 
-As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
 
-<table class="table table-striped table-bordered table-condensed">
-<tr><th>Module</th><th>Description</th></tr>
-<tr><td>myapp</td><td>The parent (aggregator) module</td></tr>
-<tr><td>myapp-dom</td><td>The domain object model, consisting of <tt>SimpleObject</tt> and <tt>SimpleObjects</tt> (repository) domain service.</td></tr>
-<tr><td>myapp-fixture</td><td>Domain object fixtures used for initializing the system when being demo'ed or for unit testing.</td></tr>
-<tr><td>myapp-integtests</td><td>End-to-end <a href="../../core/integtestsupport.html">integration tests</a>, that exercise from the UI through to the database</td></tr>
-<tr><td>myapp-webapp</td><td>Run as a webapp (from <tt>web.xml</tt>) using either the Wicket viewer or the Restful Objects viewer</td></tr>
-</table>
 
-If you run into issues, please don't hesitate to ask for help on the [users mailing list](../../support.html).
+If you run into issues, please don't hesitate to ask for help on the link:http://isis.apache.org/help.html[users mailing list].

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_isis-maven-plugin.adoc
deleted file mode 100644
index 64f9898..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_isis-maven-plugin.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_isis-maven-plugin]]
-= Apache Isis Maven Plugin
-:Notice: 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.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-NOTE: TODO
-

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc
index eeca068..b3159dd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc
@@ -68,7 +68,7 @@ This contract test automatically checks that bidirectional 1:m or 1:1 associatio
 
 [TIP]
 ====
-(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ug.adoc#_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here].  Also check out the  link:dg.adoc[IDE templates] for further guidance.
+(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ug.adoc#_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here].  Also check out the xref:cg.adoc#_cg_ide-templates[IDE templates] for further guidance.
 ====
 
 For example, suppose that `ParentDomainObject` and `ChildDomainObject` have a 1:m relationship (`ParentDomainObject#children` / `ChildDomainObject#parent`), and also `PeerDomainObject` has a 1:1 relationship with itself (`PeerDomainObject#next` / `PeerDomainObject#previous`).

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials.adoc
deleted file mode 100644
index a4045ce..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_tutorials]]
-= Tutorials
-:Notice: 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.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-This chapter contains a couple of tutorials for you to follow.
-
-* the "petclinic" tutorial takes you step-by-step through building a simple application of just three classes.  There are example solutions in the github repo in case you get lost.
-
-* the "stop scaffolding, start coding" tutorial is taken from a conference workshop.  It has less hand-holding, but lists out the steps for you to follow.  It's a good cookbook to follow when you're readng to take things further.
-
-Have fun!
-
-include::_ug_tutorials_pet-clinic.adoc[leveloffset=+1]
-include::_ug_tutorials_stop-scaffolding-start-coding.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_pet-clinic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_pet-clinic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_pet-clinic.adoc
deleted file mode 100644
index 7615e08..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_pet-clinic.adoc
+++ /dev/null
@@ -1,557 +0,0 @@
-[[_ug_tutorials_pet-clinic]]
-= Pet Clinic
-:Notice: 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.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-It consists of just three domain classes (http://yuml.me/edit/3db2078c[http://yuml.me/3db2078c]):
-
-image::{_imagesdir}tutorials/pet-clinic/domain-model.png[link="{_imagesdir}tutorials/pet-clinic/domain-model.png"]
-
-
-This supports the following use cases:
-
-* register a Pet
-* register an Owner
-* maintain a Pet's details
-* check in a Pet to visit the clinic
-* enter a diagnosis
-
-check out a Pet to visit the clinic
-
-Either follow along or check out the tags from the corresponding https://github.com/danhaywood/isis-app-petclinic[github repo].
-
-== Prerequisites
-
-You'll need:
-
-* Java 7 JDK
-* http://maven.apache.org/[Maven] 3.2.x
-* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
-
-
-
-
-== Run the archetype
-
-Throughout this tutorial you can, if you wish, just checkout from the github repo wherever you see a "git checkout" note:
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/249abe476797438d83faa12ff88365da2c362451
-----
-
-====
-
-[NOTE]
-====
-This tutorial was developed against Apache Isis 1.8.0-SNAPSHOT.  Since then 1.8.0 has been released, so simply replace "1.8.0-SNAPSHOT" for "1.8.0" wherever it appears in the `pom.xml` files.
-====
-
-
-Run the simpleapp archetype to build an empty Isis application:
-
-
-[source,bash]
-----
-mvn archetype:generate  \
-    -D archetypeGroupId=org.apache.isis.archetype \
-    -D archetypeArtifactId=simpleapp-archetype \
-    -D archetypeVersion=1.8.0 \
-    -D groupId=com.mycompany \
-    -D artifactId=petclinic \
-    -D version=1.0-SNAPSHOT \
-    -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
-    -B
-----
-
-This will generate the app in a `petclinic` directory. Move the contents back:
-
-[source,bash]
-----
-mv petclinic/* .
-rmdir petclinic
-----
-
-
-
-
-== Build and run
-
-Start off by building the app from the command line:
-
-[source,bash]
-----
-mvn clean install
-----
-
-Once that's built then run using:
-
-[source,bash]
-----
-mvn antrun:run -P self-host
-----
-
-A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
-
-Alternatively, you can run using the mvn-jetty-plugin:
-
-[source,bash]
-----
-mvn jetty:run
-----
-
-This will accomplish the same thing, though the webapp is mounted at a slightly different URL
-
-
-
-
-== Using the app
-
-Navigate to the Wicket UI (eg http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
-
-image::{_imagesdir}tutorials/pet-clinic/010-01-login-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-01-login-page.png"]
-
-
-
-The home page should be shown:
-
-image::{_imagesdir}tutorials/pet-clinic/010-02-home-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-02-home-page.png"]
-
-
-
-Install the fixtures (example test data) using the `Prototyping` menu:
-
-image::{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png"]
-
-
-
-List all objects using the `Simple Objects` menu:
-
-image::{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png"]
-
-
-To return the objects created:
-
-image::{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png"]
-
-
-
-Experiment some more, to:
-
-* create a new object
-* list all objects
-
-Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
-
-
-
-
-== Dev environment
-
-Set up link:dg.adoc[an IDE] and import the project to be able to run and debug the app.
-
-Then set up a launch configuration so that you can run the app from within the IDE. To save having to run the fixtures
-every time, specify the following system properties:
-
-[source,bash]
-----
--Disis.persistor.datanucleus.install-fixtures=true -Disis.fixtures=fixture.simple.scenario.SimpleObjectsFixture
-----
-
-For example, here's what a launch configuration in IntelliJ idea looks like:
-
-image::{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png"]
-
-
-
-where the "before launch" maven goal (to run the DataNucleus enhancer) is defined as:
-
-
-image::{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png[width="400px",link="{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png"]
-
-
-
-
-== Explore codebase
-
-Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
-
-* `petclinic` : parent module
-* `petclinic-dom`: domain objects module
-** entity: `dom.simple.SimpleObject`
-** repository: `dom.simple.SimpleObjects`
-* `petclinic-fixture`: fixtures module
-** fixture script:`fixture.simple.SimpleObjectsFixture`
-* `petclinic-integtests`: integration tests module
-* `petclinic-webapp`: webapp module
-** (builds the WAR file)
-
-
-
-
-== Testing
-
-Testing is of course massively important, and Apache Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
-
-* `myapp-dom` unit tests
-* run
-* inspect, eg
- - `SimpleObjectTest`
-* `myapp-integtests` integration tests
-* run
-* inspect, eg:
-** `integration.tests.smoke.SimpleObjectsTest`
-** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
-* generated report, eg
- - `myapp/integtests/target/cucumber-html-report/index.html`
-** change test in IDE, re-run (in Maven)
-
-If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
-
-
-
-
-== Update POM files
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/68904752bc2de9ebb3c853b79236df2b3ad2c944
-----
-
-====
-
-The POM files generated by the simpleapp archetype describe the app as "SimpleApp". Update them to say "PetClinic" instead.
-
-
-
-
-== Delete the BDD specs
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/9046226249429b269325dfa2baccf03635841c20
-----
-
-====
-
-
-During this tutorial we're going to keep the integration tests in-sync with the code, but we're going to stop short of writing BDD/Cucumber specs.
-
-Therefore delete the BDD feature spec and glue in the `integtest` module:
-
-* `integration/specs/*`
-* `integration/glue/*`
-
-
-
-
-== Rename artifacts
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/bee3629c0b64058f939b6dd20f226be31810fc66
-----
-
-====
-
-
-Time to start refactoring the app. The heart of the PetClinic app is the `Pet` concept, so go through the code and refactor. While we're at it, refactor the app itself from "SimpleApp" to "PetClinicApp".
-
-See the git commit for more detail, but in outline, the renames required are:
-
-* in the `dom` module's production code
-** `SimpleObject` -&gt; `Pet` (entity)
-** `SimpleObjects` -&gt; `Pets` (repository domain service)
-** `SimpleObject.layout.json` -&gt; `Pet.layout.json` (layout hints for the `Pet` entity)
-** delete the `SimpleObject.png`, and add a new `Pet.png` (icon shown against all `Pet` instances).
-* in the `dom` module's unit test code
-** `SimpleObjectTest` -&gt; `PetTest` (unit tests for `Pet` entity)
-** `SimpleObjectsTest` -&gt; `PetsTest` (unit tests for `Pets` domain service)
-* in the `fixture` module:
-** `SimpleObjectsFixturesService` -&gt; `PetClinicAppFixturesService` (rendered as the prototyping menu in the UI)
-** `SimpleObjectsTearDownService` -&gt; `PetClinicAppTearDownService` (tear down all objects between integration tests)
-** `SimpleObjectAbstract` -&gt; `PetAbstract` (abstract class for setting up a single pet object
-*** and corresponding subclasses to set up sample data (eg `PetForFido`)
-** `SimpleObjectsFixture` -&gt; `PetsFixture` (tear downs system and then sets up all pets)
-* in the `integtest` module:
-** `SimpleAppSystemInitializer` -&gt; `PetClinicAppSystemInitializer` (bootstraps integration tests with domain service/repositories)
-** `SimpleAppIntegTest` -&gt; `PetClinicAppIntegTest` (base class for integration tests)
-** `SimpleObjectTest` -&gt; `PetTest` (integration test for `Pet` entity)
-** `SimpleObjectsTest` -&gt; `PetsTest` (integration test for `Pets` domain service)
-* in the `webapp` module:
-** `SimpleApplication` -&gt; `PetClinicApplication`
-** update `isis.properties`
-** update `web.xml`
-
-
-Note that `Pet` has both both Isis and JDO annotations:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(identityType=IdentityType.DATASTORE) // <1>
-@javax.jdo.annotations.DatastoreIdentity(                                      // <2>
-        strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
-         column="id")
-@javax.jdo.annotations.Version(                                                // <3>
-        strategy=VersionStrategy.VERSION_NUMBER,
-        column="version")
-@javax.jdo.annotations.Unique(name="Pet_name_UNQ", members = {"name"})         // <4>
-@ObjectType("PET")                                                             // <5>
-@Bookmarkable                                                                  // <6>
-public class Pet implements Comparable<Pet> {
-    ...
-}
-----
-
-where:
-
-<1> `@PersistenceCapable` and
-<2> `@DatastoreIdentity` specify a surrogate `Id` column to be used as the primary key
-<3> `@Version` provides support for optimistic locking
-<4> `@Unique` enforces a uniqueness constraint so that no two `Pet`s can have the same name (unrealistic, but can refactor later)
-<5> `@ObjectType` is used by Apache Isis for its own internal "OID" identifier; this also appears in the URL in Apache Isis' Wicket viewer and REST API
-<6> `@Bookmarkable` indicates that the object can be automatically bookmarked in Apache Isis' Wicket viewer
-
-[NOTE]
-====
-The `@ObjectType` and `@Bookmarkable` annotations have since been deprecated, replaced with `@DomainObject(objectType=...)` and `@DomainObjectLayout(bookmarking=...)`
-====
-
-
-The `Pets` domain service also has Isis annotations:
-
-[source,java]
-----
-@DomainService(repositoryFor = Pet.class)
-@DomainServiceLayout(menuOrder = "10")
-public class Pets {
-    ...
-}
-----
-
-where:
-
-* `DomainService` indicates that the service should be instantiated automatically (as a singleton)
-* `DomainServiceLayout` provides UI hints, in this case the positioning of the menu for the actions provided by the service
-
-To run the application will require an update to the IDE configuration, for the changed name of the fixture class:
-
-
-image::{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png"]
-
-
-Running the app should now show `Pet`s:
-
-image::{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png"]
-
-
-
-
-
-== Update package names
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55ec36e520191f5fc8fe7f5b89956814eaf13317
-----
-
-====
-
-
-
-The classes created by the simpleapp archetype are by default in the `simple` package. Move these classes to `pets` package instead. Also adjust package names where they appear as strings:
-
-* in `PetClinicAppFixturesService`, change the package name from "fixture.simple" to "fixture.pets".
-* in `PetClinicAppSystemInitializer`, change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
-* in `WEB-INF/isis.properties`, similarly change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
-
-To run the application will require a further update to the IDE configuration, for the changed package of the fixture class:
-
-
-image::{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png"]
-
-
-
-== Add `PetSpecies` enum
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55c9cd28ff960220719b3dc7cb8abadace8d0829
-----
-
-====
-
-
-Each `Pet` is of a particular species. Model these as an enum called `PetSpecies`:
-
-[source,java]
-----
-public enum PetSpecies {
-    Cat,
-    Dog,
-    Budgie,
-    Hamster,
-    Tortoise
-}
-----
-
-Introduce a new property on `Pet` of this type:
-
-[source,java]
-----
-public class Pet {
-    ...
-    private PetSpecies species;
-    @javax.jdo.annotations.Column(allowsNull = "false")
-    public PetSpecies getSpecies() { return species; }
-    public void setSpecies(final PetSpecies species) { this.species = species; }
-    ...
-}
-----
-
-Update fixtures, unit tests and integration tests.
-
-
-
-
-== Icon to reflect pet species
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/2212765694693eb463f8fa88bab1bad154add0cb
-----
-
-====
-
-
-Rather than using a single icon for a domain class, instead a different icon can be supplied for each instance. We can therefore have different icon files for each pet, reflecting that pet's species.
-
-[source,java]
-----
-public class Pet {
-    ...
-    public String iconName() {
-        return getSpecies().name();
-    }
-    ...
-}
-----
-
-Download corresponding icon files (`Dog.png`, `Cat.png` etc)
-
-Running the app shows the `Pet` and its associated icon:
-
-image::{_imagesdir}tutorials/pet-clinic/050-01-list-all.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-01-list-all.png"]
-
-
-
-with the corresponding view of the `Pet`:
-
-image::{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png"]
-
-
-== Add pet's `Owner`
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/6f92a8ee8e76696d005da2a8b7a746444d017546
-----
-
-====
-
-
-Add the `Owner` entity and corresponding `Owners` domain service (repository). Add a query to find `Order`s by name:
-
-[source,java]
-----
-...
-@javax.jdo.annotations.Queries( {
-        @javax.jdo.annotations.Query(
-                name = "findByName", language = "JDOQL",
-                value = "SELECT "
-                        + "FROM dom.owners.Owner "
-                        + "WHERE name.matches(:name)")
-})
-public class Owner ... {
-    ...
-}
-----
-
-and `findByName(...)` in `Owners`:
-
-[source,java]
-----
-public class Owners {
-    ...
-    public List<Owner> findByName(
-            @ParameterLayout(named = "Name")
-            final String name) {
-        final String nameArg = String.format(".*%s.*", name);
-        final List<Owner> owners = container.allMatches(
-                new QueryDefault<>(
-                        Owner.class,
-                        "findByName",
-                        "name", nameArg));
-        return owners;
-    }
-    ...
-}
-----
-
-Add an `owner` property to `Pet`, with supporting `autoCompleteXxx()` method (so that available owners are shown in a drop-down list box):
-
-[source,java]
-----
-public class Pet ... {
-    ...
-    private Owner owner;
-    @javax.jdo.annotations.Column(allowsNull = "false")
-    public Owner getOwner() { return owner; }
-    public void setOwner(final Owner owner) { this.owner = owner; }
-    public Collection<Owner> autoCompleteOwner(final @MinLength(1) String name) {
-        return owners.findByName(name);
-    }
-    ...
-}
-----
-
-Also updated fixture data to set up a number of `Owner`s, and associate each `Pet` with an `Owner`. Also add unit tests and integration tests for `Owner`/`Owners` and updated for `Pet`/`Pets`.
-
-When running the app, notice the new `Owners` menu:
-
-image::{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png"]
-
-which when invoked returns all `Owner` objects:
-
-image::{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png"]
-
-
-Each `Pet` also indicates its corresponding `Owner`:
-
-image::{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png"]
-
-
-And, on editing a `Pet`, a new `Owner` can be specified using the autoComplete:
-
-image::{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png"]
-

[02/10] isis git commit: ISIS-1133: updated guidance on mapping of Blobs and Clobs.

[da...@apache.org]

ISIS-1133: updated guidance on mapping of Blobs and Clobs.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/dfe4dcb6
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/dfe4dcb6
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/dfe4dcb6

Branch: refs/heads/master
Commit: dfe4dcb6669322806f014d1f89d02ac8a619fbc1
Parents: f1f9b23
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jul 9 19:18:03 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jul 9 19:18:03 2015 +0100

----------------------------------------------------------------------
 .../guides/_rg_annotations_manpage-Column.adoc  |  4 +--
 .../_ug_how-tos_class-structure_properties.adoc | 30 +++++++++++++++-----
 .../java/org/apache/isis/applib/value/Clob.java |  6 ++++
 3 files changed, 31 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/dfe4dcb6/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
index d32969c..2e5e205 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
@@ -126,7 +126,7 @@ private Blob attachment;
 @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
         @javax.jdo.annotations.Column(name = "attachment_name"),
         @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-        @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "BLOB")
+        @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "LONGVARBINARY")
 })
 @Property(
         domainEvent = AttachmentDomainEvent.class,
@@ -144,7 +144,7 @@ private Clob doc;
 @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
         @javax.jdo.annotations.Column(name = "doc_name"),
         @javax.jdo.annotations.Column(name = "doc_mimetype"),
-        @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
+        @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "LONGVARCHAR")
 })
 @Property(
         optionality = Optionality.OPTIONAL

http://git-wip-us.apache.org/repos/asf/isis/blob/dfe4dcb6/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
index a14c60d..5b5e983 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
@@ -201,7 +201,7 @@ For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-
 @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
     @javax.jdo.annotations.Column(name = "attachment_name"),
     @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "BLOB")
+    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "LONGVARBINARY")
 })
 private Blob attachment;
 @Property(
@@ -224,7 +224,8 @@ If the `Blob` is mandatory, then use:
 @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
     @javax.jdo.annotations.Column(name = "attachment_name", allowsNull="false"),
     @javax.jdo.annotations.Column(name = "attachment_mimetype", allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "BLOB",
+    @javax.jdo.annotations.Column(name = "attachment_bytes",
+                                  jdbcType="BLOB", sqlType = "LONGVARBINARY",
                                   allowsNull="false")
 })
 private Blob attachment;
@@ -239,16 +240,23 @@ this.attachment = attachment;
 }
 ----
 
+[NOTE]
+====
+If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".  There can be differences in behaviour between JDBC drivers.
+====
+
+
 === Mapping Clobs
 
-Mapping `Clob`s works in a very similar way, but the `@Column#sqlType` attribute will be `CLOB`:
+Mapping `Clob`s works in a very similar way, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
 
 [source,java]
 ----
 @javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
     @javax.jdo.annotations.Column(name = "attachment_name"),
     @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "CLOB")
+    @javax.jdo.annotations.Column(name = "attachment_chars",
+                                  jdbcType="CLOB", sqlType = "LONGVARCHAR")
 })
 private Clob doc;
 @Property(
@@ -262,18 +270,26 @@ public void setDoc(final Clob doc) {
 }
 ----
 
+[NOTE]
+====
+If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".  There can be differences in behaviour between JDBC drivers.
+====
 
 === Mapping to VARBINARY or VARCHAR
 
-Instead of mapping to a `Blob` or `Clob` datatype, you might also specify map to a `VARBINARY` or `VARCHAR`. In this case you will need to specify a length. For example:
+Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`.  The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a `VARBINARY` the data is held on-row and so you will need to specify a length.
+
+For example:
 
 
 [source,java]
 ----
-@javax.jdo.annotations.Column(name = "attachment_bytes", sqlType = "VARBINARY", length=2048)
+@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", sqlType = "VARBINARY", length=2048)
 ----
 
-or
+
+The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to a regular `VARCHAR`:
+
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/dfe4dcb6/core/applib/src/main/java/org/apache/isis/applib/value/Clob.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/value/Clob.java b/core/applib/src/main/java/org/apache/isis/applib/value/Clob.java
index 924b0c8..275ee93 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/value/Clob.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/value/Clob.java
@@ -100,4 +100,10 @@ public final class Clob implements NamedWithMimeType, Serializable {
             }
         });
     }
+
+    @Override
+    public String toString() {
+        return getName() + " [" + getMimeType().getBaseType() + "]: " + getChars().length() + " chars";
+    }
+
 }

[07/10] isis git commit: ISIS-1133: pulling together the contributors guide.

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
deleted file mode 100644
index 4e6b48d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
+++ /dev/null
@@ -1,396 +0,0 @@
-[[_dg_intellij]]
-= Setting up IntelliJ IDEA
-:Notice: 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.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-
-This appendix describes how to install and setup IntelliJ, then how to import an application into IntelliJ and run it.
-
-
-[NOTE]
-====
-This document relates to IntelliJ Community Edition 14.1.1, with screenshots taken for Windows.
-====
-
-== Installing and Setting up
-
-This section covers installation and setup.
-
-=== Download and Install
-
-https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
-
-Start the wizard, click through the welcome page:
-
-.IntelliJ Installation Wizard - Welcome page
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png[width="400px"]
-
-Choose the location to install the IDE:
-
-.IntelliJ Installation Wizard - Choose Location
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/020-choose-location.png[width="400px"]
-
-Adjust any installation options as you prefer:
-
-.IntelliJ Installation Wizard - Installation Options
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/030-installation-options.png[width="400px"]
-
-and the start menu:
-
-.IntelliJ Installation Wizard - Start Menu Folder
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
-
-and finish up the wizard:
-
-.IntelliJ Installation Wizard - Completing the Wizard
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/050-completing.png[width="400px"]
-
-Later on we'll specify the Apache Isis/ASF code style settings, so for now select `I do not want to import settings`:
-
-.IntelliJ Installation Wizard - Import Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
-
-Finally, if you are young and trendy, set the UI theme to Darcula:
-
-.IntelliJ Installation Wizard Set UI Theme
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
-
-
-
-
-=== New Project
-
-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).
-
-Start off by creating a new project:
-
-.IntelliJ Create New Project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
-
-We want to create a new *Java* project:
-
-.IntelliJ Create New Project - Create a Java project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="600px"]
-
-We therefore need to specify the JDK.
-
-NOTE: at the time of writing Apache Isis supports only Java 7; Java 8 is scheduled for support in Apache Isis v1.9.0
-
-
-.IntelliJ Create New Java Project - Select the JDK
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="300px"]
-
-Specify the directory containing the JDK:
-
-.IntelliJ Create New Project - Select the JDK location
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
-
-Finally allow IntelliJ to create the directory for the new project:
-
-.IntelliJ Create New Project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png[width="200px"]
-
-
-
-=== Import Settings
-
-Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions.  These are bundled as the `settings.jar` JAR file link:resources/appendices/dev-env/intellij/isis-settings.jar[download from the Apache Isis website]).
-
-Import using: `File > Import Settings`, and specify the directory that you have downloaded the file to:
-
-.IntelliJ Import Settings - Specify JAR file
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
-
-Select all the (two) categories of settings available in the JAR file:
-
-.IntelliJ Import Settings - Select all categories
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png[width="300px"]
-
-And then restart:
-
-.IntelliJ Import Settings - Restart
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/030-restart.png[width="200px"]
-
-
-
-=== Other Settings
-
-There are also some other miscellaneous settings that we recommend that you adjust (though these are not critical).
-
-First, specify an up-to-date Maven installation, using `File > Settings` (or `IntelliJ > Preferences` if on MacOS):
-
-.IntelliJ Other Settings - Maven Installation
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png[width="600px"]
-
-Still on the Maven settings page, configure as follows:
-
-.IntelliJ Other Settings - Maven Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png[width="600px"]
-
-On the compiler settings page, ensure that `build automatically` is enabled (and optionally `compile independent modules in parallel`):
-
-.IntelliJ Other Settings - Compiler Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png[width="600px"]
-
-On the auto import page, check the `optimize imports on the fly` and `add unambiguous imports on the fly`
-
-.IntelliJ Other Settings - Auto Import
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png[width="600px"]
-
-
-
-=== Plugins
-
-You might also want to set up some additional plugins, using `File > Settings > Plugins` (or equivalently `File > Other Settings > Configure Plugins`).
-
-Recommended are:
-
-* link:https://plugins.jetbrains.com/plugin/7179?pr=idea[Maven Helper] plugin
-+
-More on this below.
-
-* link:https://github.com/asciidoctor/asciidoctor-intellij-plugin[AsciiDoctor] plugin
-+
-Useful if you are doing any authoring of documents.
-
-Some others you might like to explore are:
-
-.IntelliJ Plugins
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="600px"]
-
-==== Maven Helper Plugin
-
-This plugin provides a couple of great features.  One is better visualization of dependency trees (similar to Eclipse).
-
-If you open a `pom.xml` file, you'll see an additional "Dependencies" tab:
-
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"]
-
-Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by `mvn dependency:tree`, but filterable.
-
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"]
-
-The plugin also provides the ability to easily run a Maven goal on a project:
-
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"]
-
-This menu can also be bound to a keystroke so that it is available as a pop-up:
-
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"]
-
-
-
-== Importing and Managing Maven Modules
-
-Let's load in some actual code!  We do this by importing the Maven modules.
-
-First up, open up the Maven tool window (`View > Tool Windows > Maven Projects`).  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 _Maven Projects_ window and corresponding (IntelliJ) modules are shown in the _Projects_ window:
-
-.IntelliJ Maven Module Management - Importing Maven modules
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
-
-We can then import another module (from some other directory).  For example, here we are importing the Isis Addons' todoapp example:
-
-
-.IntelliJ Maven Module Management - Importing another Module
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
-
-You should then see the new Maven module loaded in the _Projects_ window and also the _Maven Projects_ window:
-
-.IntelliJ Maven Module Management -
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
-
-If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from `.m2/repository` folder).  So, for example (assuming that the `<version>` is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.
-
-You can press F4 (or use `File > Project Structure`) to see the resolved classpath for any of the modules loaded into the project.
-
-If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you _could_ remove the module; but better is to ignore those modules.  This will remove from the the _Projects_ window but keep them available in the _Maven Projects_ window for when you next want to work on them:
-
-.IntelliJ Maven Module Management - Ignoring Modules
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
-
-Confirm that it's ok to ignore these modules:
-
-.IntelliJ Maven Module Management - Ignoring Modules (ctd)
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
-
-All being well you should see that the _Projects_ window now only contains the code you are working on.  Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from `.m2/repository`):
-
-.IntelliJ Maven Module Management - Updated Projects Window
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
-
-
-
-== Running
-
-Let's see how to run both the app and the tests.
-
-=== Running the App
-
-Once you've imported your Isis application, we should run it.  We do this by creating a Run configuration, using `Run > Edit Configurations`.
-
-Set up the details as follows:
-
-.IntelliJ Running the App - Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
-
-We specify the `Main class` to be `org.apache.isis.WebServer`; 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.
-
-Also note that `Use classpath of module` is the webapp module for your app, and that the `working directory` is `$MODULE_DIR$`.
-
-Next, and most importantly, configure the DataNucleus enhancer to run for your `dom` goal.  This can be done by defining a Maven goal to run before the app:
-
-.IntelliJ Running the App - Datanucleus Enhancer Goal
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
-
-The `-o` flag in the goal means run off-line; this will run faster.
-
-WARNING: 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.
-
-You should now be able to run the app using `Run > Run Configuration`.  The same configuration can also be used to debug the app if you so need.
-
-
-=== Running the Unit Tests
-
-The easiest way to run the unit tests is just to right click on the `dom` module in the _Project Window_, and choose run unit tests.  Hopefully your tests will pass (!).
-
-.IntelliJ Running the App - Unit Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
-
-As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:
-
-.IntelliJ Running the App - Unit Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
-
-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).
-
-=== Running the Integration Tests
-
-Integration tests can be run in the same way as unit tests, however the `dom` module must also have been enhanced.
-
-One approach is to initially run the tests use the right click on the `integtests` 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):
-
-.IntelliJ Running the App - Integration Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
-
-
-
-
-== Hints and Tips
-
-=== Keyboard Shortcuts Cheat Sheets
-
-You can download 1-page PDFs cheat sheets for IntelliJ's keyboard shortcuts:
-* for link:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf[Windows]
-* for MacOS:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]
-
-Probably the most important shortcut on them is for `Find Action`:
-- `ctrl-shift-A` on Windows
-- `cmd-shift-A` on MacOS.
-
-This will let you search for any action just by typing its name.
-
-### Switching between Tool Windows and Editors
-
-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.
-
-* Use `alt-1` through `alt-9` (or `cmd-1` through `alt-9`) to select the tool windows
-** Press it twice and the tool window will hide itself; so can use to toggle
-* If in the _Project Window_ (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 `Esc`.
-** If in the _Terminal Window_, you'll need to press `Shift-Esc`.
-* If on the editor and want to locate the file in (say) the _Project Window_, use `alt-F1`.
-* To change the size of any tool window, use `ctrl-shift-arrow`
-
-Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse.  Peachy!
-
-=== Navigating Around
-
-For all of the following, you don't need to type every letter, typing "ab" will actually search for ".*a.*b.*".
-
-* to open classes or files or methods that you know the name of:
-** `ctrl-N` to open class
-** `ctrl-shift-N` to open a file
-** (bit fiddly this) `ctrl-shift-alt-N` to search for any symbol.
-* open up dialog of recent files: `ctrl-E`
-* search for any file: `shift-shift`
-
-Navigating around:
-* find callers of a method (the call hierarchy): `ctrl-alt-H`
-* find subclasses or overrides: `ctrl-alt-B`
-* find superclasses/interface/declaration: `ctrl-B`
-
-Viewing the structure (ie outline) of a class
-* `ctrl-F12` will pop-up a dialog showing all members
-** hit `ctrl-F12` again to also see inherited members
-
-
-=== Editing
-
-* Extend selection using `ctrl-W`
-** and contract it down again using `ctrl-shift-W`
-* to duplicate a line, it's `ctrl-D`
-** if you have some text selected (or even some lines), it'll actually duplicate the entire selection
-* to delete a line, it's `ctrl-X`
-* to move a line up or down: `shift-alt-up` and `shift-alt-down`
-** if you have selected several lines, it'll move them all togethe
-* `ctrl-shift-J` can be handy for joining lines together
-** just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")
-
-### Intentions and Code Completion
-
-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.
-
-Code completion usually happens whenever you type '.'.  You can also use `ctrl-space` to bring these up.
-
-In certain circumstances (eg in methods0) you can also type `ctrl-shift-space` to get a smart list of methods etc that you might want to call.  Can be useful.
-
-Last, when invoking a method, use `ctrl-P` to see the parameter types.
-
-
-=== Refactoring
-
-Loads of good stuff on the `Refactor` menu; most used are:
-
-* Rename (`shift-F6`)
-* Extract
-** method: `ctrl-alt-M`
-** variable: `ctrl-alt-V`
-* Inline method/variable: `ctrl-alt-N`
-* Change signature
-
-If you can't remember all those shortcuts, just use `ctrl-shift-alt-T` (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object
-
-
-=== Troubleshooting
-
-When a Maven module is imported, IntelliJ generates its own project files (suffix `.ipr`), and the application is actually built from that.
-
-Occasionally these don't keep in sync (even if auto-import of Maven modules has been enabled).
-
-To fix the issue, try:
-* reimport module
-* rebuild selected modules/entire project
-* remove and then re-add the project
-* restart, invalidating caches
-* hit StackOverflow (!)
-
-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 `File > Synchronize`, `ctrl-alt-Y`.
-
-
-
-
-== Advanced
-
-In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
-
-
-=== Setting up Dynamic Reloading
-
-NOTE: TODO - see link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
-
-
-=== Setting up JRebel
-
-NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
index 6801073..213df78 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
@@ -1,4 +1,4 @@
-[[_rg-annotations]]
+[[_rg_annotations]]
 = Annotations
 :Notice: 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.
 :_basedir: ../

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
index a06df8a..4637983 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
@@ -33,7 +33,7 @@ Note that there is a `DomainObjectContainer#newViewModelInstance(.)`; this is fo
 ====
 
 
-The view model's memento will be derived from the value of the view model object's properties. Any xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any http://isis.apache.org/reference/recognized-annotations/Programmatic.html[@Programmatic] properties. Properties that are merely http://isis.apache.org/reference/recognized-annotations/Hidden-deprecated.html[@Hidden] are included in the memento.
+The view model's memento will be derived from the value of the view model object's properties. Any xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] properties. Properties that are merely xref:rg.adoc#_rg_annotations_manpage-Property_hidden[hidden] _are_ included in the memento.
 
 Only properties supported by the configured xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`] can be used. The default implementation supports all the value types and persisted entities.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
index 241af3c..618fc8d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
@@ -51,9 +51,9 @@ isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=fa
 
 == The issue in more detail
 
-Consider the entities:
+Consider the link:http://yuml.me/edit/742ad446[entities]:
 
-    Party <->* AgreementRole <*-> Agreement
+image::{_imagesdir}reference-classes/issue-in-more-detail.png[link="{_imagesdir}reference-classes/issue-in-more-detail.png"]
 
 In the course of a transaction, the `Agreement` entity is loaded into memory (not necessarily modified), and then new ``AgreementRole``s are associated to it.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
index 010fb81..8db6b78 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
@@ -19,10 +19,10 @@ For example:
 
 [source,java]
 ----
-@RequestScoped                                                  // <1>
+@RequestScoped                                                   // <1>
 @DomainService(nature=NatureOfService.DOMAIN)
 public class ObjectChangedListenerService
-        implements javax.jdo.listener.StoreLifecycleListener {   // <1>
+        implements javax.jdo.listener.StoreLifecycleListener {   // <2>
     @Programmatic
     @PostConstruct
     public void init() {
@@ -34,7 +34,7 @@ public class ObjectChangedListenerService
         getPmFactory().removeInstanceLifecycleListener(this);
     }
     private PersistenceManager getPersistenceManager() {
-        return jdoSupport.getPersistenceManager();              // <3>
+        return jdoSupport.getPersistenceManager();               // <3>
     }
     @Programmatic
     public void preStore (InstanceLifecycleEvent event) { ... }

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
index 3843f46..0067cf1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
@@ -87,7 +87,7 @@ public class Parties ... { ... }
 Note that only the `menuOrder` of the _first_ domain service is significant in placing the menus along the menu bar;
 thereafter the purpose of the `menuOrder` is to order the menu services sections on the menu itself.
 
-== Ordering of a service's actions within a menu
+== Ordering menu actions
 
 For a given service, the actions within a section on a menu is determined by the `@MemberOrder` annotation. Thus, for
 the `Units` domain service, its actions are annotated:

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
index 8bc6c02..546caed 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
@@ -105,7 +105,7 @@ Note also that the layout file may contain entries for xref:ug.adoc#_ug_how-tos_
 
 
 
-== Downloading an initial layout file
+== Downloading an initial layout
 
 The fastest way to get started is to use the (non-ASF) link:http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module to download the layout file (derived from any existing static metadata defined by annotations).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
index 255287c..651c695 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime.adoc
@@ -1,5 +1,5 @@
 [[_rg_runtime]]
-= Runtime Configuration
+= Configuration Properties
 :Notice: 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.
 :_basedir: ../
 :_imagesdir: images/
@@ -20,7 +20,6 @@ include::_rg_runtime_configuration-files.adoc[leveloffset=+1]
 include::_rg_runtime_specifying-components.adoc[leveloffset=+1]
 include::_rg_runtime_configuring-core.adoc[leveloffset=+1]
 include::_rg_runtime_configuring-datanucleus.adoc[leveloffset=+1]
-include::_rg_runtime_web-xml.adoc[leveloffset=+1]
 include::_rg_runtime_application-specific.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
index f3aeb76..a17a6e9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_deployment-types.adoc
@@ -66,7 +66,7 @@ Wicket's mechanism for specifying the "configuration" is to use a context parame
 
 Most Apache Isis applications will consist of at least the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and optionally the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].  When both viewers are deployed in the same app, then the bootstrapping is performed by Wicket, and so the deployment type is configured as described in the previous section.
 
-In some cases though you may be using Apache Isis to provide a REST API only, that is, you won't have deployed the Wicket viewer.  In these cases your app will be bootstrapped using  Apache Isis' xref:rg.adoc#_rg_runtime_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
+In some cases though you may be using Apache Isis to provide a REST API only, that is, you won't have deployed the Wicket viewer.  In these cases your app will be bootstrapped using  Apache Isis' xref:rg.adoc#_rg_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
 
 In this case the deployment type is specified through an Apache Isis-specific context parameter, called `isis.deploymentType`:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
index 0c40fa4..59a14b2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
@@ -57,7 +57,7 @@ The values "datanucleus", "shiro" etc are actually aliases for concrete implemen
 
 It is -- at least in theory -- possible to specify a fully qualified class name to replace any of these components.  This is probably feasible for the two security APIs and the `services-installer` API; but replacing the persistor (JDO/DataNucleus) is much trickier because we rely on the JDO/DN for certain functionality (such as object dirtying and lazy loading) that is not defined within this API.
 
-As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed xref:rg.adoc#_rg_runtime_web-xml[below]).  However, the configuration of which viewers to initialize is declared through a context parameter:
+As for the viewers, these are specified indirectly by way of the filters and servlets in the xref:rg.adoc#_rg_web-xml[`web.xml`] file.  However, the configuration of which viewers to initialize is declared through a context parameter:
 
 
 [source,xml]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
deleted file mode 100644
index 4d7cee4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_web-xml.adoc
+++ /dev/null
@@ -1,463 +0,0 @@
-[[_rg_runtime_web-xml]]
-= `web.xml`
-:Notice: 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.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-Apache Isis provides two different viewers, the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].  You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer.  The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
-
-If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`.  See the xref:ug.adoc#_ug_security_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
-
-The servlets and filters are mapped to three main pipelines:
-
-* `/wicket` - the Wicket viewer UI
-* `/restful` - the Restful Objects resources (REST API)
-* other paths, also static resources (such as `.png`, `.css`)
-
-With the following key:
-
-image::{_imagesdir}runtime/web-xml/key.png[width="800px",link="{_imagesdir}runtime/web-xml/key.png"]
-
-the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
-
-image::{_imagesdir}runtime/web-xml/wicket-and-ro.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-and-ro.png"]
-
-Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API).  This class is also responsible for Apache Isis' own session and transaction management.
-
-The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener.  It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`.  This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
-
-If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
-
-image::{_imagesdir}runtime/web-xml/wicket-only.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-only.png"]
-
-Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly.  Here, the Wicket filter is no longer needed.  In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
-
-image::{_imagesdir}runtime/web-xml/ro-only.png[width="800px",link="{_imagesdir}runtime/web-xml/ro-only.png"]
-
-The following sections detail these various listeners, filters and servlets in more detail.
-
-
-
-[[_rg_runtime_web-xml_servlet-context-listeners]]
-== Servlet Context Listeners
-
-Servlet context listeners are used to perform initialization on application startup.  Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener.  In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
-
-
-=== `EnvironmentLoaderListener` (Shiro)
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<listener>
-    <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-----
-
-
-
-=== `IsisWebAppBootstrapper`
-
-The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework.  This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<listener>
-    <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
-</listener>
-----
-
-context parameters:
-
-[source,xml]
-----
-<context-param>
-    <param-name>deploymentType</param-name>
-    <param-value>SERVER_PROTOTYPE</param-value>
-</context-param>
-<context-param>
-    <param-name>isis.viewers</param-name>
-    <param-value>restfulobjects</param-value>
-</context-param>
-----
-
-
-=== `ResteasyBootstrap` (RestEasy)
-
-The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources.  It is required if the Restful Objects viewer is to be deployed.
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<listener>
-    <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
-</listener>
-----
-
-There are two relevant context parameters:
-
-[source,xml]
-----
-<context-param>
-    <param-name>javax.ws.rs.Application</param-name>        <!--1-->
-    <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
-</context-param>
-<context-param>
-    <param-name>resteasy.servlet.mapping.prefix</param-name>
-    <param-value>/restful/</param-value>                    <!--2-->
-</context-param>
-----
-<1> used by RestEasy to determine the JAX-RS resources and other related configuration
-<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
-
-
-
-[[_rg_runtime_web-xml_servlets]]
-== Servlets
-
-NOTE: WIP
-
-
-=== `HttpServletDispatcher` (RestEasy)
-
-NOTE: WIP
-
-
-definition:
-
-[source,xml]
-----
-<servlet>
-    <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-    <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-mapping:
-
-[source,xml]
-----
-<servlet-mapping>
-    <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-    <url-pattern>/restful/*</url-pattern>
-</servlet-mapping>
-----
-
-
-=== `ResourceServlet`
-
-NOTE: WIP
-
-definition
-
-[source,xml]
-----
-<servlet>
-    <servlet-name>Resource</servlet-name>
-    <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
-</servlet>
-----
-
-mapping:
-
-[source,xml]
-----
-<servlet-mapping>
-    <servlet-name>Resource</servlet-name>
-    <url-pattern>*.css</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
-    <servlet-name>Resource</servlet-name>
-    <url-pattern>*.png</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
-    <servlet-name>Resource</servlet-name>
-    <url-pattern>*.jpg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
-    <servlet-name>Resource</servlet-name>
-    <url-pattern>*.gif</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
-    <servlet-name>Resource</servlet-name>
-    <url-pattern>*.js</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
-    <servlet-name>Resource</servlet-name>
-    <url-pattern>*.html</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
-    <servlet-name>Resource</servlet-name>
-    <url-pattern>*.swf</url-pattern>
-</servlet-mapping>
-----
-
-
-
-
-[[_rg_runtime_web-xml_filters]]
-== Filters
-
-The order in which filters appear in `web.xml` matters: first to last they define a pipeline.  This is shown in the above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
-
-=== `ShiroFilter` (Shiro)
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<filter>
-    <filter-name>ShiroFilter</filter-name>
-    <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-----
-
-mapping:
-
-[source,xml]
-----
-<filter-mapping>
-    <filter-name>ShiroFilter</filter-name>
-    <url-pattern>/*</url-pattern>
-</filter-mapping>
-----
-
-
-=== `IsisLogOnExceptionFilter`
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<filter>
-    <filter-name>IsisLogOnExceptionFilter</filter-name>
-    <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
-</filter>
-----
-
-
-mapping:
-
-[source,xml]
-----
-<filter-mapping>
-    <filter-name>IsisLogOnExceptionFilter</filter-name>
-    <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-<filter-mapping>
-    <filter-name>IsisLogOnExceptionFilter</filter-name>
-    <url-pattern>/restful/*</url-pattern>
-</filter-mapping>
-----
-
-
-
-=== `ResourceCachingFilter`
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<filter>
-    <filter-name>ResourceCachingFilter</filter-name>
-    <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
-    <init-param>
-        <param-name>CacheTime</param-name>      <!--1-->
-        <param-value>86400</param-value>
-    </init-param>
-</filter>
-----
-<1> cache time, in seconds
-
-mapping:
-
-[source,xml]
-----
-<filter-mapping>
-    <filter-name>ResourceCachingFilter</filter-name>
-    <url-pattern>*.js</url-pattern>
-</filter-mapping>
-<filter-mapping>
-    <filter-name>ResourceCachingFilter</filter-name>
-    <url-pattern>*.css</url-pattern>
-</filter-mapping>
-<filter-mapping>
-    <filter-name>ResourceCachingFilter</filter-name>
-    <url-pattern>*.png</url-pattern>
-</filter-mapping>
-<filter-mapping>
-    <filter-name>ResourceCachingFilter</filter-name>
-    <url-pattern>*.jpg</url-pattern>
-</filter-mapping>
-<filter-mapping>
-    <filter-name>ResourceCachingFilter</filter-name>
-    <url-pattern>*.gif</url-pattern>
-</filter-mapping>
-<filter-mapping>
-    <filter-name>ResourceCachingFilter</filter-name>
-    <url-pattern>*.html</url-pattern>
-</filter-mapping>
-<filter-mapping>
-    <filter-name>ResourceCachingFilter</filter-name>
-    <url-pattern>*.swf</url-pattern>
-</filter-mapping>
-----
-
-
-=== `WicketFilter`
-
-NOTE: WIP
-
-
-definition:
-
-[source,xml]
-----
-<filter>
-    <filter-name>WicketFilter</filter-name>
-    <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
-    <init-param>
-        <param-name>applicationClassName</param-name>   <!--1-->
-        <param-value>domainapp.webapp.SimpleApplication</param-value>
-    </init-param>
-</filter>
-----
-<1> specify the application (subclass of `IsisWicketApplication`) to use
-
-mapping:
-
-[source,xml]
-----
-<filter-mapping>
-    <filter-name>WicketFilter</filter-name>
-    <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-----
-
-This filter reads one context parameter:
-[source,xml]
-----
-<context-param>
-    <param-name>configuration</param-name>
-    <param-value>deployment</param-value>   <!--1-->
-</context-param>
-----
-<1> alternatively set to "development"; see xref:rg.adoc#_rg_runtime_deployment-types[deployment types] for further discussion.
-
-
-=== `IsisSessionFilter`
-
-The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object.  It is only required for the Restful Objects viewer.
-
-[source,xml]
-----
-<filter>
-    <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
-    <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
-    <init-param>
-        <param-name>authenticationSessionStrategy</param-name>  <!--1-->
-        <param-value>
-            org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
-        </param-value>
-    </init-param>
-    <init-param>
-        <param-name>whenNoSession</param-name>                  <!--2-->
-        <param-value>basicAuthChallenge</param-value>
-    </init-param>
-    <!--
-    <init-param>
-        <param-name>restricted</param-name>                     <!--3-->
-        <param-value>...</param-value>
-    </init-param>
-    <init-param>
-        <param-name>redirectToOnException</param-name>          <!--4-->
-        <param-value>...</param-value>
-    </init-param>
-    -->
-</filter>
-----
-<1> pluggable strategy for determining what the authentication session (credentials) are of the request
-<2> what the servlet should do if no existing session was found; typically a 401, or can issue a Basic Auth challenge
-<3> List of paths that are allowed through even if not authenticated.  The servlets mapped to these paths are expected to be able to deal with there being no session. Typically they will be logon pages.
-<4> where to redirect to if an exception occurs.
-
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
-    <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
-    <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-
-=== `IsisTransactionFilterForRestfulObjects`
-
-NOTE: WIP
-
-definition:
-
-[source,xml]
-----
-<filter>
-    <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
-    <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
-</filter>
-----
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
-    <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
-    <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-[[_rg_runtime_web-xml_context-parameters]]
-== Configuration Files
-
-However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will read a number of configuration files, such as `isis.properties`.
-
-By default these are read from `WEB-INF` directory.
-
-    <context-param>
-      <param-name>isis.config.dir</param-name>
-      <param-value>location of your config directory if fixed</param-value>
-    </context-param>
-    -->
-
-
-    <!--
-    determines which additional configuration files to search for
-     -->
-    <context-param>
-        <param-name>isis.viewers</param-name>
-        <param-value>wicket,restfulobjects</param-value>
-    </context-param>
-

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
new file mode 100644
index 0000000..93d09ce
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_web-xml.adoc
@@ -0,0 +1,463 @@
+[[_rg_web-xml]]
+= `web.xml`
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+Apache Isis provides two different viewers, the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].  You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer.  The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
+
+If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`.  See the xref:ug.adoc#_ug_security_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
+
+The servlets and filters are mapped to three main pipelines:
+
+* `/wicket` - the Wicket viewer UI
+* `/restful` - the Restful Objects resources (REST API)
+* other paths, also static resources (such as `.png`, `.css`)
+
+With the following key:
+
+image::{_imagesdir}runtime/web-xml/key.png[width="800px",link="{_imagesdir}runtime/web-xml/key.png"]
+
+the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
+
+image::{_imagesdir}runtime/web-xml/wicket-and-ro.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-and-ro.png"]
+
+Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API).  This class is also responsible for Apache Isis' own session and transaction management.
+
+The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener.  It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`.  This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
+
+If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
+
+image::{_imagesdir}runtime/web-xml/wicket-only.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-only.png"]
+
+Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly.  Here, the Wicket filter is no longer needed.  In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
+
+image::{_imagesdir}runtime/web-xml/ro-only.png[width="800px",link="{_imagesdir}runtime/web-xml/ro-only.png"]
+
+The following sections detail these various listeners, filters and servlets in more detail.
+
+
+
+[[_rg_web-xml_servlet-context-listeners]]
+== Servlet Context Listeners
+
+Servlet context listeners are used to perform initialization on application startup.  Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener.  In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
+
+
+=== `EnvironmentLoaderListener` (Shiro)
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<listener>
+    <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
+</listener>
+----
+
+
+
+=== `IsisWebAppBootstrapper`
+
+The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework.  This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<listener>
+    <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
+</listener>
+----
+
+context parameters:
+
+[source,xml]
+----
+<context-param>
+    <param-name>deploymentType</param-name>
+    <param-value>SERVER_PROTOTYPE</param-value>
+</context-param>
+<context-param>
+    <param-name>isis.viewers</param-name>
+    <param-value>restfulobjects</param-value>
+</context-param>
+----
+
+
+=== `ResteasyBootstrap` (RestEasy)
+
+The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources.  It is required if the Restful Objects viewer is to be deployed.
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<listener>
+    <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
+</listener>
+----
+
+There are two relevant context parameters:
+
+[source,xml]
+----
+<context-param>
+    <param-name>javax.ws.rs.Application</param-name>        <!--1-->
+    <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
+</context-param>
+<context-param>
+    <param-name>resteasy.servlet.mapping.prefix</param-name>
+    <param-value>/restful/</param-value>                    <!--2-->
+</context-param>
+----
+<1> used by RestEasy to determine the JAX-RS resources and other related configuration
+<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
+
+
+
+[[_rg_web-xml_servlets]]
+== Servlets
+
+NOTE: WIP
+
+
+=== `HttpServletDispatcher` (RestEasy)
+
+NOTE: WIP
+
+
+definition:
+
+[source,xml]
+----
+<servlet>
+    <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+    <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
+</servlet>
+----
+
+mapping:
+
+[source,xml]
+----
+<servlet-mapping>
+    <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+    <url-pattern>/restful/*</url-pattern>
+</servlet-mapping>
+----
+
+
+=== `ResourceServlet`
+
+NOTE: WIP
+
+definition
+
+[source,xml]
+----
+<servlet>
+    <servlet-name>Resource</servlet-name>
+    <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
+</servlet>
+----
+
+mapping:
+
+[source,xml]
+----
+<servlet-mapping>
+    <servlet-name>Resource</servlet-name>
+    <url-pattern>*.css</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+    <servlet-name>Resource</servlet-name>
+    <url-pattern>*.png</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+    <servlet-name>Resource</servlet-name>
+    <url-pattern>*.jpg</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+    <servlet-name>Resource</servlet-name>
+    <url-pattern>*.gif</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+    <servlet-name>Resource</servlet-name>
+    <url-pattern>*.js</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+    <servlet-name>Resource</servlet-name>
+    <url-pattern>*.html</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+    <servlet-name>Resource</servlet-name>
+    <url-pattern>*.swf</url-pattern>
+</servlet-mapping>
+----
+
+
+
+
+[[_rg_web-xml_filters]]
+== Filters
+
+The order in which filters appear in `web.xml` matters: first to last they define a pipeline.  This is shown in the above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
+
+=== `ShiroFilter` (Shiro)
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+    <filter-name>ShiroFilter</filter-name>
+    <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
+</filter>
+----
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+    <filter-name>ShiroFilter</filter-name>
+    <url-pattern>/*</url-pattern>
+</filter-mapping>
+----
+
+
+=== `IsisLogOnExceptionFilter`
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+    <filter-name>IsisLogOnExceptionFilter</filter-name>
+    <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
+</filter>
+----
+
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+    <filter-name>IsisLogOnExceptionFilter</filter-name>
+    <url-pattern>/wicket/*</url-pattern>
+</filter-mapping>
+<filter-mapping>
+    <filter-name>IsisLogOnExceptionFilter</filter-name>
+    <url-pattern>/restful/*</url-pattern>
+</filter-mapping>
+----
+
+
+
+=== `ResourceCachingFilter`
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+    <filter-name>ResourceCachingFilter</filter-name>
+    <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
+    <init-param>
+        <param-name>CacheTime</param-name>      <!--1-->
+        <param-value>86400</param-value>
+    </init-param>
+</filter>
+----
+<1> cache time, in seconds
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+    <filter-name>ResourceCachingFilter</filter-name>
+    <url-pattern>*.js</url-pattern>
+</filter-mapping>
+<filter-mapping>
+    <filter-name>ResourceCachingFilter</filter-name>
+    <url-pattern>*.css</url-pattern>
+</filter-mapping>
+<filter-mapping>
+    <filter-name>ResourceCachingFilter</filter-name>
+    <url-pattern>*.png</url-pattern>
+</filter-mapping>
+<filter-mapping>
+    <filter-name>ResourceCachingFilter</filter-name>
+    <url-pattern>*.jpg</url-pattern>
+</filter-mapping>
+<filter-mapping>
+    <filter-name>ResourceCachingFilter</filter-name>
+    <url-pattern>*.gif</url-pattern>
+</filter-mapping>
+<filter-mapping>
+    <filter-name>ResourceCachingFilter</filter-name>
+    <url-pattern>*.html</url-pattern>
+</filter-mapping>
+<filter-mapping>
+    <filter-name>ResourceCachingFilter</filter-name>
+    <url-pattern>*.swf</url-pattern>
+</filter-mapping>
+----
+
+
+=== `WicketFilter`
+
+NOTE: WIP
+
+
+definition:
+
+[source,xml]
+----
+<filter>
+    <filter-name>WicketFilter</filter-name>
+    <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
+    <init-param>
+        <param-name>applicationClassName</param-name>   <!--1-->
+        <param-value>domainapp.webapp.SimpleApplication</param-value>
+    </init-param>
+</filter>
+----
+<1> specify the application (subclass of `IsisWicketApplication`) to use
+
+mapping:
+
+[source,xml]
+----
+<filter-mapping>
+    <filter-name>WicketFilter</filter-name>
+    <url-pattern>/wicket/*</url-pattern>
+</filter-mapping>
+----
+
+This filter reads one context parameter:
+[source,xml]
+----
+<context-param>
+    <param-name>configuration</param-name>
+    <param-value>deployment</param-value>   <!--1-->
+</context-param>
+----
+<1> alternatively set to "development"; see xref:rg.adoc#_rg_runtime_deployment-types[deployment types] for further discussion.
+
+
+=== `IsisSessionFilter`
+
+The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object.  It is only required for the Restful Objects viewer.
+
+[source,xml]
+----
+<filter>
+    <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+    <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
+    <init-param>
+        <param-name>authenticationSessionStrategy</param-name>  <!--1-->
+        <param-value>
+            org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
+        </param-value>
+    </init-param>
+    <init-param>
+        <param-name>whenNoSession</param-name>                  <!--2-->
+        <param-value>basicAuthChallenge</param-value>
+    </init-param>
+    <!--
+    <init-param>
+        <param-name>restricted</param-name>                     <!--3-->
+        <param-value>...</param-value>
+    </init-param>
+    <init-param>
+        <param-name>redirectToOnException</param-name>          <!--4-->
+        <param-value>...</param-value>
+    </init-param>
+    -->
+</filter>
+----
+<1> pluggable strategy for determining what the authentication session (credentials) are of the request
+<2> what the servlet should do if no existing session was found; typically a 401, or can issue a Basic Auth challenge
+<3> List of paths that are allowed through even if not authenticated.  The servlets mapped to these paths are expected to be able to deal with there being no session. Typically they will be logon pages.
+<4> where to redirect to if an exception occurs.
+
+
+This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
+
+[source,xml]
+----
+<filter-mapping>
+    <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+    <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+</filter-mapping>
+----
+
+
+
+
+=== `IsisTransactionFilterForRestfulObjects`
+
+NOTE: WIP
+
+definition:
+
+[source,xml]
+----
+<filter>
+    <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
+    <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
+</filter>
+----
+
+This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
+
+[source,xml]
+----
+<filter-mapping>
+    <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
+    <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+</filter-mapping>
+----
+
+
+
+[[_rg_web-xml_context-parameters]]
+== Configuration Files
+
+However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will read a number of configuration files, such as `isis.properties`.
+
+By default these are read from `WEB-INF` directory.
+
+    <context-param>
+      <param-name>isis.config.dir</param-name>
+      <param-value>location of your config directory if fixed</param-value>
+    </context-param>
+    -->
+
+
+    <!--
+    determines which additional configuration files to search for
+     -->
+    <context-param>
+        <param-name>isis.viewers</param-name>
+        <param-value>wicket,restfulobjects</param-value>
+    </context-param>
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc b/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
new file mode 100644
index 0000000..3c0994f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_tg_pet-clinic.adoc
@@ -0,0 +1,557 @@
+[[_ug_tutorials_pet-clinic]]
+= Pet Clinic
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+It consists of just three domain classes (http://yuml.me/edit/3db2078c[http://yuml.me/3db2078c]):
+
+image::{_imagesdir}tutorials/pet-clinic/domain-model.png[link="{_imagesdir}tutorials/pet-clinic/domain-model.png"]
+
+
+This supports the following use cases:
+
+* register a Pet
+* register an Owner
+* maintain a Pet's details
+* check in a Pet to visit the clinic
+* enter a diagnosis
+
+check out a Pet to visit the clinic
+
+Either follow along or check out the tags from the corresponding https://github.com/danhaywood/isis-app-petclinic[github repo].
+
+== Prerequisites
+
+You'll need:
+
+* Java 7 JDK
+* http://maven.apache.org/[Maven] 3.2.x
+* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
+
+
+
+
+== Run the archetype
+
+Throughout this tutorial you can, if you wish, just checkout from the github repo wherever you see a "git checkout" note:
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/249abe476797438d83faa12ff88365da2c362451
+----
+
+====
+
+[NOTE]
+====
+This tutorial was developed against Apache Isis 1.8.0-SNAPSHOT.  Since then 1.8.0 has been released, so simply replace "1.8.0-SNAPSHOT" for "1.8.0" wherever it appears in the `pom.xml` files.
+====
+
+
+Run the simpleapp archetype to build an empty Isis application:
+
+
+[source,bash]
+----
+mvn archetype:generate  \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=simpleapp-archetype \
+    -D archetypeVersion=1.8.0 \
+    -D groupId=com.mycompany \
+    -D artifactId=petclinic \
+    -D version=1.0-SNAPSHOT \
+    -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+    -B
+----
+
+This will generate the app in a `petclinic` directory. Move the contents back:
+
+[source,bash]
+----
+mv petclinic/* .
+rmdir petclinic
+----
+
+
+
+
+== Build and run
+
+Start off by building the app from the command line:
+
+[source,bash]
+----
+mvn clean install
+----
+
+Once that's built then run using:
+
+[source,bash]
+----
+mvn antrun:run -P self-host
+----
+
+A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
+
+Alternatively, you can run using the mvn-jetty-plugin:
+
+[source,bash]
+----
+mvn jetty:run
+----
+
+This will accomplish the same thing, though the webapp is mounted at a slightly different URL
+
+
+
+
+== Using the app
+
+Navigate to the Wicket UI (eg http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
+
+image::{_imagesdir}tutorials/pet-clinic/010-01-login-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-01-login-page.png"]
+
+
+
+The home page should be shown:
+
+image::{_imagesdir}tutorials/pet-clinic/010-02-home-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-02-home-page.png"]
+
+
+
+Install the fixtures (example test data) using the `Prototyping` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png"]
+
+
+
+List all objects using the `Simple Objects` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png"]
+
+
+To return the objects created:
+
+image::{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png"]
+
+
+
+Experiment some more, to:
+
+* create a new object
+* list all objects
+
+Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
+
+
+
+
+== Dev environment
+
+Set up xref:cg.adoc#_cg_ide[an IDE] and import the project to be able to run and debug the app.
+
+Then set up a launch configuration so that you can run the app from within the IDE. To save having to run the fixtures
+every time, specify the following system properties:
+
+[source,bash]
+----
+-Disis.persistor.datanucleus.install-fixtures=true -Disis.fixtures=fixture.simple.scenario.SimpleObjectsFixture
+----
+
+For example, here's what a launch configuration in IntelliJ idea looks like:
+
+image::{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png"]
+
+
+
+where the "before launch" maven goal (to run the DataNucleus enhancer) is defined as:
+
+
+image::{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png[width="400px",link="{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png"]
+
+
+
+
+== Explore codebase
+
+Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
+
+* `petclinic` : parent module
+* `petclinic-dom`: domain objects module
+** entity: `dom.simple.SimpleObject`
+** repository: `dom.simple.SimpleObjects`
+* `petclinic-fixture`: fixtures module
+** fixture script:`fixture.simple.SimpleObjectsFixture`
+* `petclinic-integtests`: integration tests module
+* `petclinic-webapp`: webapp module
+** (builds the WAR file)
+
+
+
+
+== Testing
+
+Testing is of course massively important, and Apache Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
+
+* `myapp-dom` unit tests
+* run
+* inspect, eg
+ - `SimpleObjectTest`
+* `myapp-integtests` integration tests
+* run
+* inspect, eg:
+** `integration.tests.smoke.SimpleObjectsTest`
+** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
+* generated report, eg
+ - `myapp/integtests/target/cucumber-html-report/index.html`
+** change test in IDE, re-run (in Maven)
+
+If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
+
+
+
+
+== Update POM files
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/68904752bc2de9ebb3c853b79236df2b3ad2c944
+----
+
+====
+
+The POM files generated by the simpleapp archetype describe the app as "SimpleApp". Update them to say "PetClinic" instead.
+
+
+
+
+== Delete the BDD specs
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/9046226249429b269325dfa2baccf03635841c20
+----
+
+====
+
+
+During this tutorial we're going to keep the integration tests in-sync with the code, but we're going to stop short of writing BDD/Cucumber specs.
+
+Therefore delete the BDD feature spec and glue in the `integtest` module:
+
+* `integration/specs/*`
+* `integration/glue/*`
+
+
+
+
+== Rename artifacts
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/bee3629c0b64058f939b6dd20f226be31810fc66
+----
+
+====
+
+
+Time to start refactoring the app. The heart of the PetClinic app is the `Pet` concept, so go through the code and refactor. While we're at it, refactor the app itself from "SimpleApp" to "PetClinicApp".
+
+See the git commit for more detail, but in outline, the renames required are:
+
+* in the `dom` module's production code
+** `SimpleObject` -&gt; `Pet` (entity)
+** `SimpleObjects` -&gt; `Pets` (repository domain service)
+** `SimpleObject.layout.json` -&gt; `Pet.layout.json` (layout hints for the `Pet` entity)
+** delete the `SimpleObject.png`, and add a new `Pet.png` (icon shown against all `Pet` instances).
+* in the `dom` module's unit test code
+** `SimpleObjectTest` -&gt; `PetTest` (unit tests for `Pet` entity)
+** `SimpleObjectsTest` -&gt; `PetsTest` (unit tests for `Pets` domain service)
+* in the `fixture` module:
+** `SimpleObjectsFixturesService` -&gt; `PetClinicAppFixturesService` (rendered as the prototyping menu in the UI)
+** `SimpleObjectsTearDownService` -&gt; `PetClinicAppTearDownService` (tear down all objects between integration tests)
+** `SimpleObjectAbstract` -&gt; `PetAbstract` (abstract class for setting up a single pet object
+*** and corresponding subclasses to set up sample data (eg `PetForFido`)
+** `SimpleObjectsFixture` -&gt; `PetsFixture` (tear downs system and then sets up all pets)
+* in the `integtest` module:
+** `SimpleAppSystemInitializer` -&gt; `PetClinicAppSystemInitializer` (bootstraps integration tests with domain service/repositories)
+** `SimpleAppIntegTest` -&gt; `PetClinicAppIntegTest` (base class for integration tests)
+** `SimpleObjectTest` -&gt; `PetTest` (integration test for `Pet` entity)
+** `SimpleObjectsTest` -&gt; `PetsTest` (integration test for `Pets` domain service)
+* in the `webapp` module:
+** `SimpleApplication` -&gt; `PetClinicApplication`
+** update `isis.properties`
+** update `web.xml`
+
+
+Note that `Pet` has both both Isis and JDO annotations:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(identityType=IdentityType.DATASTORE) // <1>
+@javax.jdo.annotations.DatastoreIdentity(                                      // <2>
+        strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
+         column="id")
+@javax.jdo.annotations.Version(                                                // <3>
+        strategy=VersionStrategy.VERSION_NUMBER,
+        column="version")
+@javax.jdo.annotations.Unique(name="Pet_name_UNQ", members = {"name"})         // <4>
+@ObjectType("PET")                                                             // <5>
+@Bookmarkable                                                                  // <6>
+public class Pet implements Comparable<Pet> {
+    ...
+}
+----
+
+where:
+
+<1> `@PersistenceCapable` and
+<2> `@DatastoreIdentity` specify a surrogate `Id` column to be used as the primary key
+<3> `@Version` provides support for optimistic locking
+<4> `@Unique` enforces a uniqueness constraint so that no two `Pet`s can have the same name (unrealistic, but can refactor later)
+<5> `@ObjectType` is used by Apache Isis for its own internal "OID" identifier; this also appears in the URL in Apache Isis' Wicket viewer and REST API
+<6> `@Bookmarkable` indicates that the object can be automatically bookmarked in Apache Isis' Wicket viewer
+
+[NOTE]
+====
+The `@ObjectType` and `@Bookmarkable` annotations have since been deprecated, replaced with `@DomainObject(objectType=...)` and `@DomainObjectLayout(bookmarking=...)`
+====
+
+
+The `Pets` domain service also has Isis annotations:
+
+[source,java]
+----
+@DomainService(repositoryFor = Pet.class)
+@DomainServiceLayout(menuOrder = "10")
+public class Pets {
+    ...
+}
+----
+
+where:
+
+* `DomainService` indicates that the service should be instantiated automatically (as a singleton)
+* `DomainServiceLayout` provides UI hints, in this case the positioning of the menu for the actions provided by the service
+
+To run the application will require an update to the IDE configuration, for the changed name of the fixture class:
+
+
+image::{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png"]
+
+
+Running the app should now show `Pet`s:
+
+image::{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png"]
+
+
+
+
+
+== Update package names
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55ec36e520191f5fc8fe7f5b89956814eaf13317
+----
+
+====
+
+
+
+The classes created by the simpleapp archetype are by default in the `simple` package. Move these classes to `pets` package instead. Also adjust package names where they appear as strings:
+
+* in `PetClinicAppFixturesService`, change the package name from "fixture.simple" to "fixture.pets".
+* in `PetClinicAppSystemInitializer`, change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
+* in `WEB-INF/isis.properties`, similarly change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
+
+To run the application will require a further update to the IDE configuration, for the changed package of the fixture class:
+
+
+image::{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png"]
+
+
+
+== Add `PetSpecies` enum
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55c9cd28ff960220719b3dc7cb8abadace8d0829
+----
+
+====
+
+
+Each `Pet` is of a particular species. Model these as an enum called `PetSpecies`:
+
+[source,java]
+----
+public enum PetSpecies {
+    Cat,
+    Dog,
+    Budgie,
+    Hamster,
+    Tortoise
+}
+----
+
+Introduce a new property on `Pet` of this type:
+
+[source,java]
+----
+public class Pet {
+    ...
+    private PetSpecies species;
+    @javax.jdo.annotations.Column(allowsNull = "false")
+    public PetSpecies getSpecies() { return species; }
+    public void setSpecies(final PetSpecies species) { this.species = species; }
+    ...
+}
+----
+
+Update fixtures, unit tests and integration tests.
+
+
+
+
+== Icon to reflect pet species
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/2212765694693eb463f8fa88bab1bad154add0cb
+----
+
+====
+
+
+Rather than using a single icon for a domain class, instead a different icon can be supplied for each instance. We can therefore have different icon files for each pet, reflecting that pet's species.
+
+[source,java]
+----
+public class Pet {
+    ...
+    public String iconName() {
+        return getSpecies().name();
+    }
+    ...
+}
+----
+
+Download corresponding icon files (`Dog.png`, `Cat.png` etc)
+
+Running the app shows the `Pet` and its associated icon:
+
+image::{_imagesdir}tutorials/pet-clinic/050-01-list-all.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-01-list-all.png"]
+
+
+
+with the corresponding view of the `Pet`:
+
+image::{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png"]
+
+
+== Add pet's `Owner`
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/6f92a8ee8e76696d005da2a8b7a746444d017546
+----
+
+====
+
+
+Add the `Owner` entity and corresponding `Owners` domain service (repository). Add a query to find `Order`s by name:
+
+[source,java]
+----
+...
+@javax.jdo.annotations.Queries( {
+        @javax.jdo.annotations.Query(
+                name = "findByName", language = "JDOQL",
+                value = "SELECT "
+                        + "FROM dom.owners.Owner "
+                        + "WHERE name.matches(:name)")
+})
+public class Owner ... {
+    ...
+}
+----
+
+and `findByName(...)` in `Owners`:
+
+[source,java]
+----
+public class Owners {
+    ...
+    public List<Owner> findByName(
+            @ParameterLayout(named = "Name")
+            final String name) {
+        final String nameArg = String.format(".*%s.*", name);
+        final List<Owner> owners = container.allMatches(
+                new QueryDefault<>(
+                        Owner.class,
+                        "findByName",
+                        "name", nameArg));
+        return owners;
+    }
+    ...
+}
+----
+
+Add an `owner` property to `Pet`, with supporting `autoCompleteXxx()` method (so that available owners are shown in a drop-down list box):
+
+[source,java]
+----
+public class Pet ... {
+    ...
+    private Owner owner;
+    @javax.jdo.annotations.Column(allowsNull = "false")
+    public Owner getOwner() { return owner; }
+    public void setOwner(final Owner owner) { this.owner = owner; }
+    public Collection<Owner> autoCompleteOwner(final @MinLength(1) String name) {
+        return owners.findByName(name);
+    }
+    ...
+}
+----
+
+Also updated fixture data to set up a number of `Owner`s, and associate each `Pet` with an `Owner`. Also add unit tests and integration tests for `Owner`/`Owners` and updated for `Pet`/`Pets`.
+
+When running the app, notice the new `Owners` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png"]
+
+which when invoked returns all `Owner` objects:
+
+image::{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png"]
+
+
+Each `Pet` also indicates its corresponding `Owner`:
+
+image::{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png"]
+
+
+And, on editing a `Pet`, a new `Owner` can be specified using the autoComplete:
+
+image::{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png"]
+

[05/10] isis git commit: ISIS-1133: pulling together the contributors guide.

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc
deleted file mode 100644
index 262285c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc
+++ /dev/null
@@ -1,683 +0,0 @@
-[[_ug_tutorials_stop-scaffolding-start-coding]]
-= Stop scaffolding, start coding
-:Notice: 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.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This is a half-day tutorial on developing domain-driven apps using Apache Isis.  Actually, you could probably spend a full day working through this tutorial if you wanted to, so pick and choose the bits that look interesting.
-
-There's a bit of overlap with the xref:ug.adoc#_ug_tutorials_pet-clinic[Pet Clinic] tutorial initially, but it then sets off on its own.
-
-
-
-== Prerequisites
-
-You'll need:
-
-* Java 7 JDK
-* http://maven.apache.org/[Maven] 3.2.x
-* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
-
-
-
-== Run the archetype
-
-Run the simpleapp archetype to build an empty Isis application:
-
-[source,bash]
-----
-mvn archetype:generate  \
-    -D archetypeGroupId=org.apache.isis.archetype \
-    -D archetypeArtifactId=simpleapp-archetype \
-    -D archetypeVersion=1.8.0 \
-    -D groupId=com.mycompany \
-    -D artifactId=myapp \
-    -D version=1.0-SNAPSHOT \
-    -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
-    -B
-----
-
-
-
-
-== Build and run
-
-Start off by building the app from the command line:
-
-[source,bash]
-----
-cd myapp
-mvn clean install
-----
-
-Once that's built then run using:
-
-[source,bash]
-----
-mvn antrun:run -P self-host
-----
-
-A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
-
-Alternatively, you can run using the mvn-jetty-plugin:
-
-[source,bash]
-----
-mvn jetty:run
-----
-
-This will accomplish the same thing, though the webapp is mounted at a slightly different URL
-
-
-
-
-== Using the app
-
-Navigate to the Wicket UI (eg link:http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
-
-Once at the home page:
-
-* install fixtures
-* list all objects
-* create a new object
-* list all objects
-
-Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
-
-
-
-
-== Dev environment
-
-Set up link:dg.adoc[an IDE] and import the project to be able to run and debug the app.
-
-Then set up a launch configuration and check that you can:
-
-* Run the app from within the IDE
-* Run the app in debug mode
-* Run with different deploymentTypes; note whether prototype actions (those annotated xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action(restrictTo=PROTOTYPING`]) are available or not:
-* `--type SERVER_PROTOTYPE`
-* `--type SERVER`
-
-
-
-
-== Explore codebase
-
-Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
-
-* `myapp` : parent module
-* `myapp-dom`: domain objects module
-* entity: `dom.simple.SimpleObject`
-* repository: `dom.simple.SimpleObjects`
-* `myapp-fixture`: fixtures module
-* fixture script:`fixture.simple.SimpleObjectsFixture`
-* `myapp-integtests`: integration tests module
-* `myapp-webapp`: webapp module
-* (builds the WAR file)
-
-
-
-
-== Testing
-
-Testing is of course massively important, and Apache Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
-
-* `myapp-dom` unit tests
-* run
-* inspect, eg
- - `SimpleObjectTest`
-* `myapp-integtests` integration tests
-* run
-* inspect, eg:
-** `integration.tests.smoke.SimpleObjectsTest`
-** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
-* generated report, eg
- - `myapp/integtests/target/cucumber-html-report/index.html`
-** change test in IDE, re-run (in Maven)
-
-If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
-
-
-
-
-== Prototyping
-
-Although testing is important, in this tutorial we want to concentrate on how to write features and to iterate quickly. So for now, exclude the `integtests` module. Later on in the tutorial we'll add the tests back in so you can learn how to write automated tests for the features of your app.
-
-In the parent `pom.xml`:
-
-[source,xml]
-----
-<modules>
-    <module>dom</module>
-    <module>fixture</module>
-    <module>integtests</module>
-    <module>webapp</module>
-</modules>
-----
-
-change to:
-
-[source,xml]
-----
-<modules>
-    <module>dom</module>
-    <module>fixture</module>
-    <!--
-    <module>integtests</module>
-    -->
-    <module>webapp</module>
-</modules>
-----
-
-
-
-
-== Build a domain app
-
-The remainder of the tutorial provides guidance on building a domain application. We don't mandate any particular design, but we suggest one with no more than 3 to 6 domain entities in the first instance. If you're stuck for ideas, then how about:
-
-* a todo app (``ToDoItem``s)
-* a pet clinic (`Pet`, `Owner`, `PetSpecies`, `Visit`)
-* a library (`Book`, `Title`, `LibraryMember`, `Loan`, `Reservation`)
-* a holiday cottage rental system
-* a scrum/kanban system (inspired by Trello)
-* a meeting planner (inspired by Doodle)
-* (the domain model for) a CI server (inspired by Travis/Jenkins)
-* a shipping system (inspired by the example in the DDD "blue" book)
-* a system for ordering coffee (inspired by Restbucks, the example in "Rest in Practice" book)
-
-Hopefully one of those ideas appeals or sparks an idea for something of your own.
-
-
-
-
-== Domain entity
-
-Most domain objects in Apache Isis applications are persistent entities. In the simpleapp archetype the `SimpleObject` is an example. We can start developing our app by refactoring that class:
-
-* rename the `SimpleObject` class
-** eg rename to `Pet`
-* if required, rename the `SimpleObject` class' `name` property
-** for `Pet`, can leave `name` property as is
-* specify a xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[title]
-* specify an xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[icon]
-* make the entity bookmarkable by adding the xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`] attribute.
-* confirm is available from bookmark panel (top-left of Wicket UI)
-
-
-
-
-== Domain service
-
-Domain services often act as factories or repositories to entities; more generally can be used to "bridge across" to other domains/bounded contexts. Most are application-scoped, but they can also be request-scoped if required.
-
-In the simpleapp archetype the `SimpleObjects` service is a factory/repository for the original `SimpleObject` entity. For our app it therefore makes sense to refactor that class into our own first service:
-
-* rename the `SimpleObjects` class
-** eg rename to `Pets`
-* review `create` action (acting as a factory)
-** as per the docs describing xref:ug.adoc#_ug_how-tos_crud[how to create or delete objects]
-* rename if you wish
-** eg `newPet(...)` or `addPet(...)`
-* review `listAll` action (acting as a repository)
-* as per the docs describing xref:ug.adoc#_ug_how-tos_crud[how to write a custom repository]
-* note the annotations on the corresponding domain class (originally called `SimpleObject`, though renamed by now, eg to `Pet`)
-* rename if you wish
-** eg `listPets()`
-* note the xref:rg.adoc#_rg_annotations_manpage-DomainService[`@DomainService`] annotation
-* optional: add an action to a return subset of objects
-** use the JDO `@Query` annotation
-** see for example the Isisaddons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF), see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L93[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItems.java#L63[here]
-
-
-
-
-== Fixture scripts
-
-Fixture scripts are used to setup the app into a known state. They are great for demo's and as a time-saver when implementing a feature, and they can also be reused in automated integration tests. We usually also have a fixture script to zap all the (non-reference) data (or some logical subset of the data)
-
-* rename the `SimpleObjectsTearDownFixture` class
-* and update to delete from the appropriate underlying database table(s)
-* use the injected xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] domain service.
-* refactor/rename the fixture script classes that create instances your entity:
-* `RecreateSimpleObjects`, which sets up a set of objects for a given scenario
-* `SimpleObjectCreate` which creates a single object
-* note that domain services can be injected into these fixture scripts
-
-
-
-
-== Actions
-
-Most business functionality is implemented using actions� basically a `public` method accepting domain classes and primitives as its parameter types. The action can return a domain entity, or a collection of entities, or a primitive/String/value, or void. If a domain entity is returned then that object is rendered immediately; if a collection is returned then the Wicket viewer renders a table. Such collections are sometimes called "standalone" collections.
-
-* write an action to update the domain property (originally called `SimpleObject#name`, though renamed by now)
-* use the xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`@ParameterLayout(named=...)`] annotation to specify the name of action parameters
-* use the xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action(semanticsOf=...)`]  annotation to indicate the semantics of the action (safe/query-only, idempotent or non-idempotent)
-* annotate safe action as bookmarkable using xref:rg.adoc#_rg_annotations_manpage-ActionLayout_bookmarking[`@ActionLayout(bookmarking=...)`]
-* confirm is available from bookmark panel (top-left of Wicket UI)
-* optional: add an action to clone an object
-
-
-
-
-== REST API
-
-As well as exposing the Wicket viewer, Isis also exposes a REST API (an implementation of the http://restfulobjects.org[Restful Objects spec]). All of the functionality of the domain object model is available through this REST API.
-
-* add Chrome extensions
-* install https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Postman]
-* install https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en[JSON-View]
-* browse to Wicket viewer, install fixtures
-* browse to the http://localhost:8080/restful[http://localhost:8080/restful] API
-* invoke the service to list all objects
-* services
-* actions
-* invoke (invoking 0-arg actions is easy; the Restful Objects spec defines how to invoke N-arg actions)
-
-
-
-
-== Specify Action semantics
-
-The semantics of an action (whether it is safe/query only, whether it is idempotent, whether it is neither) can be specified for each action; if not specified then Isis assumes non-idempotent. In the Wicket viewer this matters in that only query-only actions can be bookmarked or used as contributed properties/collections. In the RESTful viewer this matters in that it determines the HTTP verb (GET, PUT or POST) that is used to invoke the action.
-
-* experiment changing xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action(semantics=...)`] on actions
-* note the HTTP methods exposed in the REST API change
-* note whether the non-safe actions are bookmarkable (assuming that it has been annotated with `@ActionLayout(bookmarking=...)`, that is).
-
-
-
-
-== Value properties
-
-Domain entities have state: either values (primitives, strings) or references to other entities. In this section we explore adding some value properties
-
-* add some xref:ug.adoc#_ug_how-tos_class-structure_properties[value properties]; also:
-* for string properties
-** use the xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_multiLine[`@Property(multiLine=...)`] annotation to render a text area instead of a text box
-** use the xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
-** use joda date/time properties, bigdecimals and blob/clob properties
-* use the xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Column(allowsNull=...)`] annotation specify whether a property is optional or mandatory
-* use enums for properties (eg as used in the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp], see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L207[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L266[here])
-* update the corresponding domain service for creating new instances
-* for all non-optional properties will either need to prompt for a value, or calculate some suitable default
-* change the implementation of title, if need be
-* revisit the title, consider whether to use the xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`] annotation
-** rather than the xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] `title()` method
-* order the properties using the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
-** see also the docs on xref:rg.adoc#_rg_object-layout_static[static layouts]
-* use the xref:rg.adoc#_rg_annotations_manpage-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
-** do the same for parameters using xref:rg.adoc#_rg_annotations_manpage-ParameterLayout[`@ParameterLayout`]
-
-
-
-
-== Reference properties
-
-Domain entities can also reference other domain entities. These references may be either scalar (single-valued) or vector (multi-valued). In this section we focus on scalar reference properties.
-
-* add some xref:ug.adoc#_ug_how-tos_class-structure_properties[reference properties]
-* update the corresponding domain service (for creation actoin)
-* use different techniques to obtain references (shown in drop-down list box)
-** use the xref:rg.adoc#_rg_annotations_manpage-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
-** use a xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`] supporting method
-*** on a property
-*** on an action parameter
-** use a xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method
-*** on a property
-*** on an action parameter
-
-
-
-
-== Usability: Defaults
-
-Quick detour: often we want to set up defaults to go with choices. Sensible defaults for action parameters can really improve the usability of the app.
-
-* Add xref:ug.adoc#_ug_how-tos_drop-downs-and-defaults[defaults] for action parameters
-
-
-
-
-== Collections
-
-Returning back to references, Isis also supports vector (multi-valued) references to another object instances� in other words collections. We sometimes called these "parented" collections (to distinguish from a "standalone" collection as returned from an action)
-
-* Ensure that all domain classes implement `java.lang.Comparable`
-** use the xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
-*** you can also `equals()`, `hashCode()`, `toString()`
-* Add a xref:ug.adoc#_ug_how-tos_class-structure_collections[collection] to one of the entities
-** Use `SortedSet` as the class
-** Use the xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
-* optional: use the xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
-
-
-
-
-
-== Actions and Collections
-
-The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
-
-* Add domain actions to add/remove from the collection
-* to create objects, xref:ug.adoc#_ug_how-tos_class-structure_inject-services[inject] associated domain service
-** generally we recommend using the xref:rg.adoc#_rg_annotations_manpage-Inject[`@Inject`] annotation with either private or default visibility
-* the service itself should use xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
-* use the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
-
-
-
-
-== CSS UI Hints
-
-CSS classes can be associated with any class member (property, collection, action). But for actions in particular:
-
-* the bootstrap "btn" CSS classes can be used using the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout(cssClass=...)`] annotation
-
-*  the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
-
-It's also possible to use Font Awesome icons for the xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[domain object icon].
-
-So:
-- for some of the actions of your domain services or entities, annotate using `@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`
-
-
-
-
-== Dynamic Layout
-
-Up to this point we've been using annotations (`@MemberOrder`, `@MemberGroupLayout`, `@Named`, `@PropertyLayout`, `@ParameterLayout`, `@ActionLayout` and so on) for UI hints. However, the feedback loop is not good: it requires us stopping the app, editing the code, recompiling and running again. So instead, all these UI hints (and more) can be specified dynamically, using a corresponding `.layout.json` file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run&gt;Reload Changed Classes):
-
-* Delete the various hint annotations and instead specify layout hints using a xref:rg.adoc#_rg_object-layout_dynamic[.layout.json] file.
-
-
-
-
-== Business rules
-
-Apache Isis excels for domains where there are complex business rules to enforce. The UI tries not to constrain the user from navigating around freely, however the domain objects nevertheless ensure that they cannot change into an invalid state. Such rules can be enforced either declaratively (using annotations) or imperatively (using code). The objects can do this in one of three ways:
-
-* visibility: preventing the user from even seeing a property/collection/action
-* usability: allowing the user to view a property/collection/action but not allowing the user to change it
-* validity: allowing the user to modify the property/invoke the action, but validating that the new value/action arguments are correct before hand.
-
-Or, more pithily: "see it, use it, do it"
-
-
-=== See it!
-
-* Use the xref:rg.adoc#_rg_annotations_manpage-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
-** likewise xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[`@Collection(hidden=...)`] for collections
-** the xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`]  annotation can also be used and in many cases is to be preferred; the difference is that the latter means the member is not part of the Apache Isis metamodel.
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
-
-
-=== Use it!
-
-* Use the xref:rg.adoc#_rg_annotations_manpage-Property_editing[`Property(editing=...)`] annotation to make property read-only
-** likewise xref:rg.adoc#_rg_annotations_manpage-Collection_editing[`@Collection(editing=...)`] for collections
-** alternatively, use xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`@DomainObject(editing=...)`] to disable editing for all properties/collections
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
-
-
-=== Do it!
-
-* use the xref:rg.adoc#_rg_annotations_manpage-Property_regexPattern[`@Property(regexPattern=...)`] annotation to specify a regex pattern for properties, and use xref:rg.adoc#_rg_annotations_manpage-Parameter_regexPattern[`@Parameter(regexPattern=...)`] for parameters
-* use the xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a maxmum number of characters, and xref:rg.adoc#_rg_annotations_manpage-Parameter_maxLength[`@Parameter(maxLength=...)`] for parameters
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] supporting method on properties or action parameter
-* optional: for any data type:
-** use the xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
-
-
-
-
-== Home page
-
-The Wicket UI will automatically invoke the "home page" action, if available. This is a no-arg action of one of the domain services, that can return either an object (eg representing the current user) or a standalone action.
-
-* Add the xref:rg.adoc#_rg_annotations_manpage-HomePage[`@HomePage`] annotation to one (no more) of the domain services' no-arg actions
-
-
-
-
-== Clock Service
-
-To ensure testability, there should be no dependencies on system time, for example usage of `LocalDate.now()`. Instead the domain objects should delegate to the provided `ClockService`.
-
-* remove any dependencies on system time (eg defaults for date/time action parameters)
-* inject xref:rg.adoc#_rg_services-api_manpage-ClockService[`ClockService`]
-* call `ClockService.now()` etc where required.
-
-
-
-
-== Using Contributions
-
-One of Apache Isis' most powerful features is the ability for the UI to combine functionality from domain services into the representation of an entity. The effect is similar to traits or mix-ins in other languages, however the "mixing in" is done at runtime, within the Apache Isis metamodel. In Apache Isis' terminology, we say that the domain service action is contributed to the entity.
-
-Any action of a domain service that has a domain entity type as one of its parameter types will (by default) be contributed. If the service action takes more than one argument, or does not have safe semantics, then it will be contributed as an entity action. If the service action has precisely one parameter type (that of the entity) and has safe semantics then it will be contributed either as a collection or as a property (dependent on whether it returns a collection of a scalar).
-
-Why are contributions so useful? Because the service action will match not on the entity type, but also on any of the entity's supertypes (all the way up to `java.lang.Object`). That means that you can apply the http://en.wikipedia.org/wiki/Dependency_inversion_principle[dependency inversion principle] to ensure that the modules of your application have acyclic dependencies; but in the UI it can still appear as if there are bidirectional dependencies between those modules. The lack of bidirectional dependencies can help save your app degrading into a http://en.wikipedia.org/wiki/Big_ball_of_mud[big ball of mud].
-
-Finally, note that the layout of contributed actions/collections/properties can be specified using the `.layout.json` file (and it is highly recommended that you do so).
-
-=== Contributed Actions
-
-* Write a new domain service
-** by convention, called "XxxContributions"
-** annotate with xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)`]
-*** indicates that all of the service's actions should _not_ be included in the main application menu bar
-*** should be rendered "as if" an action of the entity
-* Write an action accepting &gt;1 args:
-** one being a domain entity
-** other being a primitive or String
-
-=== Contributed Collections
-
-* Write a new domain service (or update the one previously)
-* Write a query-only action accepting exactly 1 arg (a domain entity)
-* returning a collection, list or set
-* For this action:
-** add the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
-** should be rendered in the UI "as if" a collection of the entity
-* use `.layout.json` to position as required
-
-
-=== Contributed Properties
-
-* As for contributed collections, write a new domain service with a query-only action accepting exactly 1 arg (a domain entity); except:
-** returning a scalar value rather than a collection
-* For this action:
-** add the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
-* should be rendered in the UI "as if" a property of the entity
-* use `.layout.json` to position as required
-
-
-
-== Using the Event Bus
-
-Another way in which Apache Isis helps you keep your application nicely modularized is through its event bus. Each action invocation, or property modification, can be used to generate a succession of events that allows subscribers to veto the interaction (the see it/use it/do it rules) or, if the action is allowed, to perform work prior to the execution of the action or after the execution of the action.
-
-Under the covers Apache Isis uses the https://code.google.com/p/guava-libraries/wiki/EventBusExplained[Guava event bus] and subscribers (always domain services) subscribe by writing methods annotated with `@com.google.common.eventbus.Subscribe` annotation.
-
-By default the events generated are `ActionDomainEvent.Default` (for actions) and `PropertyDomainEvent.Default` (for properties). Subclasses of these can be specified using the xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action(domainEvent=...)`] or xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`Property(domainEvent=...)`] for properties.
-
-
-Using the guidance in the docs for the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]:
-
-* write a domain service subscriber to subscribe to events
-* use the domain service to perform log events
-* use the domain service to veto actions (hide/disable or validate)
-
-
-
-== Bulk actions
-
-Bulk actions are actions that can be invoked on a collection of actions, that is on collections returned by invoking an action. Actions are specified as being bulk actions using the xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@action(invokeOn=OBJECT_AND_COLLECTION)`] annotation.
-
-[NOTE]
-====
-Note that currently (1.8.0) only no-arg actions can be specified as bulk actions.
-====
-
-Thus:
-* Write a no-arg action for your domain entity, annotate with `@Action(invokeOn=...)`
-* Inject the xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`ActionInteractionContext`] (request-scoped) service
-* Use the `ActionInteractionContext` service to determine whether the action was invoked in bulk or as a regular action.
-* return null if invoked on a collection; the Wicket viewer will go back to the original collection
-** (if return non-null, then Wicket viewer will navigate to the object of the last invocation� generally not what is required)
-
-The similar xref:rg.adoc#_rg_services-api_manpage-Scratchpad[`Scratchpad`] (request-scoped) domain service is a good way to share information between bulk action invocations:
-
-* Inject the `Scratchpad` domain service
-* for each action, store state (eg a running total)
-* in the last invoked bulk action, perform some aggregate processing (eg calculate the average) and return
-
-
-
-
-== Performance tuning
-
-The xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`QueryResultsCache`] (request-scoped) domain service allows arbitrary objects to be cached for the duration of a request.
-
-This can be helpful for "naive" code which would normally make the same query within a loop.
-
-* optional: inject the `QueryResultsCache` service, invoke queries "through" the cache API
-* remember that the service is request-scoped, so it only really makes sense to use this service for code that invokes queries within a loop
-
-
-
-
-== Extending the Wicket UI
-
-Each element in the Wicket viewer (entity form, properties, collections, action button etc) is a component, each created by a internal API (`ComponentFactory`, described xref:ug.adoc#_ug_extending_wicket-viewer[here]). For collections there can be multiple views, and the Wicket viewer provides a view selector drop down (top right of each collection panel).
-
-Moreover, we can add additional views. In this section we'll explore some of these, already provided through http://www.isisaddons.org/[Isis addons] (not ASF).
-
-=== Excel download
-
-The https://github.com/isisaddons/isis-wicket-excel[Excel download add-on] allows the collection to be downloaded as an Excel spreadsheet (`.xlsx`).
-
-* Use the instructions on the add-on module's README to add in the excel download module (ie: update the POM).
-
-=== Fullcalendar2
-
-The https://github.com/isisaddons/isis-wicket-fullcalendar2[Fullcalendar2 download add-on] allows entities to be rendered in a full-page calendar.
-
-* Use the instructions on the add-on module's README to add in the fullcalendar2 module (ie: update the POM).
-* on one of your entities, implement either the `CalendarEventable` interface or the (more complex) `Calendarable` interface.
-* update fixture scripts to populate any new properties
-* when the app is run, a collection of the entities should be shown within a calendar view
-
-=== gmap3
-
-The https://github.com/isisaddons/isis-wicket-gmap3[Gmap3 download add-on] allows entities that implement certain APIs to be rendered in a full-page gmap3.
-
-* Use the instructions on the add-on module's README to add in the gmap3 module (ie: update the POM).
-* on one of your entities, implement the `Locatable` interface
-* update fixture scripts to populate any new properties
-* when the app is run, a collection of the entities should be shown within a map view
-
-
-
-
-== Add-on modules (optional)
-
-In addition to providing Wicket viewer extensions, http://www.isisaddons.org/[Isis addons] also has a large number of modules. These address such cross-cutting concerns as security, command (profiling), auditing and publishing.
-
-* (optional): follow the https://github.com/isisaddons/isis-module-security[security module] README or http://youtu.be/bj8735nBRR4[screencast]
-* (optional): follow the https://github.com/isisaddons/isis-module-command[command module] README or http://youtu.be/g01tK58MxJ8[screencast]
-* (optional): follow the https://github.com/isisaddons/isis-module-audit[auditing module] README or (the same) http://youtu.be/g01tK58MxJ8[screencast]
-
-
-
-
-== View models
-
-In most cases users can accomplish the business operations they need by invoking actions directly on domain entities. For some high-volume or specialized uses cases, though, there may be a requirement to bring together data or functionality that spans several entities.
-
-Also, if using Apache Isis' REST API then the REST client may be a native application (on a smartphone or tablet, say) that is deployed by a third party. In these cases exposing the entities directly would be inadvisable because a refactoring of the domain entity would change the REST API and probably break that REST client.
-
-To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
-
-* build a view model summarizing the state of the app (a "dashboard")
-* write a new `@HomePage` domain service action returning this dashboard viewmodel (and remove the `@HomePage` annotation from any other domain service if present)
-
-
-
-
-== Testing
-
-Up to this point we've been introducing the features of Isis and building out our domain application, but with little regard to testing. Time to fix that.
-
-
-=== Unit testing
-
-Unit testing domain entities and domain services is easy; just use JUnit and mocking libraries to mock out interactions with domain services.
-
-https://code.google.com/p/mockito/[Mockito] seems to be the current favourite among Java developers for mocking libraries, but if you use JMock then you'll find we provide a `JUnitRuleMockery2` class and a number of other utility classes, documented xref:ug.adoc#_ug_testing_unit-test-support[here].
-
-* write some unit tests (adapt from the unit tests in the `myapp-dom` Maven module).
-
-
-
-=== Integration testing
-
-Although unit tests are easy to write and fast to execute, integration tests are more valuable: they test interactions of the system from the outside-in, simulating the way in which the end-users use the application.
-
-Earlier on in the tutorial we commented out the `myapp-integtests` module. Let's commented it back in. In the parent `pom.xml`:
-
-[source,xml]
-----
-<modules>
-    <module>dom</module>
-    <module>fixture</module>
-    <!--
-    <module>integtests</module>
-    -->
-    <module>webapp</module>
-</modules>
-----
-
-change back to:
-
-[source,xml]
-----
-<modules>
-    <module>dom</module>
-    <module>fixture</module>
-    <module>integtests</module>
-    <module>webapp</module>
-</modules>
-----
-
-There will probably be some compile issues to fix up once you've done this; comment out all code that doesn't compile.
-
-Isis has great support for writing xref:ug.adoc#_ug_testing_integ-test-support[integration tests]; well-written integration tests should leverage fixture scripts and use the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`@WrapperFactory`] domain service.
-
-* use the tests from the original archetype and the documentation on the website to develop integration tests for your app's functionality.
-
-
-
-
-== Customising the REST API
-
-The REST API generated by Apache Isis conforms to the Restful Objects specification. Apache Isis 1.8.0 provides experimental support to allow the representations to be customized.
-
-* as per xref:ug.adoc#_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
-+
-[source,ini]
-----
-isis.viewer.restfulobjects.objectPropertyValuesOnly=true
-----
-
-
-
-
-== Configuring to use an external database
-
-If you have an external database available, then update the `pom.xml` for the classpath and update the JDBC properties in `WEB-INF\persistor.properties` to point to your database.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
deleted file mode 100644
index cfbb258..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
+++ /dev/null
@@ -1 +0,0 @@
-[[_ug_xxx]]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/cg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cg.adoc b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
new file mode 100644
index 0000000..e36e3df
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
@@ -0,0 +1,36 @@
+[[cg]]
+= Contributors Guide
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:numbered:
+
+
+[[_cg]]
+== Contributors' Guide
+
+This contributors' guide has three related audiences:
+
+* 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)
+
+* programmers who want to contribute back patches (bug fixes, new features) either to the codebase or the framework's documentation
+
+* committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.
+
+The developer' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*.  This guide also does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.
+
+
+include::_cg_ide.adoc[leveloffset=+1]
+include::_cg_ide-templates.adoc[leveloffset=+1]
+include::_cg_cmd-line.adoc[leveloffset=+1]
+include::_cg_isis-maven-plugin.adoc[leveloffset=+1]
+
+include::_cg_building-isis.adoc[leveloffset=+1]
+include::_cg_contributing.adoc[leveloffset=+1]
+include::_cg_policies.adoc[leveloffset=+1]
+
+include::_cg_asciidoc.adoc[leveloffset=+1]
+
+include::_cg_committers.adoc[leveloffset=+1]
+
+include::_cg_git-cookbook.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg.adoc b/adocs/documentation/src/main/asciidoc/guides/dg.adoc
deleted file mode 100644
index 07f4a4f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[dg]]
-= Development Environment Guide
-:Notice: 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.
-:_basedir: ../
-:_imagesdir: images/
-
-
-== Developers' Guide
-
-This developers' guide describes how to set up your development environment to develop your Apache Isis applications either within the xref:dg.adoc#_dg_intellij[IntelliJ] IDE, or within the xref:dg.adoc#_dg_eclipse[Eclipse] IDE, or from the xref:dg.adoc#_dg_cmd-line[command line].
-
-The developer' guide is _not_ intended as a reference manual; for that see the link:rg.html#[Reference Guide].  This guide also does _not_ describe how to actually build an Apache Isis application; for that see the link:ug.html#[Users' Guide].
-
-
-include::_dg_intellij.adoc[leveloffset=+1]
-include::_dg_eclipse.adoc[leveloffset=+1]
-include::_dg_cmd-line.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/building-isis/setting-up-git.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/building-isis/setting-up-git.png b/adocs/documentation/src/main/asciidoc/guides/images/building-isis/setting-up-git.png
new file mode 100644
index 0000000..5ed2a79
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/building-isis/setting-up-git.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow-2.png b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow-2.png
new file mode 100644
index 0000000..28cc822
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow-2.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.png b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.png
new file mode 100644
index 0000000..dde5573
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.pptx b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.pptx
new file mode 100644
index 0000000..e83367b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.pptx differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-cloning.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-cloning.png b/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-cloning.png
new file mode 100644
index 0000000..19c222d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-cloning.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-forking.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-forking.png b/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-forking.png
new file mode 100644
index 0000000..3f8ff75
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-forking.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/reference-classes/issue-in-more-detail.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-classes/issue-in-more-detail.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-classes/issue-in-more-detail.png
new file mode 100644
index 0000000..2297838
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-classes/issue-in-more-detail.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/jira-create-release-notes.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/jira-create-release-notes.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/jira-create-release-notes.png
new file mode 100644
index 0000000..2777532
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/jira-create-release-notes.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-release-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-release-1.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-release-1.png
new file mode 100644
index 0000000..a00a1ba
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-release-1.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-0.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-0.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-0.png
new file mode 100644
index 0000000..127d485
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-0.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-1.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-1.png
new file mode 100644
index 0000000..7266ea9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-1.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2.png
new file mode 100644
index 0000000..d4a985a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2a.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2a.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2a.png
new file mode 100644
index 0000000..894c168
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2a.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-3.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-3.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-3.png
new file mode 100644
index 0000000..8bc439c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-3.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-4.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-4.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-4.png
new file mode 100644
index 0000000..c3610b5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-4.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
index e53e216..60eb898 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -6,6 +6,7 @@
 :numbered:
 
 
+[[_rg]]
 == Reference Guide
 
 This reference guide describes in detail the various elements of the Apache Isis Programming Model.  Most notably these are the xref:rg.adoc#_rg_annotations[annotations] (such as `@DomainObject`), and the reserved and prefix xref:rg.adoc#_rg_methods[methods] (such as `title()` and `validate...()`); it also includes various utility and supporting xref:rg.adoc#_rg_classes[classes].
@@ -14,7 +15,8 @@ This guide also documents the domain services, both those that act as an xref:rg
 
 Also part of the reference manual are the details of how to influence the xref:rg.adoc#_rg_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it catalogues all the various xref:rg.adoc#_rg_runtime[configuration properties] available that influence the behaviour of the framework and the API domain services.
 
-This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the link:ug.html#[Users' Guide].  The reference guide also does _not_ explain how to setup your development environment; for that see the link:dg.html#[Developers' Guide].
+This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.  The reference guide also does _not_ explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
+
 
 
 
@@ -25,3 +27,4 @@ include::_rg_services-spi.adoc[leveloffset=+1]
 include::_rg_classes.adoc[leveloffset=+1]
 include::_rg_object-layout.adoc[leveloffset=+1]
 include::_rg_runtime.adoc[leveloffset=+1]
+include::_rg_web-xml.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
new file mode 100644
index 0000000..de41bcd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
@@ -0,0 +1,207 @@
+[[simpleapp-archetype]]
+= SimpleApp Archetype
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+The quickest way to get started with Apache Isis is to run the simple archetype.  This will generate a very simple one-class domain model, called `SimpleObject`, with a single property `name`.  There is also a corresponding `SimpleObjectRepository` domain service.  From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
+
+
+
+
+
+== Generating the App
+
+Create a new directory, and `cd` into that directory.
+
+Then run the following command:
+
+[source,bash]
+----
+mvn archetype:generate  \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=simpleapp-archetype \
+    -D archetypeVersion=1.8.0 \
+    -D groupId=com.mycompany \
+    -D artifactId=myapp \
+    -D version=1.0-SNAPSHOT \
+    -B
+----
+
+where:
+
+- `groupId` represents your own organization, and
+- `artifactId` is a unique identifier for this app within your organization.
+- `version` is the initial (snapshot) version of your app
+
+The archetype generation process will then run; it only takes a few seconds.
+
+
+
+
+=== Snapshot release
+
+We also maintain the archetype for the most current `-SNAPSHOT`; an app generated with this archetype will contain the latest features of Apache Isis, but the usual caveats apply: some features still in development may be unstable.
+
+The process is almost identical to that for stable releases, however the `archetype:generate` goal is called with slightly different arguments:
+
+[source,bash]
+----
+mvn archetype:generate  \
+    -D archetypeGroupId=org.apache.isis.archetype \
+    -D archetypeArtifactId=simpleapp-archetype \
+    -D archetypeVersion=1.9.0-SNAPSHOT \
+    -D groupId=com.mycompany \
+    -D artifactId=myapp \
+    -D version=1.0-SNAPSHOT \
+    -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+    -B
+----
+
+where as before:
+
+- `groupId` represents your own organization, and
+- `artifactId` is a unique identifier for this app within your organization.
+- `version` is the initial (snapshot) version of your app
+
+but also:
+
+- `archetypeVersion` is the SNAPSHOT version of Apache Isis.
+- `archetypeRepository` specifies the location of our snapshot repo (hosted on [CloudBees](http://www.cloudbees.com)), and
+
+The archetype generation process will then run; it only takes a few seconds.
+
+
+
+
+== Building the App
+
+Switch into the root directory of your newly generated app, and build your app:
+
+[source,bash]
+----
+cd myapp
+mvn clean install
+----
+
+where `myapp` is the `artifactId` entered above.
+
+
+
+
+== Running the App
+
+The `simpleapp` archetype generates a single WAR file, configured to run both the link:./guides/ug.html#_ug_wicket-viewer[Wicket viewer] and the link:./guides/ug.html#_ug_restfulobjects-viewer[Restful Objects viewer].   The archetype also configures the JDO/DataNucleus objectstore to use an in-memory HSQLDB connection.  
+
+Once you've built the app, you can run the WAR in a variety of ways. 
+
+The recommended approach when getting started is to run the self-hosting version of the WAR, allowing Apache Isis to run as a standalone app; for example:
+
+[source,bash]
+----
+java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar
+----
+
+
+
+This can also be accomplished using an embedded Ant target provided in the build script:
+
+
+[source,bash]
+----
+mvn -P self-host antrun:run
+----
+
+
+    
+The first is to simply deploying the generated WAR (`webapp/target/myapp-webapp-1.0-SNAPSHOT.war`) to a servlet container.
+
+
+Alternatively, you could run the WAR in a Maven-hosted Jetty instance, though you need to `cd` into the `webapp` module:
+
+[source,bash]
+----
+cd webapp
+mvn jetty:run -D jetty.port=9090
+----
+
+
+In the above, we've passed in a property to indicate a different port from the default port (8080).
+
+Note that if you use `mvn jetty:run`, then the context path changes; check the console output (eg [http://localhost:9090/myapp-webapp](http://localhost:9090/myapp-webapp)).
+
+Finally, you can also run the app by deploying to a standalone servlet container such as [Tomcat](http://tomcat.apache.org).
+
+
+
+
+=== With Fixtures
+
+It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory
+testing.  This is done by specifying a _fixture script_ on the command line:
+
+
+[source,bash]
+----
+java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar \
+     --initParam isis.persistor.datanucleus.install-fixtures=true  \
+     --initParam isis.fixtures=fixture.simple.SimpleObjectsFixture
+----
+
+    
+where (in the above example) `fixture.simple.SimpleObjectsFixture` is the fully qualified class name of the fixture 
+script to be run.
+
+
+
+
+== Using the App
+
+The archetype provides a welcome page that explains the classes and files generated, and provides detailed guidance and what to do next.
+
+The app itself is configured to run using shiro security, as configured in the `WEB-INF/shiro.ini` config file.  To log in, use `sven/pass`.
+
+
+
+== Modifying the App
+
+Once you are familiar with the generated app, you'll want to start modifying it.  Check out our the link:.guides/ug.html[Users' Guide], which has how-tos and a complete reference guide (as well as some background concepts and discussion of more advanced techniques).
+
+If you use IntelliJ or Eclipse, you'll also want to set up your IDE; this is also described in the link:cg.adoc#_cg_ide[Contributors' Guide].
+
+
+== App Structure
+
+As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
+
+
+.Table caption
+[cols="1,1a", options="header"]
+|===
+| Module 
+| Description
+
+
+|myapp
+|The parent (aggregator) module
+
+|myapp-dom
+|The domain object model, consisting of <tt>SimpleObject</tt> and <tt>SimpleObjects</tt> (repository) domain service.
+
+|myapp-fixture
+|Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
+
+|myapp-integtests
+|End-to-end integration tests, that exercise from the UI through to the database
+
+|myapp-webapp
+|Run as a webapp (from `web.xml`) using either the Wicket viewer or the RestfulObjects viewer
+
+|===
+
+
+If you run into issues, please don't hesitate to ask for help on the link:../../support.html[users mailing list].

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/tg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/tg.adoc b/adocs/documentation/src/main/asciidoc/guides/tg.adoc
new file mode 100644
index 0000000..20b6517
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/tg.adoc
@@ -0,0 +1,22 @@
+[[tg]]
+= Tutorials
+:Notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+
+
+[[_tg]]
+== Tutorials
+
+This page contains a couple of tutorials for you to follow.
+
+* the "petclinic" tutorial takes you step-by-step through building a simple application of just three classes.  There are example solutions in the github repo in case you get lost.
+
+* the "stop scaffolding, start coding" tutorial is taken from a conference workshop.  It has less hand-holding, but lists out the steps for you to follow.  It's a good cookbook to follow when you're readng to take things further.
+
+Have fun!
+
+
+
+include::_tg_pet-clinic.adoc[leveloffset=+1]
+include::_tg_stop-scaffolding-start-coding.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index 7a55ccb..497339e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -6,6 +6,7 @@
 :numbered:
 
 
+[[_ug]]
 == Users' Guide
 
 This users' guide introduces the xref:ug.adoc#_ug_core-concepts[core concepts] and ideas behind Apache Isis, tells you how to xref:ug.adoc#_ug_getting-started[get started] with a Maven archetype, and provides xref:ug.adoc#_ug_how-tos[how-to]s and xref:ug.adoc#_ug_more-advanced[more advanced] guidance on writing maintainable larger applications.
@@ -14,13 +15,13 @@ It goes on to discuss the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], both fr
 
 Later chapters discuss essential topics such as xref:ug.adoc#_ug_testing[testing] and how to xref:ug.adoc#_ug_deployment[deploy] your app, and discuss other ways in which you can xref:ug.adoc#_ug_extending[extend] or adapt the framework itself to your particular needs.
 
-The users' guide is _not_ intended as a reference manual; for that see the link:rg.html#[Reference Guide].  The users' guide also does _not_ explain how to setup your development environment; for that see the link:dg.html#[Developers' Guide].
+The users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*.  The users' guide also does _not_ explain how to setup your development environment; for that see the *link:cg.adoc#_cg[Contributors' Guide]*.
+
 
 
 
 include::_ug_core-concepts.adoc[leveloffset=+1]
 include::_ug_getting-started.adoc[leveloffset=+1]
-include::_ug_tutorials.adoc[leveloffset=+1]
 
 include::_ug_how-tos.adoc[leveloffset=+1]
 include::_ug_more-advanced.adoc[leveloffset=+1]
@@ -29,9 +30,8 @@ include::_ug_wicket-viewer.adoc[leveloffset=+1]
 include::_ug_restfulobjects-viewer.adoc[leveloffset=+1]
 include::_ug_security.adoc[leveloffset=+1]
 
-include::_ug_isis-maven-plugin.adoc[leveloffset=+1]
-include::_ug_deployment.adoc[leveloffset=+1]
 include::_ug_testing.adoc[leveloffset=+1]
+include::_ug_deployment.adoc[leveloffset=+1]
 include::_ug_headless-access.adoc[leveloffset=+1]
 include::_ug_extending.adoc[leveloffset=+1]
 include::_ug_troubleshooting.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/help.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/help.adoc b/adocs/documentation/src/main/asciidoc/help.adoc
index 280cc08..10d1367 100644
--- a/adocs/documentation/src/main/asciidoc/help.adoc
+++ b/adocs/documentation/src/main/asciidoc/help.adoc
@@ -16,7 +16,7 @@ pass:[<br/><br/><br/>]
 * link:https://issues.apache.org/jira/browse/ISIS[JIRA]
 * link:http://github.com/apache/isis[Github mirror]
 * link:http://stackoverflow.com/questions/tagged/isis[Stack Overflow] (tagged=isis)
-* link:contributing.html[How to contribute]
+* link:guides/cg.html#_cg_contributing[How to contribute]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/building-isis/setting-up-git.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/building-isis/setting-up-git.png b/adocs/documentation/src/main/asciidoc/images/building-isis/setting-up-git.png
deleted file mode 100644
index 5ed2a79..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/building-isis/setting-up-git.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow-2.png b/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow-2.png
deleted file mode 100644
index 28cc822..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow-2.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.png b/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.png
deleted file mode 100644
index dde5573..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.pptx b/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.pptx
deleted file mode 100644
index e83367b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.pptx and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/github-cloning.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/github-cloning.png b/adocs/documentation/src/main/asciidoc/images/contributing/github-cloning.png
deleted file mode 100644
index 19c222d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/github-cloning.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/github-forking.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/github-forking.png b/adocs/documentation/src/main/asciidoc/images/contributing/github-forking.png
deleted file mode 100644
index 3f8ff75..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/github-forking.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/jira-create-release-notes.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/jira-create-release-notes.png b/adocs/documentation/src/main/asciidoc/images/release-process/jira-create-release-notes.png
deleted file mode 100644
index 2777532..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/jira-create-release-notes.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-release-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-release-1.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-release-1.png
deleted file mode 100644
index a00a1ba..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-release-1.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-0.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-0.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-0.png
deleted file mode 100644
index 127d485..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-0.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-1.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-1.png
deleted file mode 100644
index 7266ea9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-1.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2.png
deleted file mode 100644
index d4a985a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2a.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2a.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2a.png
deleted file mode 100644
index 894c168..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2a.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-3.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-3.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-3.png
deleted file mode 100644
index 8bc439c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-3.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-4.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-4.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-4.png
deleted file mode 100644
index c3610b5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-4.png and /dev/null differ

[10/10] isis git commit: ISIS-1133: pulling together the contributors guide.

[da...@apache.org]

ISIS-1133: pulling together the contributors guide.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/8ad6101a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/8ad6101a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/8ad6101a

Branch: refs/heads/master
Commit: 8ad6101af5a107aef74d50f3f1c2d65fba2d9fa6
Parents: dfe4dcb
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Jul 10 08:39:57 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Jul 10 08:39:57 2015 +0100

----------------------------------------------------------------------
 adocs/documentation/README.adoc                 |   75 +-
 .../src/main/asciidoc/applying-patches.adoc     |   88 --
 .../src/main/asciidoc/building-isis.adoc        |  174 ---
 .../src/main/asciidoc/contributing.adoc         |  258 -----
 .../src/main/asciidoc/documentation.adoc        |  103 +-
 .../src/main/asciidoc/editor-templates.adoc     |   70 --
 .../src/main/asciidoc/git-cookbook.adoc         |  261 -----
 .../src/main/asciidoc/git-policy.adoc           |  101 --
 .../src/main/asciidoc/guides/_cg_asciidoc.adoc  |  208 ++++
 .../main/asciidoc/guides/_cg_building-isis.adoc |  174 +++
 .../src/main/asciidoc/guides/_cg_cmd-line.adoc  |    9 +
 .../guides/_cg_committers-applying-patches.adoc |   90 ++
 .../main/asciidoc/guides/_cg_committers.adoc    |   27 +
 ..._committers_cutting-a-release-one-pager.adoc |  240 ++++
 .../_cg_committers_cutting-a-release.adoc       | 1046 ++++++++++++++++++
 .../guides/_cg_committers_key-generation.adoc   |  571 ++++++++++
 .../guides/_cg_committers_pmc-notes.adoc        |   71 ++
 .../_cg_committers_recreating-an-archetype.adoc |  335 ++++++
 .../_cg_committers_release-checklist.adoc       |   86 ++
 ...ommitters_release-process-for-snapshots.adoc |   96 ++
 ...tters_verifying-releases-using-a-script.adoc |  152 +++
 ..._verifying-releases-using-creadur-tools.adoc |   46 +
 .../_cg_committers_verifying-releases.adoc      |  145 +++
 .../main/asciidoc/guides/_cg_contributing.adoc  |  255 +++++
 .../main/asciidoc/guides/_cg_git-cookbook.adoc  |  258 +++++
 .../main/asciidoc/guides/_cg_ide-templates.adoc |   69 ++
 .../src/main/asciidoc/guides/_cg_ide.adoc       |   16 +
 .../main/asciidoc/guides/_cg_ide_eclipse.adoc   |  134 +++
 .../main/asciidoc/guides/_cg_ide_intellij.adoc  |  398 +++++++
 .../asciidoc/guides/_cg_isis-maven-plugin.adoc  |    9 +
 .../src/main/asciidoc/guides/_cg_policies.adoc  |   14 +
 .../guides/_cg_policies_git-policy.adoc         |   98 ++
 .../guides/_cg_policies_versioning-policy.adoc  |   35 +
 .../src/main/asciidoc/guides/_dg_cmd-line.adoc  |    9 -
 .../src/main/asciidoc/guides/_dg_eclipse.adoc   |  136 ---
 .../src/main/asciidoc/guides/_dg_intellij.adoc  |  396 -------
 .../main/asciidoc/guides/_rg_annotations.adoc   |    2 +-
 .../_rg_annotations_manpage-ViewModel.adoc      |    2 +-
 ...classes_utility_manpage-ObjectContracts.adoc |    4 +-
 .../guides/_rg_methods_lifecycle_jdo-api.adoc   |    6 +-
 .../_rg_object-layout_application-menu.adoc     |    2 +-
 .../guides/_rg_object-layout_dynamic.adoc       |    2 +-
 .../src/main/asciidoc/guides/_rg_runtime.adoc   |    3 +-
 .../guides/_rg_runtime_deployment-types.adoc    |    2 +-
 .../_rg_runtime_specifying-components.adoc      |    2 +-
 .../asciidoc/guides/_rg_runtime_web-xml.adoc    |  463 --------
 .../src/main/asciidoc/guides/_rg_web-xml.adoc   |  463 ++++++++
 .../main/asciidoc/guides/_tg_pet-clinic.adoc    |  557 ++++++++++
 .../_tg_stop-scaffolding-start-coding.adoc      |  683 ++++++++++++
 .../asciidoc/guides/_ug_getting-started.adoc    |    2 +-
 ...ug_getting-started_datanucleus-enhancer.adoc |    2 +-
 ..._ug_getting-started_simpleapp-archetype.adoc |   49 +-
 .../asciidoc/guides/_ug_isis-maven-plugin.adoc  |    9 -
 ...esting_unit-test-support_contract-tests.adoc |    2 +-
 .../src/main/asciidoc/guides/_ug_tutorials.adoc |   18 -
 .../guides/_ug_tutorials_pet-clinic.adoc        |  557 ----------
 ...tutorials_stop-scaffolding-start-coding.adoc |  683 ------------
 .../src/main/asciidoc/guides/_ug_xxx.adoc       |    1 -
 .../src/main/asciidoc/guides/cg.adoc            |   36 +
 .../src/main/asciidoc/guides/dg.adoc            |   18 -
 .../images/building-isis/setting-up-git.png     |  Bin 0 -> 24406 bytes
 .../images/contributing/git-workflow-2.png      |  Bin 0 -> 40826 bytes
 .../guides/images/contributing/git-workflow.png |  Bin 0 -> 48331 bytes
 .../images/contributing/git-workflow.pptx       |  Bin 0 -> 68580 bytes
 .../images/contributing/github-cloning.png      |  Bin 0 -> 18935 bytes
 .../images/contributing/github-forking.png      |  Bin 0 -> 10274 bytes
 .../reference-classes/issue-in-more-detail.png  |  Bin 0 -> 7905 bytes
 .../jira-create-release-notes.png               |  Bin 0 -> 66123 bytes
 .../images/release-process/nexus-release-1.png  |  Bin 0 -> 82855 bytes
 .../images/release-process/nexus-staging-0.png  |  Bin 0 -> 76120 bytes
 .../images/release-process/nexus-staging-1.png  |  Bin 0 -> 105396 bytes
 .../images/release-process/nexus-staging-2.png  |  Bin 0 -> 108834 bytes
 .../images/release-process/nexus-staging-2a.png |  Bin 0 -> 108230 bytes
 .../images/release-process/nexus-staging-3.png  |  Bin 0 -> 122517 bytes
 .../images/release-process/nexus-staging-4.png  |  Bin 0 -> 96733 bytes
 .../src/main/asciidoc/guides/rg.adoc            |    5 +-
 .../asciidoc/guides/simpleapp-archetype.adoc    |  207 ++++
 .../src/main/asciidoc/guides/tg.adoc            |   22 +
 .../src/main/asciidoc/guides/ug.adoc            |    8 +-
 adocs/documentation/src/main/asciidoc/help.adoc |    2 +-
 .../images/building-isis/setting-up-git.png     |  Bin 24406 -> 0 bytes
 .../images/contributing/git-workflow-2.png      |  Bin 40826 -> 0 bytes
 .../images/contributing/git-workflow.png        |  Bin 48331 -> 0 bytes
 .../images/contributing/git-workflow.pptx       |  Bin 68580 -> 0 bytes
 .../images/contributing/github-cloning.png      |  Bin 18935 -> 0 bytes
 .../images/contributing/github-forking.png      |  Bin 10274 -> 0 bytes
 .../jira-create-release-notes.png               |  Bin 66123 -> 0 bytes
 .../images/release-process/nexus-release-1.png  |  Bin 82855 -> 0 bytes
 .../images/release-process/nexus-staging-0.png  |  Bin 76120 -> 0 bytes
 .../images/release-process/nexus-staging-1.png  |  Bin 105396 -> 0 bytes
 .../images/release-process/nexus-staging-2.png  |  Bin 108834 -> 0 bytes
 .../images/release-process/nexus-staging-2a.png |  Bin 108230 -> 0 bytes
 .../images/release-process/nexus-staging-3.png  |  Bin 122517 -> 0 bytes
 .../images/release-process/nexus-staging-4.png  |  Bin 96733 -> 0 bytes
 .../src/main/asciidoc/key-generation.adoc       |  572 ----------
 .../src/main/asciidoc/pmc-notes.adoc            |   73 --
 .../main/asciidoc/recreating-an-archetype.adoc  |  337 ------
 .../src/main/asciidoc/release-checklist.adoc    |   87 --
 .../asciidoc/release-process-one-pager.adoc     |  240 ----
 .../src/main/asciidoc/release-process.adoc      | 1046 ------------------
 .../src/main/asciidoc/screencasts.adoc          |    4 +-
 .../src/main/asciidoc/simpleapp-archetype.adoc  |  208 ----
 .../src/main/asciidoc/snapshot-process.adoc     |   96 --
 .../asciidoc/verifying-releases-script.adoc     |  152 ---
 .../verifying-releases-using-creadur-tools.adoc |   45 -
 .../src/main/asciidoc/verifying-releases.adoc   |  146 ---
 .../src/main/asciidoc/versioning-policy.adoc    |   35 -
 107 files changed, 6658 insertions(+), 6448 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/README.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/README.adoc b/adocs/documentation/README.adoc
index 04416af..e197fc5 100644
--- a/adocs/documentation/README.adoc
+++ b/adocs/documentation/README.adoc
@@ -19,12 +19,11 @@ Notice: Licensed to the Apache Software Foundation (ASF) under one
  under the License.
 endif::env-github[]
 
-This directory contains the source documentation that constitutes both the Apache Isis website (including the user guide and reference guide)  It is written using http://www.methods.co.nz/asciidoc/[Asciidoc].
+This directory contains the source documentation that constitutes both the Apache Isis' documentation (meaning the website and the users' guide, the reference guide and contributors' guide)   It is written using http://www.methods.co.nz/asciidoc/[Asciidoc], specifically the link:asciidoctor.org/[Asciidoctor] implementation.
 
-The website is created by running build tools (documented below) which create the HTML version of the site and guides.  This HTML is then copied to a different git repository (link:https://git-wip-us.apache.org/repos/asf?p=isis-site.git[isis-site]) which is synced by ASF infrastructure over to link:http://isis.apache.org[isis.apache.org].
-
-If you want to contribute documentation - either just to fix a typo, or to write a how-to, or to write a longer article - then fork this repo, write the `.adoc` source file, and raise a pull request.
+The website is created by running build tools (documented below) which create the HTML version of the site and guides.  You can therefore easily check the documentation before raising a pull request
 
+So, if you want to contribute documentation - either just to fix a typo, or to write a how-to or longer article - then fork the repo, write or modify the the `.adoc` source file, and raise a pull request.
 
 
 == Naming Conventions
@@ -141,71 +140,5 @@ usage: monitor.rb [options]
 
 == Publish procedure
 
-Only Apache Isis committers can publish to link:http://isis.apache.org[isis.apache.org].
-
-=== One-time setup
-
-The generated site is published by copying into the `content/` directory of the https://git-wip-us.apache.org/repos/asf/isis-site.git[isis-site git repo]. You therefore need to check this out this repo.
-
-The procedure assumes that two git repos (for https://git-wip-us.apache.org/repos/asf/isis.git[isis] itself and for isis-site) are checked out into the same parent directory, eg:
-
-[source]
-----
-/APACHE/
-    isis/                       # checkout of isis.git
-        adocs/
-            documentation/
-                README.adoc     # this file you are reading right now
-                ...
-    isis-site/                  # checkout of isis-site.git
-        content/                # the published website
-----
-
-If this isn't the case, then it is possible to override the relative directory by passing in a system property to the mvn goal; see below.
-
-You also need to know that ASF's publishing script work from the 'asf-site' branch, NOT from the 'master' branch. Therefore, in the `isis.git` repo site:
-
-[source]
-----
-git checkout asf-site
-----
-
-=== Publishing
-
-Back in the main `isis-git.repo`, to copy the generated documents to the `isis-site.git` repo , run:
-
-[source]
-----
-mvn clean package
-----
-
-This deletes the entire content of `contents`, and replaces with the content under `target/site`.  It also fixes up line endings, standardizing on unix-style LFs.
-
-[TIP]
-====
-If you have checked out the `isis-site.git` repo into some other directory (relative to `isis.site.git), then this can be overridden by specifying `-Disis-site.dir=...` when calling `mvn`.
-====
-
-
-To copy and to also commit the generated documents to the `isis-site.git` repo , run:
-
-[source]
-----
-mvn clean install
-----
-
-This will use a standard commit message (in the `isis-site.git` repo).  If you want to specify a custom message, use:
-
-[source]
-----
-mvn clean install -Dmessage="ISIS-nnnn: a custom commit message"
-----
-
-Pushing the commits (in the `isis-site.git` directory, of course) will publishing the changes:
-
-[source]
-----
-git push
-----
+Only Apache Isis committers can publish to link:http://isis.apache.org[isis.apache.org].  See the link:http://isis.apache.org/guides/cg.html#_cg_asciidoc[committers' guide] (including a longer version of this page) for details.
 
-Double check at http://isis.apache.org[isis.apache.org].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/applying-patches.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/applying-patches.adoc b/adocs/documentation/src/main/asciidoc/applying-patches.adoc
deleted file mode 100644
index badb6de..0000000
--- a/adocs/documentation/src/main/asciidoc/applying-patches.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-[[applying-patches]]
-= Applying Patches
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-
-pass:[<br/><br/>]
-
-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.
-
-
-
-== Diff files
-
-If a diff file has been provided, then it can easily be applied using eGit's wizards (Eclipse's Git integration)…
-
-NOTE: TODO - this stuff needs fleshing out ...
-
-
-
-== Patch files
-
-If a patch file has been provided, then it can be applied using command line tools.
-
-=== Inspect the patch
-
-First, take a look at what changes are in the patch. You can do this easily with `git apply`
-
-[source]
-----
-git apply --stat ISIS-xxx.patch
-----
-
-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.
-
-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.
-
-[source]
-----
-git apply --check ISIS-xxx.patch
-----
-
-If you don't get any errors, the patch has no conflicts. Otherwise you may see what trouble you’ll run into.
-
-
-=== Apply a (clean) patch
-
-To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`:
-
-[source]
-----
-git am --signoff < ISIS-xxx.patch
-----
-
-This preserves the original author's commit message.
-
-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 `am` session:
-
-[source]
-----
-git am abort
-----
-
-and continue on by applying a non-clean patch, as described next.
-
-=== Apply a (non-clean) patch
-
-If the patch does not apply cleanly, then the original authors commit message cannot be preserved. This sequence in this case is:
-
-[source]
-----
-git apply ISIS-xxx.patch
-----
-
-Fix up any issues. The add and commit as usual
-
-[source]
-----
-git add .
-git commit -am "<original authors' commit message>" --signoff
-----
-
-The `--signoff` simply adds a line to the commit message indicating you have signed off the commit.
-
-Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/building-isis.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/building-isis.adoc b/adocs/documentation/src/main/asciidoc/building-isis.adoc
deleted file mode 100644
index 1e7d2c6..0000000
--- a/adocs/documentation/src/main/asciidoc/building-isis.adoc
+++ /dev/null
@@ -1,174 +0,0 @@
-[[building-isis]]
-= Building Apache Isis
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-
-== Git
-
-The Apache Isis source code lives in a git repo.
-
-
-=== Installation
-
-The easiest place to get hold of command-line git is probably the http://git-scm.com/downloads[github download page].
-
-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:
-
-image::{_imagesdir}building-isis/setting-up-git.png[width="350px",link="{_imagesdir}building-isis/setting-up-git.png"]
-
-Once git is installed, the two main command line tools to note are:
-
-* `git` command line tool
-* `gitk` for viewing the commit history
-
-If using Windows, note that github also have a dedicated https://help.github.com/articles/set-up-git[Windows client]. With a little http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx[hacking around], it can also be made to work with non-github repositories.
-
-If using Mac, you might also want to check out Atlassian's http://www.atlassian.com/software/sourcetree/overview[Sourcetree].
-
-
-
-
-==== Cloning the Apache Isis repo
-
-First, clone the Apache Isis repo.
-
-If you are a *committer*, then clone from the Apache read/write repo:
-
-[source,bash]
-----
-git clone https://git-wip-us.apache.org/repos/asf/isis.git
-----
-
-
-If you are *not a committer*, please see the link:contributing.html[contributing] page for details on which repo to clone from.
-
-==== Configuring Git
-
-Next up is to configure your user name and password; see also https://git-wip-us.apache.org/[Apache's git] docs:
-
-[source,bash]
-----
-git config user.name "<i>My Name Here</i>"
-git config user.email <i>myusername@apache.org</i>
-----
-
-Next, configure the `core.autocrlf` so that line endings are normalized to LF (Unix style) in the rep; again see https://git-wip-us.apache.org/[Apache's git] page:
-
-
-* on Windows, use: +
-+
-[source,bash]
-----
-git config core.autocrlf true
-----
-
-* on Mac/Linux, use: +
-+
-[source,bash]
-----
-git config core.autocrlf input
-----
-
-
-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.
-
-We also recommend setting `core.safecrlf`, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:
-
-[source,bash]
-----
-git config core.safecrlf true
-----
-
-
-Note that these settings are supplemented in the repo by the `.gitattributes` file and that explicitly specifies line handling treatment for most of the common file types that we have.
-
-Next, we recommend you setup this a refspec so that you can distinguish remote tags from local ones. To do that, locate the `[remote &quot;origin&quot;]` section in your `.git/config` and add the third entry shown below:
-
-
-[source,bash]
-----
-[remote "origin"]
-    url = ... whatever ...
-    fetch = ... whatever ...
-    fetch = +refs/tags/*:refs/tags/origin/*
-----
-
-
-This will ensure that a `git fetch` or `git pull` places any remote tags under `origin/xxx.  For example, the`isis-1.0.0`tag on the origin will appear under`origin/isis-1.0.0`.
-
-
-If you don't use git outside of Apache, you can add the `--global` flag so that the above settings apply for all repos managed by git on your PC.
-
-
-
-=== Getting help
-
-Three commands of git that in particular worth knowing:
-
-* `git help _command_` +
-+
-will open the man page in your web browser
-
-* `git gui` +
-+
-will open up a basic GUI client to staging changes and making commits.
-
-* `gitk --all` +
-+
-will open the commit history for all branches. In particular, you should be able to see the local `master`, which branch you are working on (the `HEAD`), and also the last known position of the `master` branch from the central repo, called `origin/master`.
-
-You might also want to explore using a freely available equivalent such as link:https://www.sourcetreeapp.com/[Atlassian SourceTree].
-
-For further reading, see:
-
-* http://www.kernel.org/pub/software/scm/git/docs/git-config.html[git config man page]
-* http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html[.gitattributes man page]
-* http://git-scm.com/docs/gitattributes[.gitattributes git-scm.com docs]
-
-
-
-
-== Installing Maven
-
-Install Maven 3.0.x, downloadable http://maven.apache.org/download.html[here].
-
-Set `MAVEN_OPTS` environment variable:
-
-[source,ini]
-----
-MAVEN_OPTS=-Xms512m -Xmx1024m -XX:MaxPermSize=256m
-----
-
-
-[NOTE]
-====
-Previously we suggested `128m` for the `MaxPermSize`, but that would no longer seem to be sufficient.
-====
-
-
-== Building all of Apache Isis
-
-To build the source code from the command line, simply go to the root directory and type:
-
-[source,bash]
-----
-mvn clean install
-----
-
-
-The first time you do this, you'll find it takes a while since Maven needs to download all of the Apache Isis prerequisites.
-
-Thereafter you can speed up the build by adding the `-o` (offline flag):
-
-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.
-
-When using Eclipse, a Maven profile is configured such that Eclipse compiles to `target-ide` directory rather than the usual `target` directory. You can therefore switch between Eclipse and Maven command line without one interfering with the other.
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/contributing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/contributing.adoc b/adocs/documentation/src/main/asciidoc/contributing.adoc
deleted file mode 100644
index 07d365e..0000000
--- a/adocs/documentation/src/main/asciidoc/contributing.adoc
+++ /dev/null
@@ -1,258 +0,0 @@
-[[contributing]]
-= Contributing
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/><br/>]
-
-This page explains how you can contribute to Apache Isis. You'll probably also want link:development-environment.html[set up your development environment] and learn link:building-isis.html[how to build Apache Isis].
-
-Thanks for considering to help out, your contributions are appreciated!
-
-
-
-
-== Recommended Workflow (github)
-
-Apache Isis' source code is hosted in an Apache git repo (https://git-wip-us.apache.org/repos/asf/isis.git[https], http://git-wip-us.apache.org/repos/asf/isis.git[http]), with a clone on github (https://github.com/apache/isis.git[https], or ssh: `git@github.com:apache/isis.git`.
-
-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 https://github.com/apache/isis.git[apache/isis] repo in github, and then use your fork as a way of publishing your patches for the Apache Isis committers to apply.
-
-The diagram below illustrates the process:
-
-image::{_imagesdir}contributing/git-workflow.png[width="600px",link="{_imagesdir}contributing/git-workflow.png"]
-
-
-That is:
-
-. as a one-time activity, you fork the https://github.com/apache/isis.git[github.com/apache/isis] repo into your own fork on github.com
-. as a one-time activity, you clone your fork to your local computer
-. you set the https://github.com/apache/isis.git[github.com/apache/isis] as your upstream branch; this will allow you to keep your local clone up-to-date with new commits
-* note the asymmetry here: the `upstream` repo (the Apache github repo) is *not* the same as the `origin` repo (your fork).
-. you work on your changes locally; when done, you push them to your github fork
-. to contribute back a change, raise a https://issues.apache.org/jira/browse/ISIS[JIRA] ticket, and ensure your commit message is in the form: `ISIS-nnnn: ...` 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 http://isis.apache.org/support.html[mailing lists].
-. Use github to raise a https://help.github.com/articles/using-pull-requests/[pull request] for your feature
-. An Apache Isis committer will review your change, and apply it if suitable.
-
-
-
-
-== Alternative Workflow (JIRA patches)
-
-As an alternative, you may decide to clone directly from https://github.com/apache/isis.git[github.com/apache/isis] rather than create your own fork:
-
-
-image::{_imagesdir}contributing/git-workflow-2.png[width="600px",link="{_imagesdir}contributing/git-workflow-2.png"]
-
-In this case your `upstream` repo is the same as your `origin` 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. 
-
-For the Apache Isis committers it really doesn't matter which route you take, so go with whatever's most comfortable.
-
-
-
-
-== Setting up your fork/clone
-
-If you choose to create your own fork then you'll need an account on https://github.com[github.com]. You then fork simply by pressing the "Fork" button:
-
-
-image::{_imagesdir}contributing/github-forking.png[width="600px",link="{_imagesdir}contributing/github-forking.png"]
-
-
-
-An account isn't needed if you just clone straight from the http://github.com/apache/isis[github.com/apache/isis].
-
-Whether you've forked or not, you then need to clone the repo onto your computer. Github makes this very easy to do:
-
-* for Windows users, we suggest you use github's 'Clone in Windows' feature
-* for Mac/Linux users, create a clone from the command line:
-
-Again, the info is easily found in the github page:
-
-
-
-image::{_imagesdir}contributing/github-cloning.png[width="600px",link="{_imagesdir}contributing/github-cloning.png"]
-
-If you've created your own fork, then you need to add the `upstream` remote to the https://github.com/apache/isis[github.com/apache/isis]. This remote is traditionally called `upstream`. You should then arrange for your `master` branch to track the `upstream/master` remote branch:
-
-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:
-
-
-[source,bash]
-----
-git fetch
-----
-
-
-For more info on tracking branches http://git-scm.com/book/en/Git-Branching-Remote-Branches[here] and http://gitready.com/beginner/2009/03/09/remote-tracking-branches.html[here].
-
-
-
-
-
-== Commit messages
-
-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!
-
-We therefore recommend that your commit messages are as follows [1]:
-
-[source,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.
-----
-
-
-
-Once your git repo is setup, the next thing you'll most likely want to do is to setup your development environment. See link:development-environment.html[here] for more details.
-
-
-
-
-
-== Creating the patch file
-
-If you are working without a github fork of Apache Isis, then you can create the patches from your own local git repository.
-
-As per http://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit[this stackoverflow question], create the patch using `git format-patch`:
-
-[source,bash]
-----
-git format-patch -10 HEAD --stdout > 0001-last-10-commits.patch
-----
-
-Here `-10` 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.
-
-
-
-
-== Sample Contribution Workflow
-
-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.
-
-=== Update your master branch
-
-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.
-
-Irrespective of whether you are using a github fork, the upstream for your local `master` branch will be tracking the appropriate remote's `master` branch. So n either case, the same commands work:
-
-Alternatively, you can combine the `git fetch` and `git merge` and just use `git pull`:
-<pre>
-git checkout master
-git pull –ff-only
-</pre>
-
-If the `merge` or `pull` fails, it means that you must have made commits and there have been changes meanwhile on the remote `master`'s branch. You can use `gitk --all` to confirm. If this fails, see our link:git-cookbook.html[git cookbook] page for a procedure to retrospectively sort out this situation.
-
-
-
-=== Create a topic branch
-
-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 `master` and call it "ISIS-123-blobs"
-
-You can confirm the branch is there and is your new `HEAD` using either `gitk --all`. Alternatively, use the command line:
-
-
-[source,bash]
-----
-$ git checkout -b ISIS-123-blobs
-----
-
-
-The command line prompt should also indicate you are on a branch, isolated from any changes that might happen on the `master` branch.
-
-=== Make File Changes and Commit
-
-Next, make changes to your files using the usual commands (see also our link:git-cookbook.html[git cookbook] page):
-
-* `git add`
-* `git mv`
-* `git rm`
-* `git commit`
-* `git status`
-
-and so on.
-
-Continue this way until happy with the change. Remember to run all your tests on the topic branch (including a full `mvn clean install`).
-
-
-
-
-=== Rebasing with `master`
-
-Before you can share your change, you should rebase (in other words replay) your changes on top of the `master` branch. 
-
-The first thing to do is to pull down any changes made in upstream remote's `master` since you started your topic branch:
-
-These are the same commands that you would have run before you created your topic branch. If you use `gitk --all`, there's a good chance that new commits have come in.
-
-Next, we reintegrate our topic branch by rebasing onto `master`:
-<pre>
-git checkout ISIS-123-blobs
-git rebase master
-</pre>
-
-This takes all of the commits in your branch, and applies them on top of the new `master` branch. When your change is eventually integrated back in, it will result in a nice clear linear history on the public repo.
-
-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:
-
-Once the rebase has completed, re-run your tests to confirm that everything is still good.
-
-
-
-=== Raising a pull request
-
-If you have your own fork, you can now simply push the changes you've made locally to your fork:
-
-This will create a corresponding branch in the remote github repo. If you use `gitk --all`, you'll also see a `remotes/origin/ISIS-123-blobs` branch.
-
-Then, use github to raise a https://help.github.com/articles/using-pull-requests/[pull request]. Pull requests sent to the Apache GitHub repositories will forward a pull request e-mail to the link:../support.html[dev mailing list]. You'll probably want to sign up to the dev mailing list first before issuing your first pull request (though that isn't mandatory).
-
-The process to raise the pull request, broadly speaking:
-
-* Open a web browser to your github fork of isis
-* Select your topic branch (pushed in the previous step) so that the pull request references the topic branch.
-* Click the `Pull Request` button.
-* Check that the Apache Isis mailing list email came through.
-
-
-
-== If your pull request is accepted
-
-To double check that your pull request is accepted, update your `master` branch from the `upstream` remote:
-
-You can then use `gitk --all` (or `git log` if you prefer the command line) to check your contribution has been added.
-
-You can now delete your topic branch and remove the branch in your github:
-
-Finally, you might want to push the latest changes in master back up to your github fork. If so, use:
-
-
-
-=== If your pull request is rejected
-
-If your pull request is rejected, then you'll need to update your branch from the main repository and then address the rejection reason.
-
-You'll probably also want to remove the remote branch on github:
-
-[source,bash]
-----
-git push origin –delete ISIS-123-blobs
-----
-
-
-… and continue as before until you are ready to resubmit your change.
-
-[1] inspiration for the recommended commit format comes from the https://github.com/puppetlabs/puppet[puppet] project's https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md[contributing] page.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index f3b13bd..65e3f0f 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -26,28 +26,24 @@ pass:[<br/>]
 * link:./powered-by.html[Powered by Apache Isis]
 * link:./how-isis-works.html[How Apache Isis Works] image:{_imagesdir}tv_show-25.png[width="25px" link="how-isis-works.html"]
 * link:./common-use-cases.html[Common Use Cases]
-* link:http://isisdemo.mmyco.co.uk/[Online demo] (todoapp)
-
-
-| *Archetypes and Apps:*
 
-* *link:./simpleapp-archetype.html[SimpleApp Archetype]*
-* http://github.com/isisaddons/isis-app-todoapp[TodoApp Example App] (not ASF)
-* http://github.com/isisaddons/isis-app-kitchensink[Kitchensink App] (not ASF)
 
-*Isis Add-ons*
+|*Learning More*
 
-* http://isisaddons.org[Isis addons] (not ASF)
+* link:http://isisdemo.mmyco.co.uk/[Online demo] (todoapp)
+* link:./screencasts.html[Screencasts] image:{_imagesdir}tv_show-25.png[width="25px",link="./screencasts.html]
+* link:./guides/tg.html[Tutorials]
 
 
 
+|*Resources:*
 
-|*Development Environment:*
+* *link:./cheat-sheet.html[Cheat Sheet]*
+* link:./icons.html[Icons]
 
-* link:./guides/dg.html#_dg_intellij[Setting up IntelliJ]
-* link:./guides/dg.html#_dg_eclipse[Setting up Eclipse]
-* *link:./editor-templates.html[IDE templates]* (IntelliJ and Eclipse)
+*Isis Add-ons*
 
+* http://isisaddons.org[Isis addons] (not ASF)
 
 
 |===
@@ -56,77 +52,84 @@ pass:[<br/>]
 [cols="1a,1a,1a"]
 |===
 
-|*User Guide:*
+|*Users' Guide:*
+
+Core concepts, how tos and more advanced techniques, using and customizing the Wicket viewer & the Restful Objects viewer, security, testing
+
+pass:[<a class="button guide" href="./guides/ug.html" role="button" target="_blank">Users' Guide »</a>]
 
-Core concepts, how tos, more advanced techniques, Wicket viewer, Restful Objects viewer, security, configuration, deployment, testing, extending
+including:
+
+* *link:./guides/ug.html#_ug_getting-started_simpleapp-archetype[Getting Started]* (SimpleApp Archetype)
+* link:./guides/ug.html#_ug_how-tos[How-tos]
+* link:./guides/ug.html#_ug_wicket-viewer[Customizing the Wicket Viewer]
+* link:./guides/ug.html#_ug_testing[Testing]
+* link:./guides/ug.html#_ug_extending[Extending]
 
-pass:[<a class="button guide" href="./guides/ug.html" role="button" target="_blank">User Guide »</a>]
 
 |*Reference Guide:*
 
-Annotations, reserved methods, method prefixes domain services (API and SPI), utility classes, object layout
+Programming model (annotations, methods), domain services (API and SPI), utility classes, UI layout, runtime configuration properties
 
 pass:[<a class="button guide" href="./guides/rg.html" role="button" target="_blank">Reference Guide »</a>]
 
+including:
 
-|*Resources:*
+* link:./guides/rg.html#_rg_annotations[Annotations]
+* *link:./guides/rg.html#_rg_methods[Methods]*
+* *link:./guides/rg.html#_rg_services-api[Domain Services API]*
+* link:./guides/rg.html#_rg_services-spi[Domain Services SPI]
+* link:./guides/rg.html#_rg_runtime[Configuration Properties]
 
-To save you time
 
-* *link:./editor-templates.html[IDE templates]* (IntelliJ and Eclipse)
-* *link:./cheat-sheet.html[Cheat Sheet]*
-* link:./icons.html[Icons]
+|*Contributors' Guide*
 
+IDE setup, build the framework, writing docs, how to contribute patches (pull requests); for committers: publishing docs, applying patches, release process.
 
-|===
+pass:[<a class="button guide" href="./guides/cg.html" role="button" target="_blank">Contributors' Guide »</a>]
 
+including:
+
+* Setting up link:./guides/cg.html#_cg_ide_intellij[IntelliJ] or link:./guides/cg.html#_cg_ide_eclipse[Eclipse]
+* link:./guides/cg.html#_cg_ide-templates[*IDE templates*] (IntelliJ and Eclipse)
+* link:./guides/cg.html#_cg_contributing[Contributing patches] (pull requests)
+* link:./guides/cg.html#_cg_committers_cutting-a-release[Cutting a release] (and link:./guides/cg.html#_cg_committers_cutting-a-release-one-pager[*one-pager*])
 
 
 
-[cols="1a,1a,1a",frame="none"]
 |===
 
-|*Further resources:*
 
-For digging deeper
 
-* link:./screencasts.html[Screencasts] image:{_imagesdir}tv_show-25.png[width="25px",link="./screencasts.html]
-* link:./articles-and-presentations.html[Articles, Conferences, Podcasts]
 
-* link:./books.html[Books]
-* link:./resources/thesis/Pawson-Naked-Objects-thesis.pdf[Naked Objects PhD thesis] (Pawson)
-//* link:./downloadable-presentations.html[Downloadable Presentations]
+[cols="1a,1a,1a",frame="none"]
+|===
 
-*Releases:*
+|*Example Apps:*
+
+* http://github.com/estatio/estatio[Estatio] (not ASF)
+* http://github.com/isisaddons/isis-app-todoapp[TodoApp Example App] (not ASF)
+* http://github.com/isisaddons/isis-app-kitchensink[Kitchensink App] (not ASF)
 
-* link:release-notes.html[Release Notes]
-* link:migration-notes.html[Migration Notes]
 
 
 
-|*Contributors:*
+|*Going Deeper:*
+
+* link:./articles-and-presentations.html[Articles, Conferences, Podcasts]
+* link:./books.html[Books]
+* link:./resources/thesis/Pawson-Naked-Objects-thesis.pdf[Naked Objects PhD thesis] (Pawson)
+//* link:./downloadable-presentations.html[Downloadable Presentations]
 
-* link:./contributing.html[Contributing]
-* link:./building-isis.html[Building Apache Isis]
-* link:./git-policy.html[Git Policy]
-* link:./git-cookbook.html[Git Cookbook]
-* link:./versioning-policy.html[Versioning Policy]
 
 
-|*Committers*:
+|*Releases:*
 
-* link:./applying-patches.html[Applying Patches]
-* link:./recreating-an-archetype.html[Recreating an archetype]
-* link:./snapshot-process.html[Snapshot process]
-* link:./release-process.html[Release process] (link:./release-process-one-pager.html[one-pager])
-* link:./release-branch-and-tag-names.html[Release branch and tag names]
-* link:./verifying-releases.html[Verifying releases]
-* link:./key-generation.html[Key generation]
+* link:release-notes.html[Release Notes]
+* link:migration-notes.html[Migration Notes]
 
 
-*PMC*:
 
-* link:./pmc-notes.html[Notes]
 
 
 |====

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/editor-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/editor-templates.adoc b/adocs/documentation/src/main/asciidoc/editor-templates.adoc
deleted file mode 100644
index 62a08ec..0000000
--- a/adocs/documentation/src/main/asciidoc/editor-templates.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-[[editor-templates]]
-= Editor Templates
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-pass:[<br/><br/><br/>]
-
-
-We provide IDE templates (for IntelliJ and Eclipse) for writing Apache Isis domain objects, and also for unit tests (JUnit and JMock).
-
-== Download
-
-The following table lists the templates to download
-
-[cols="1a,1a,1a,1a", options="header"]
-|===
-
-|Template
-|Prefix
-|IntelliJ
-|Eclipse
-
-
-|Apache Isis Domain Objects
-|is
-|link:./resources/templates/isis-templates-idea.xml[Download]
-|link:./resources/templates/isis-templates.xml[Download]
-
-
-|JUnit tests
-|ju
-|link:./resources/templates/junit4-templates-idea.xml[Download]
-|link:./resources/templates/junit4-templates.xml[Download]
-
-
-|JMock tests
-|jm
-|link:./resources/templates/jmock2-templates-idea.xml[Download]
-|link:./resources/templates/jmock2-templates.xml[Download]
-
-|===
-
-
-The most commonly used Apache Isis domain objects templates are also listed on the link:./cheat-sheet.html[Apache Isis cheat sheet].
-
-
-
-== Installation
-
-=== IntelliJ
-
-To install in IntelliJ, copy to the relevant `config/templates` directory, eg:
-
-* Windows `<User home>\.IntelliJIdea14\config\templates`
-* Linux `~/.IntelliJIdea14/config/templates`
-* Mac OS `~/Library/Preferences/IntelliJIdea14/templates`
-
-
-=== Eclipse
-
-To install in Eclipse, go to `Windows > Preferences > Java > Editor > Templates` and choose `Import`.
-
-
-
-== Usage
-
-Enter the prefix (`is`, `ju`, `jm`) and the IDE will list all available templates in that category.  
-

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/git-cookbook.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/git-cookbook.adoc b/adocs/documentation/src/main/asciidoc/git-cookbook.adoc
deleted file mode 100644
index 21f2932..0000000
--- a/adocs/documentation/src/main/asciidoc/git-cookbook.adoc
+++ /dev/null
@@ -1,261 +0,0 @@
-[[git-cookbook]]
-= Git Cookbook
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-
-
-
-This page describes the commands often used while working with git.  In addition to these basic commands, please make sure you have read:
-
-* link:./building-isis.html[building Apache Isis]
-* link:./git-policy.html[Git policy]
-* link:./contributing.html[Contributing]
-
-
-
-
-== Modifying existing files
-
-To modify existing files:
-
-[source,bash]
-----
-git add filename
-git commit -m "ISIS-nnn: yada yada"
-----
-
-The `git add` command adds the changes to the file(s) to the git index (aka staging area).  If you were to make subsequent changes to the file these would not be committed.
- 
-The `git commit` takes all the staged changes and commits them locally.  Note that these changes are not shared public with Apache Isis' central git repo.
-
-You can combine these two commands using `-am` flag to git commit:
-
-[source,bash]
-----
-git commit -am "ISIS-nnn: yada yada"
-----
-
-
-
-
-== Adding new files
-
-To add a new file:
-
-[source,bash]
-----
-git add .
-git commit -m "ISIS-nnn: yada yada"
-----
-
-
-Note that this sequence of commands is identical to modifying an existing file.  However, it isn't possible to combine the two steps using `git commit -am`; the `git add` is always needed when adding new files to the repo.
-
-
-
-
-== Deleting files
-
-To delete a file:
-
-[source,bash]
-----
-git rm filename
-git commit -m "ISIS-nnn: yada yada"
-----
-
-
-
-== Renaming or moving files
-
-To rename or move a file:
-
-
-[source,bash]
-----
-git mv <i>filename</i> <i>newfilename</i>
-git commit -m "ISIS-nnn: yada yada"
-----
-
-
-
-
-== Common Workflows
-
-The link:./contributing.html[contributing] page describes the workflow for non-committers.  The link:./git-policy.html[Git policy] page describes a workflow for Apache Isis **committers**.
-
-
-
-
-
-== Backing up a local branch
-
-If committing to a local branch, the changes are still just that: local, and run risk of a disk failure or other disaster.
-
-To create a new, similarly named branch on the central repo, use:
-
-[source,bash]
-----
-git push -u origin <i>branchname</i>
-----
-
-Using `gitk --all` will show you this new branch, named *origin/branchname*.
-
-Thereafter, you can push subsequent commits using simply:
-
-[source,bash]
-----
-git push
-----
-
-
-Doing this also allows others to collaborate on this branch, just as they would for `master`.
-
-When, eventually, you have reintegrated this branch, you can delete the remote branch using:
-
-[source,bash]
-----
-git push origin --delete <i>branchname</i>
-----
-
-
-For more detail, see these blogs/posts link:http://www.mariopareja.com/blog/archive/2010/01/11/how-to-push-a-new-local-branch-to-a-remote.aspx[here] and link:http://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-both-locally-and-in-github[here].
-
-
-
-== Quick change: stashing changes
-
-If you are working on something but are not ready to commit, then use:
-
-[source,bash]
-----
-git stash
-----
-
-
-If you use `gitk --all` then you'll see new commits are made that hold the current state of your working directory and staging area.
-
-You can then, for example, pull down the latest changes using `git pull --rebase` (see above).
-
-To reapply your stash, then use:
-
-[source,bash]
-----
-git stash pop
-----
-
-Note that stashing works even if switching branches
-
-
-## Ignoring files
-
-Put file patterns into `.gitignore`.  There is one at the root of the git repo, but they can additionally appear in subdirectories (the results are cumulative).
-
-See also:
-
-- link:https://help.github.com/articles/ignoring-files[github's help page]
-- link:http://www.kernel.org/pub/software/scm/git/docs/gitignore.html[man page]
-
-
-
-
-== More advanced use cases
-
-=== If accidentally push to remote
-
-Suppose you committed to `master`, and then pushed the change, and then decided that you didn't intend to do that:
-
-[source,bash]
-----
-C1  -  C2  -  C3  -  C4  -  C5  -  C6  -  C7
-                                          ^
-                                          master
-                                          ^
-                                          origin/master
-----
-
-To go back to an earlier commit, first we wind back the local `master`:
-
-[source,bash]
-----
-git reset --hard C5
-----
-
-where `C5` is the long sha-id for that commit.
-
-This gets us to:
-
-[source,bash]
-----
-C1  -  C2  -  C3  -  C4  -  C5  -  C6  -  C7
-                            ^
-                            master
-                                          ^
-                                          origin/master
-----
-
-Then, do a force push:
-
-[source,bash]
-----
-git push origin master --force
-----
-
-If this doesn't work, it may be that the remote repo has disabled this feature.  There are other hacks to get around this, see for example link:http://stackoverflow.com/questions/1377845/git-reset-hard-and-a-remote-repository[here].
-
-
-
-
-== If you've accidentally worked on `master` branch
-
-If at any time the `git pull` from your upstream fails, it most likely means that you must have made commits on the `master` branch.  You can use `gitk --all` to confirm; at some point in time both `master` and `origin\master` will have a common ancestor.
-
-You can retrospectively create a topic branch for the work you've accidentally done on `master`.  
-
-First, create a branch for your current commit:
-
-[source,bash]
-----
-git branch <i>newbranch</i>
-----
-
-
-Next, make sure you have no outstanding edits.  If you do, you should commit them or stash them:
-
-
-[source,bash]
-----
-git stash
-----
-
-
-Finally, locate the shaId of the commit you want to roll back to (easily obtained in `gitk -all`), and wind `master` branch back to that commit:
-
-
-[source,bash]
-----
-git checkout master
-git reset --hard <i>shaId</i>      # move master branch shaId of common ancestor
-----
-
-
-
-== If you've forgotten to prefix your commits (but not pushed)
-
-One of our committers, Alexander Krasnukhin, has put together some git scripts to help his workflow.  Using one of these, `git prefix`, you can just commit with proper message without bothering about prefix and add prefix only in the end *before* the final push.
- 
-For example, to prefix all not yet prefixed commits `master..isis/666` with `ISIS-666` prefix, use:
-
-[source,bash]
-----
-git prefix ISIS-666 master..isis/666
-----
-
-
-You can grab this utility, and others, from link:https://github.com/themalkolm/git-boots[this repo].

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/git-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/git-policy.adoc b/adocs/documentation/src/main/asciidoc/git-policy.adoc
deleted file mode 100644
index 33f9c49..0000000
--- a/adocs/documentation/src/main/asciidoc/git-policy.adoc
+++ /dev/null
@@ -1,101 +0,0 @@
-[[git-policy]]
-= Git Policy
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-
-
-These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:
-
-* git commits form an acyclic graph, with each commit pointing to its parent commit (or commit**s**, if a merge)
-
-* a branch is merely a pointer to one of these commits; git calls the main branch `master`
-
-* git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.
-
-For more background reading, see:
-
-* http://git-scm.com/book[Pro Git] book (free in electronic form)
-* https://github.s3.amazonaws.com/media/book.pdf[Git community book]
-* http://git-scm.com/2011/07/11/reset.html[git reset demystified] - differentiating the working directory vs index/staging area
-
-And, of course, there is loads of good advice on http://stackoverflow.com/questions/tagged/git[stackoverflow.com]
-
-
-
-== Workflow
-
-There are many ways of using Git, but the Apache Isis committers have adopted the following workflow:
-
-* create a topic branch for a feature +
-+
-[source,bash]
-----
-git checkout -b ISIS-999
-----
-
-* periodically, push the branch to origin (for safekeeping): +
-+
-[source,bash]
-----
-git push origin ISIS-999
-----
-
-
-* `rebase` the topic branch periodically on master. +
-+
-How often you do this will depend on whether you are collaborating with others on the feature.  You need to ensure that your co-worker has no outstanding work before you do this; otherwise it'll create merge conflict hell for them:
-+
-[source,bash]
-----
-git checkout master
-git pull
-git checkout ISIS-999
-git rebase master
-git push origin ISIS-999 --force
-----
-
-* when feature is complete, rebase once more (as above), then switch to master and perform a `merge --no-ff`: +
-+
-[source,bash]
-----
-git checkout master
-git merge --no-ff ISIS-999
-----
-
-* finally, remove the branch +
-+
-[source,bash]
-----
-git branch -d ISIS-999
-git push origin --delete ISIS-999
-----
-
-This way of working gives us the full history on the branch as to what the thought processes were for the feature, but only a single commit on to `master` to see the ultimate impact of the changes (acting a bit like a summary).
-
-
-
-
-
-== Commit message
-
-The minimum we expect in a commit messages is:
-
-[source,bash]
-----
-ISIS-nnn: brief summary here
-
-- optionally, longer details
-- should be written here
-- in bullet points
-----
-
-
-where `ISIS-nnn` is a ticket raised in our https://issues.apache.org/jira/browse/ISIS[JIRA issue tracker].
-
-For non-committers we typically expect more detail again; see the link:contributing.html[contributing] page for the longer format recommended for contributors to use.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc
new file mode 100644
index 0000000..ed4de95
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_asciidoc.adoc
@@ -0,0 +1,208 @@
+[[_cg_asciidoc]]
+= AsciiDoc Documentation
+
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+Apache Isis' documentation (meaning the website and the users' guide, the reference guide and this contributors' guide) is written using link:http://www.methods.co.nz/asciidoc/[Asciidoc], specifically the link:asciidoctor.org/[Asciidoctor] implementation.
+
+The website and guides are created by running build tools (documented below) which create the HTML version of the site and guides.  You can therefore easily check the documentation before raising a pull request (as a contributor) or publishing the site (if a committer).
+
+Publishing is performed by copying the generated HTML to a different git repository (link:https://git-wip-us.apache.org/repos/asf?p=isis-site.git[isis-site]).  This is synced by ASF infrastructure over to link:http://isis.apache.org[isis.apache.org].
+
+
+
+
+== Where to find the Docs
+
+The (Asciidoc) source code can be found at `adocs/documentation` (relative to root).  Online you'll find it link:https://github.com/apache/isis/tree/master/adocs/documentation[cloned to github here].
+
+
+
+== Naming Conventions
+
+For documents with inclusions, use '_' to separate out the logical hierarchy:
+
+[source]
+----
+xxx-xxx/xxx-xxx.adoc
+        _xxx-xxx_ppp-ppp.adoc
+        _xxx-xxx_qqq-qqq.adoc
+        _xxx-xxx_qqq-qqq_mmm-mmm.adoc
+        _xxx-xxx_qqq-qqq_nnn-nnn.adoc
+----
+
+Any referenced images should be in subdirectories of the `images` directory: 
+
+[source]
+----
+xxx-xxx/images/.
+              /ppp-ppp/.
+              /qqq-qqq/.
+                      /mmm-mmm
+                      /nnn-nnn
+----
+
+And similarly any resources should be in the `resources` subdirectory:
+
+[source]
+----
+xxx-xxx/resources/.
+                  ppp-ppp/.
+                  qqq-qqq/.
+                         /mmm-mmm/
+                         /nnn-nnn/
+----
+
+
+
+== Build and Review (using Maven)
+
+To (re)build the documentation locally prior to release, use:
+
+[source]
+----
+mvn clean compile
+----
+
+The site will be generated at `target/site/index.html`.
+
+You could then use a web server such as Python's SimpleHTTPServer to preview (so that all Javascript works correctly). However, instead we recommend using instant preview, described next.
+
+
+== Instant Rebuild (using Ruby)
+
+The ruby script, `monitor.rb` emulates the `mvn site` command, regenerating any changed Asciidoctor files to the relevant `target/site` directory. If any included files are changed then it rebuilds the parent (per the above naming convention). 
+
+To setup:
+
+* download and install ruby 2.0.0, from link:rubyinstaller.org/downloads[http://rubyinstaller.org/downloads/]
+* download devkit for the Ruby 2.0 installation, also from link:rubyinstaller.org/downloads[http://rubyinstaller.org/downloads/]. Then follow the link:https://github.com/oneclick/rubyinstaller/wiki/Development-Kit[installation instructions] on their wiki
+
+
+[NOTE]
+====
+We use Ruby 2.0 rather than 2.1 because the wdm gem (required to monitor the filesystem if running on Windows) is not currently compatible with Ruby 2.1.
+====
+
+To install:
+
+[source,bash]
+----
+gem install bundler
+bundle install
+----
+
+To run, we typically just use:
+
+[source,bash]
+----
+ruby monitor.rb
+----
+
+This will start monitoring all files under `src/main/asciidoc`, and start up a web server on port 4000 so you can review results.  If any `.adoc` changes, then the appropriate HTML will be regenerated.  And, if any new assets (CSS, images etc) are added, they will be copied across.
+
+It often makes sense to combine this with `mvn`:
+
+[source,bash]
+----
+mvn clean install && ruby monitor.rb
+----
+
+This directory contains a tiny script, `r.sh`, that executes exactly the above line.
+
+The `monitor.rb` script has a couple of other options, use `-h` flag for usage:
+
+[source,bash]
+----
+ruby monitor.rb -h
+----
+
+which should print:
+
+[source]
+----
+usage: monitor.rb [options]
+    -p, --port       port (default: 4000)
+    -b, --browser    launch browser
+    -h, --help       help
+----
+
+
+
+
+== Publish procedure
+
+Only Apache Isis committers can publish to link:http://isis.apache.org[isis.apache.org].  We've decided to include these procedures here here (rather than put them in the xref:cg.adoc#_cg_committers[committers' section] of this guide, just to keep things together.
+
+
+=== One-time setup
+
+The generated site is published by copying into the `content/` directory of the https://git-wip-us.apache.org/repos/asf/isis-site.git[isis-site git repo]. You therefore need to check this out this repo.
+
+The procedure assumes that two git repos (for https://git-wip-us.apache.org/repos/asf/isis.git[isis] itself and for isis-site) are checked out into the same parent directory, eg:
+
+[source]
+----
+/APACHE/
+    isis/                       # checkout of isis.git
+        adocs/
+            documentation/
+                README.adoc     # this file you are reading right now
+                ...
+    isis-site/                  # checkout of isis-site.git
+        content/                # the published website
+----
+
+If this isn't the case, then it is possible to override the relative directory by passing in a system property to the mvn goal; see below.
+
+You also need to know that ASF's publishing script work from the 'asf-site' branch, NOT from the 'master' branch. Therefore, in the `isis.git` repo site:
+
+[source,bash]
+----
+git checkout asf-site
+----
+
+=== Publishing
+
+Back in the main `isis-git.repo`, to copy the generated documents to the `isis-site.git` repo , run:
+
+[source,bash]
+----
+mvn clean package
+----
+
+This deletes the entire content of `contents`, and replaces with the content under `target/site`.  It also fixes up line endings, standardizing on unix-style LFs.
+
+[TIP]
+====
+If you have checked out the `isis-site.git` repo into some other directory (relative to `isis.site.git), then this can be overridden by specifying `-Disis-site.dir=...` when calling `mvn`.
+====
+
+
+To copy and to also commit the generated documents to the `isis-site.git` repo , run:
+
+[source,bash]
+----
+mvn clean install
+----
+
+This will use a standard commit message (in the `isis-site.git` repo).  If you want to specify a custom message, use:
+
+[source,bash]
+----
+mvn clean install -Dmessage="ISIS-nnnn: a custom commit message"
+----
+
+Pushing the commits (in the `isis-site.git` directory, of course) will publishing the changes:
+
+[source,bash]
+----
+git push
+----
+
+Double check at http://isis.apache.org[isis.apache.org].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_building-isis.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_building-isis.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_building-isis.adoc
new file mode 100644
index 0000000..9ba29a9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_building-isis.adoc
@@ -0,0 +1,174 @@
+[[_cg_building-isis]]
+= Building Apache Isis
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+
+== Git
+
+The Apache Isis source code lives in a git repo.
+
+
+=== Installation
+
+The easiest place to get hold of command-line git is probably the http://git-scm.com/downloads[github download page].
+
+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:
+
+image::{_imagesdir}building-isis/setting-up-git.png[width="350px",link="{_imagesdir}building-isis/setting-up-git.png"]
+
+Once git is installed, the two main command line tools to note are:
+
+* `git` command line tool
+* `gitk` for viewing the commit history
+
+If using Windows, note that github also have a dedicated https://help.github.com/articles/set-up-git[Windows client]. With a little http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx[hacking around], it can also be made to work with non-github repositories.
+
+If using Mac, you might also want to check out Atlassian's http://www.atlassian.com/software/sourcetree/overview[Sourcetree].
+
+
+
+
+==== Cloning the Apache Isis repo
+
+First, clone the Apache Isis repo.
+
+If you are a *committer*, then clone from the Apache read/write repo:
+
+[source,bash]
+----
+git clone https://git-wip-us.apache.org/repos/asf/isis.git
+----
+
+
+If you are *not a committer*, please see the xref:cg.adoc#_cg_contributing[contributing] page for details on which repo to clone from.
+
+==== Configuring Git
+
+Next up is to configure your user name and password; see also https://git-wip-us.apache.org/[Apache's git] docs:
+
+[source,bash]
+----
+git config user.name "<i>My Name Here</i>"
+git config user.email <i>myusername@apache.org</i>
+----
+
+Next, configure the `core.autocrlf` so that line endings are normalized to LF (Unix style) in the rep; again see https://git-wip-us.apache.org/[Apache's git] page:
+
+
+* on Windows, use: +
++
+[source,bash]
+----
+git config core.autocrlf true
+----
+
+* on Mac/Linux, use: +
++
+[source,bash]
+----
+git config core.autocrlf input
+----
+
+
+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.
+
+We also recommend setting `core.safecrlf`, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:
+
+[source,bash]
+----
+git config core.safecrlf true
+----
+
+
+Note that these settings are supplemented in the repo by the `.gitattributes` file and that explicitly specifies line handling treatment for most of the common file types that we have.
+
+Next, we recommend you setup this a refspec so that you can distinguish remote tags from local ones. To do that, locate the `[remote &quot;origin&quot;]` section in your `.git/config` and add the third entry shown below:
+
+
+[source,bash]
+----
+[remote "origin"]
+    url = ... whatever ...
+    fetch = ... whatever ...
+    fetch = +refs/tags/*:refs/tags/origin/*
+----
+
+
+This will ensure that a `git fetch` or `git pull` places any remote tags under `origin/xxx.  For example, the`isis-1.0.0`tag on the origin will appear under`origin/isis-1.0.0`.
+
+
+If you don't use git outside of Apache, you can add the `--global` flag so that the above settings apply for all repos managed by git on your PC.
+
+
+
+=== Getting help
+
+Three commands of git that in particular worth knowing:
+
+* `git help _command_` +
++
+will open the man page in your web browser
+
+* `git gui` +
++
+will open up a basic GUI client to staging changes and making commits.
+
+* `gitk --all` +
++
+will open the commit history for all branches. In particular, you should be able to see the local `master`, which branch you are working on (the `HEAD`), and also the last known position of the `master` branch from the central repo, called `origin/master`.
+
+You might also want to explore using a freely available equivalent such as link:https://www.sourcetreeapp.com/[Atlassian SourceTree].
+
+For further reading, see:
+
+* http://www.kernel.org/pub/software/scm/git/docs/git-config.html[git config man page]
+* http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html[.gitattributes man page]
+* http://git-scm.com/docs/gitattributes[.gitattributes git-scm.com docs]
+
+
+
+
+== Installing Maven
+
+Install Maven 3.0.x, downloadable http://maven.apache.org/download.html[here].
+
+Set `MAVEN_OPTS` environment variable:
+
+[source,ini]
+----
+MAVEN_OPTS=-Xms512m -Xmx1024m -XX:MaxPermSize=256m
+----
+
+
+[NOTE]
+====
+Previously we suggested `128m` for the `MaxPermSize`, but that would no longer seem to be sufficient.
+====
+
+
+== Building all of Apache Isis
+
+To build the source code from the command line, simply go to the root directory and type:
+
+[source,bash]
+----
+mvn clean install
+----
+
+
+The first time you do this, you'll find it takes a while since Maven needs to download all of the Apache Isis prerequisites.
+
+Thereafter you can speed up the build by adding the `-o` (offline flag):
+
+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.
+
+When using Eclipse, a Maven profile is configured such that Eclipse compiles to `target-ide` directory rather than the usual `target` directory. You can therefore switch between Eclipse and Maven command line without one interfering with the other.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_cmd-line.adoc
new file mode 100644
index 0000000..d5f8f8c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_cmd-line.adoc
@@ -0,0 +1,9 @@
+[[_cg_cmd-line]]
+= Command Line and CI
+:Notice: 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.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+NOTE: TODO
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers-applying-patches.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers-applying-patches.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers-applying-patches.adoc
new file mode 100644
index 0000000..8c175a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers-applying-patches.adoc
@@ -0,0 +1,90 @@
+[[_cg_committers_applying-patches]]
+= Applying Patches
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+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.
+
+
+
+
+== Diff files
+
+If a diff file has been provided, then it can easily be applied using eGit's wizards (Eclipse's Git integration)…
+
+NOTE: TODO - this stuff needs fleshing out ...
+
+
+
+
+== Patch files
+
+If a patch file has been provided, then it can be applied using command line tools.
+
+=== Inspect the patch
+
+First, take a look at what changes are in the patch. You can do this easily with `git apply`
+
+[source,bash]
+----
+git apply --stat ISIS-xxx.patch
+----
+
+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.
+
+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.
+
+[source,bash]
+----
+git apply --check ISIS-xxx.patch
+----
+
+If you don't get any errors, the patch has no conflicts. Otherwise you may see what trouble you’ll run into.
+
+
+=== Apply a (clean) patch
+
+To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`:
+
+[source,bash]
+----
+git am --signoff < ISIS-xxx.patch
+----
+
+This preserves the original author's commit message.
+
+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 `am` session:
+
+[source,bash]
+----
+git am abort
+----
+
+and continue on by applying a non-clean patch, as described next.
+
+
+
+=== Apply a (non-clean) patch
+
+If the patch does not apply cleanly, then the original authors commit message cannot be preserved. This sequence in this case is:
+
+[source,bash]
+----
+git apply ISIS-xxx.patch
+----
+
+Fix up any issues. The add and commit as usual
+
+[source,bash]
+----
+git add .
+git commit -am "<original authors' commit message>" --signoff
+----
+
+The `--signoff` simply adds a line to the commit message indicating you have signed off the commit.
+
+Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers.adoc
new file mode 100644
index 0000000..0eb5938
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers.adoc
@@ -0,0 +1,27 @@
+[[_cg_committers]]
+= Committers
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+This chapter provides guidance for Apache Isis' own committers.
+
+// for some reason this doesn't seem to include:: correctly; that said, it's incomplete anyway
+//include::_cg_committers_applying-patches.adoc[leveloffset=+1]
+
+include::_cg_committers_recreating-an-archetype.adoc[leveloffset=+1]
+include::_cg_committers_cutting-a-release.adoc[leveloffset=+1]
+include::_cg_committers_cutting-a-release-one-pager.adoc[leveloffset=+1]
+include::_cg_committers_release-checklist.adoc[leveloffset=+1]
+include::_cg_committers_verifying-releases.adoc[leveloffset=+1]
+include::_cg_committers_verifying-releases-using-a-script.adoc[leveloffset=+1]
+include::_cg_committers_verifying-releases-using-creadur-tools.adoc[leveloffset=+1]
+include::_cg_committers_release-process-for-snapshots.adoc[leveloffset=+1]
+
+include::_cg_committers_key-generation.adoc[leveloffset=+1]
+
+include::_cg_committers_pmc-notes.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_cutting-a-release-one-pager.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_cutting-a-release-one-pager.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_cutting-a-release-one-pager.adoc
new file mode 100644
index 0000000..df2dfc3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_cutting-a-release-one-pager.adoc
@@ -0,0 +1,240 @@
+[[_cg_committers_cutting-a-release-one-pager]]
+= Cutting a release (1 pager)
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+See also the xref:cg.adoc#_cg_release-process[full release process] and the xref:cg.adoc#_cg_committers_release-checklist[release checklist].
+
+
+
+== Switch to correct directory, parameterize the release
+
+[WARNING]
+====
+Make sure you are in the correct directory (eg `core`, or `example/archetype/zzz`)
+====
+
+
+if you are releasing `core`:
+
+[source]
+----
+cd core
+
+export ISISTMP=/c/tmp              # or whatever
+export ISISART=isis
+export ISISDEV=1.9.0-SNAPSHOT
+export ISISREL=1.8.0
+export ISISRC=RC1
+
+export ISISCOR="Y"
+env | grep ISIS | sort
+----
+
+See xref:cg.adoc#_cg_committers_recreating-an-archetype[here] for details on recreating and releasing an archetype.
+
+
+== Get code
+
+Pull down latest, create branch (eg `prepare/isis-1.8.0`):
+
+[source]
+----
+git checkout master
+git pull --ff-only
+git checkout -b $ISISART-$ISISREL
+----
+
+
+== Update parent pom
+
+Check:
+
+* parent is `org.apache:apache` (non-SNAPSHOT version)
+
+
+== Check for SNAPSHOT dependencies
+
+Search for any non-`SNAPSHOT` usages (including tck project, if any):
+
+[source]
+----
+grep SNAPSHOT `/bin/find . -name pom.xml | grep -v target | sort`
+----
+
+or (more thoroughly):
+
+[source]
+----
+vi `/bin/find . -name pom.xml | grep -v target | sort`
+----
+
+== Sanity check
+
+[WARNING]
+====
+Make sure you are in the correct directory (eg `core`, or `example/archetype/zzz`)
+====
+
+
+Clean all local mvn artifacts and rebuild with `-o` flag:
+
+[source]
+----
+cd core
+
+rm -rf ~/.m2/repository/org/apache/isis
+mvn clean install -o
+----
+
+== Check versions
+
+[TIP]
+====
+Actually, you may want to defer this and do after cutting the release (ie beginning of a new dev cycle)
+====
+
+=== Update plugin versions
+
+
+[source]
+----
+mvn versions:display-plugin-updates > /tmp/foo
+grep "\->" /tmp/foo | /bin/sort -u
+----
+
+=== Newer dependencies:
+
+[source]
+----
+mvn versions:display-dependency-updates > /tmp/foo
+grep "\->" /tmp/foo | /bin/sort -u
+----
+
+== Update license information
+
+=== Missing license headers in files:
+
+[source]
+----
+mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o
+for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done
+----
+
+=== Missing/spurious `supplemental-models.xml`
+
+[source]
+----
+mvn license:download-licenses
+if [ "$ISISCOR" == "Y" ]; then
+    groovy ../scripts/checkmissinglicenses.groovy
+else
+    groovy ../../../scripts/checkmissinglicenses.groovy
+fi
+----
+
+== Commit changes
+
+Commit any changes from the preceding steps:
+
+[source]
+----
+git commit -am "ISIS-nnnn: updates to pom.xml etc for release"
+----
+
+== Release
+
+[WARNING]
+====
+Make sure you are in the correct directory (eg `core`, or `example/archetype/zzz`)
+====
+
+=== Prepare:
+
+
+first the dry run:
+
+[source]
+----
+mvn release:prepare -P apache-release \
+                    -DdryRun=true \
+                    -DreleaseVersion=$ISISREL \
+                    -DdevelopmentVersion=$ISISDEV \
+                    -Dtag=$ISISART-$ISISREL-$ISISRC
+----
+
+then "for real": 
+
+[source]
+----
+mvn release:prepare -P apache-release -DskipTests=true -Dresume=false \
+                    -DreleaseVersion=$ISISREL \
+                    -DdevelopmentVersion=$ISISDEV \
+                    -Dtag=$ISISART-$ISISREL-$ISISRC
+----
+
+=== Confirm:
+
+[source]
+----
+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
+----
+
+=== Perform:
+
+[source]
+----
+mvn release:perform -P apache-release \
+    -DworkingDirectory=$ISISTMP/$ISISART-$ISISREL/checkout
+----
+
+[NOTE]
+====
+The `workingDirectory` property is to avoid 260 char path issue if building on Windows.
+====
+
+
+== Nexus staging
+
+Log onto http://repository.apache.org[repository.apache.org] and close the staging repo.
+
+== Git branches/tags
+
+Push branch:
+
+[source]
+----
+git push -u origin $ISISART-$ISISREL
+----
+
+Then push tag:
+
+[source]
+----
+git push origin refs/tags/$ISISART-$ISISREL-$ISISRC:refs/tags/$ISISART-$ISISREL-$ISISRC
+git fetch
+----

[08/10] isis git commit: ISIS-1133: pulling together the contributors guide.

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
new file mode 100644
index 0000000..74f5cda
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
@@ -0,0 +1,145 @@
+[[_cg_committers_verifying-releases]]
+= Verifying Releases
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+Whenever a committer announces a vote on a release on the link:../support.html[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release. Anyone else can also vote, but only members of the Apache Isis PMC's vote are binding.
+
+This page provides some guidance on what a voter is expected to verify before casting their vote. 
+
+Per this http://www.apache.org/dev/release.html[ASF documentation], the legal requirements for an ASF release are:
+
+* a source zip file + corresponding signature (signed by the release manager, which is in the ASF web of trust and in our KEYS file)
+* all source files have the Apache license (this is ensured by the running of the rat plugin prior to release; you could run it on the unzipped source)
+* all dependencies are appropriately licensed; see the `DEPENDENCIES` file which is automatically generated from the POMs plus the supplemental-models.xml file
+
+Note that the binaries are _not_ an ASF release, they merely exist on the Maven central repo as a convenience. That said, you might also want to verify the release by pulling the binaries from the Maven staging repository. Details of how to do this are also documented below.
+
+
+
+== Prerequisites
+
+To verify the source ZIP files, you will need to have imported the public keys used for signing Apache Isis releases. These can be downloaded from the root of the Apache Isis source tree.
+
+Since the Apache Isis source is mirrored on github.com, you can just use:
+
+[source,bash]
+----
+curl http://www.apache.org/dist/isis/KEYS > /tmp/KEYS
+gpg --import /tmp/KEYS
+----
+
+
+
+
+== Verifying the source release artifacts
+
+
+[NOTE]
+====
+Note: to automate this next stage, there is also a xref:cg.adoc#_cg_committers_verifying-releases-using-a-script[script] available; but read what follows first before using the script.
+====
+
+
+Download both the ZIP and .ASC files from the location specified in the voting email. To verify that the signature is correct, use:
+
+[source,bash]
+----
+gpg --verify isis-x.y.z.zip.asc isis-x.y.z.zip
+----
+
+
+
+
+== Building the source release artifacts
+
+Assuming the ZIP file verifies, it should be unpacked, and then the artifact built from source.
+
+First, delete all Isis artifacts from your local Maven repo:
+
+[source,bash]
+----
+rm -rf ~/.m2/repository/org/apache/isis
+----
+
+
+To build Apache Isis core, first download any dependencies:
+
+[source]
+----
+mvn dependency:go-offline
+----
+
+Check that no Isis artifacts have yet been downloaded, ie there is no `~/.m2/org/repository/org/apache/isis` directory. If there are, it could indicate that the release being verified incorrectly references previous versions of Apache Isis core.
+
+Assuming all is ok, build using the `-o` offline flag:
+
+[source]
+----
+mvn clean install -o
+----
+
+Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
+
+
+
+
+
+== Verifying the binary release artifacts (using the Maven staging repository)
+
+If you wish, you can verify the binary releases by configuring your local Maven install to point to the Maven Maven staging repository (or repositories) and then using them, eg to run the link:../intro/getting-started/simpleapp-archetype.html[simpleapp archetype] and running the resultant app.
+
+Configuring your local Maven install amounts to updating the `~/.m2/settings.xml` file:
+
+[source,xml]
+----
+<profiles>
+    <profile>
+        <id>verify-isis</id>
+        <repositories>
+            <repository>
+                <id>isis-core-staging</id>
+                <name>Isis Core Staging</name>
+                <releases>
+                    <enabled>true</enabled>
+                    <updatePolicy>always</updatePolicy>
+                    <checksumPolicy>warn</checksumPolicy>
+                </releases>
+                <url>http://repository.apache.org/content/repositories/orgapacheisis-10xx</url>
+                <layout>default</layout>
+            </repository>
+            ...
+        </repositories>
+    </profile>
+    ...
+</profiles>
+<activeProfiles>
+    <activeProfile>verify-isis</activeProfile>
+    ...
+</activeProfiles>
+----
+
+where the repository URL is as provided in the VOTE email. If there is more than one repository (as is sometimes the case if multiple components have been released), then repeat the <repository> section for each.
+
+Once the vote has completed, the staging repositories will be removed and so you should deactive the profile (comment out the `&lt;activeProfile&gt;` element). If you forget to deactive the profile, there should be no adverse effects; Maven will just spend unnecessary cycles attempting to hit a non-existent repo.
+
+
+
+
+
+== Using the Creadur Tools
+
+The http://creadur.apache.org[Apache Creadur] project exists to provide a set of tools to ensure compliance with Apache's licensing standards. The main release auditing tool, http://creadur.apache.org/rat[Apache RAT], is used in the preparation of the release (as documented link:release-process.html[here]). Creadur's remaining tools are to support the verification process.
+
+At the time of writing, these additional tools are quite young and haven't been formally released; so to use them will take a little bit of work. See link:verifying-releases-using-creadur-tools.html[here] for more details.
+
+
+
+
+== Casting a Vote
+
+When you have made the above checks (and any other checks you think may be relevant), cast your vote by replying to the email thread on the mailing list. If you are casting `-1`, please provide details of the problem(s) you have found.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
new file mode 100644
index 0000000..b0c0aba
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
@@ -0,0 +1,255 @@
+[[_cg_contributing]]
+= Contributing
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+This page explains how you can contribute to Apache Isis. You'll probably also want xref:cg.adoc#_cg_ide[set up your IDE] and learn xref:cg.adoc#_cg_building-isis[how to build Apache Isis].
+
+Thanks for considering to help out, your contributions are appreciated!
+
+
+== Recommended Workflow (github)
+
+Apache Isis' source code is hosted in an Apache git repo (https://git-wip-us.apache.org/repos/asf/isis.git[https], http://git-wip-us.apache.org/repos/asf/isis.git[http]), with a clone on github (https://github.com/apache/isis.git[https], or ssh: `git@github.com:apache/isis.git`.
+
+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 https://github.com/apache/isis.git[apache/isis] repo in github, and then use your fork as a way of publishing your patches for the Apache Isis committers to apply.
+
+The diagram below illustrates the process:
+
+image::{_imagesdir}contributing/git-workflow.png[width="600px",link="{_imagesdir}contributing/git-workflow.png"]
+
+
+That is:
+
+. as a one-time activity, you fork the https://github.com/apache/isis.git[github.com/apache/isis] repo into your own fork on github.com
+. as a one-time activity, you clone your fork to your local computer
+. you set the https://github.com/apache/isis.git[github.com/apache/isis] as your upstream branch; this will allow you to keep your local clone up-to-date with new commits
+* note the asymmetry here: the `upstream` repo (the Apache github repo) is *not* the same as the `origin` repo (your fork).
+. you work on your changes locally; when done, you push them to your github fork
+. to contribute back a change, raise a https://issues.apache.org/jira/browse/ISIS[JIRA] ticket, and ensure your commit message is in the form: `ISIS-nnnn: ...` 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 http://isis.apache.org/support.html[mailing lists].
+. Use github to raise a https://help.github.com/articles/using-pull-requests/[pull request] for your feature
+. An Apache Isis committer will review your change, and apply it if suitable.
+
+
+
+
+== Alternative Workflow (JIRA patches)
+
+As an alternative, you may decide to clone directly from https://github.com/apache/isis.git[github.com/apache/isis] rather than create your own fork:
+
+
+image::{_imagesdir}contributing/git-workflow-2.png[width="600px",link="{_imagesdir}contributing/git-workflow-2.png"]
+
+In this case your `upstream` repo is the same as your `origin` 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.
+
+For the Apache Isis committers it really doesn't matter which route you take, so go with whatever's most comfortable.
+
+
+
+
+== Setting up your fork/clone
+
+If you choose to create your own fork then you'll need an account on https://github.com[github.com]. You then fork simply by pressing the "Fork" button:
+
+
+image::{_imagesdir}contributing/github-forking.png[width="600px",link="{_imagesdir}contributing/github-forking.png"]
+
+
+
+An account isn't needed if you just clone straight from the http://github.com/apache/isis[github.com/apache/isis].
+
+Whether you've forked or not, you then need to clone the repo onto your computer. Github makes this very easy to do:
+
+* for Windows users, we suggest you use github's 'Clone in Windows' feature
+* for Mac/Linux users, create a clone from the command line:
+
+Again, the info is easily found in the github page:
+
+
+
+image::{_imagesdir}contributing/github-cloning.png[width="600px",link="{_imagesdir}contributing/github-cloning.png"]
+
+If you've created your own fork, then you need to add the `upstream` remote to the https://github.com/apache/isis[github.com/apache/isis]. This remote is traditionally called `upstream`. You should then arrange for your `master` branch to track the `upstream/master` remote branch:
+
+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:
+
+
+[source,bash]
+----
+git fetch
+----
+
+
+For more info on tracking branches http://git-scm.com/book/en/Git-Branching-Remote-Branches[here] and http://gitready.com/beginner/2009/03/09/remote-tracking-branches.html[here].
+
+
+
+
+
+== Commit messages
+
+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!
+
+We therefore recommend that your commit messages are as follows [1]:
+
+[source,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.
+----
+
+
+
+Once your git repo is setup, the next thing you'll most likely want to do is to setup your development environment. See link:development-environment.html[here] for more details.
+
+
+
+
+
+== Creating the patch file
+
+If you are working without a github fork of Apache Isis, then you can create the patches from your own local git repository.
+
+As per http://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit[this stackoverflow question], create the patch using `git format-patch`:
+
+[source,bash]
+----
+git format-patch -10 HEAD --stdout > 0001-last-10-commits.patch
+----
+
+Here `-10` 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.
+
+
+
+
+== Sample Contribution Workflow
+
+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.
+
+=== Update your master branch
+
+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.
+
+Irrespective of whether you are using a github fork, the upstream for your local `master` branch will be tracking the appropriate remote's `master` branch. So n either case, the same commands work:
+
+Alternatively, you can combine the `git fetch` and `git merge` and just use `git pull`:
+<pre>
+git checkout master
+git pull –ff-only
+</pre>
+
+If the `merge` or `pull` fails, it means that you must have made commits and there have been changes meanwhile on the remote `master`'s branch. You can use `gitk --all` to confirm. If this fails, see our link:git-cookbook.html[git cookbook] page for a procedure to retrospectively sort out this situation.
+
+
+
+=== Create a topic branch
+
+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 `master` and call it "ISIS-123-blobs"
+
+You can confirm the branch is there and is your new `HEAD` using either `gitk --all`. Alternatively, use the command line:
+
+
+[source,bash]
+----
+$ git checkout -b ISIS-123-blobs
+----
+
+
+The command line prompt should also indicate you are on a branch, isolated from any changes that might happen on the `master` branch.
+
+=== Make File Changes and Commit
+
+Next, make changes to your files using the usual commands (see also our xref:cg.adoc#_cg_git-cookbook[git cookbook] section):
+
+* `git add`
+* `git mv`
+* `git rm`
+* `git commit`
+* `git status`
+
+and so on.
+
+Continue this way until happy with the change. Remember to run all your tests on the topic branch (including a full `mvn clean install`).
+
+
+
+
+=== Rebasing with `master`
+
+Before you can share your change, you should rebase (in other words replay) your changes on top of the `master` branch.
+
+The first thing to do is to pull down any changes made in upstream remote's `master` since you started your topic branch:
+
+These are the same commands that you would have run before you created your topic branch. If you use `gitk --all`, there's a good chance that new commits have come in.
+
+Next, we reintegrate our topic branch by rebasing onto `master`:
+<pre>
+git checkout ISIS-123-blobs
+git rebase master
+</pre>
+
+This takes all of the commits in your branch, and applies them on top of the new `master` branch. When your change is eventually integrated back in, it will result in a nice clear linear history on the public repo.
+
+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:
+
+Once the rebase has completed, re-run your tests to confirm that everything is still good.
+
+
+
+=== Raising a pull request
+
+If you have your own fork, you can now simply push the changes you've made locally to your fork:
+
+This will create a corresponding branch in the remote github repo. If you use `gitk --all`, you'll also see a `remotes/origin/ISIS-123-blobs` branch.
+
+Then, use github to raise a https://help.github.com/articles/using-pull-requests/[pull request]. Pull requests sent to the Apache GitHub repositories will forward a pull request e-mail to the link:../support.html[dev mailing list]. You'll probably want to sign up to the dev mailing list first before issuing your first pull request (though that isn't mandatory).
+
+The process to raise the pull request, broadly speaking:
+
+* Open a web browser to your github fork of isis
+* Select your topic branch (pushed in the previous step) so that the pull request references the topic branch.
+* Click the `Pull Request` button.
+* Check that the Apache Isis mailing list email came through.
+
+
+
+== If your pull request is accepted
+
+To double check that your pull request is accepted, update your `master` branch from the `upstream` remote:
+
+You can then use `gitk --all` (or `git log` if you prefer the command line) to check your contribution has been added.
+
+You can now delete your topic branch and remove the branch in your github:
+
+Finally, you might want to push the latest changes in master back up to your github fork. If so, use:
+
+
+
+=== If your pull request is rejected
+
+If your pull request is rejected, then you'll need to update your branch from the main repository and then address the rejection reason.
+
+You'll probably also want to remove the remote branch on github:
+
+[source,bash]
+----
+git push origin –delete ISIS-123-blobs
+----
+
+
+… and continue as before until you are ready to resubmit your change.
+
+[1] inspiration for the recommended commit format comes from the https://github.com/puppetlabs/puppet[puppet] project's https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md[contributing] page.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
new file mode 100644
index 0000000..70b6870
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
@@ -0,0 +1,258 @@
+[[_cg_git-cookbook]]
+= Appendix: Git Cookbook
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+This section describes the commands often used while working with git.  In addition to these basic commands, please make sure you have read:
+
+* xref:cg.adoc#_cg_building-isis[building Apache Isis]
+* xref:cg.adoc#_cg_git-policy[Git policy]
+* xref:cg.adoc#_cg_contributing[Contributing]
+
+
+
+
+== Modifying existing files
+
+To modify existing files:
+
+[source,bash]
+----
+git add filename
+git commit -m "ISIS-nnn: yada yada"
+----
+
+The `git add` command adds the changes to the file(s) to the git index (aka staging area).  If you were to make subsequent changes to the file these would not be committed.
+ 
+The `git commit` takes all the staged changes and commits them locally.  Note that these changes are not shared public with Apache Isis' central git repo.
+
+You can combine these two commands using `-am` flag to git commit:
+
+[source,bash]
+----
+git commit -am "ISIS-nnn: yada yada"
+----
+
+
+
+
+== Adding new files
+
+To add a new file:
+
+[source,bash]
+----
+git add .
+git commit -m "ISIS-nnn: yada yada"
+----
+
+
+Note that this sequence of commands is identical to modifying an existing file.  However, it isn't possible to combine the two steps using `git commit -am`; the `git add` is always needed when adding new files to the repo.
+
+
+
+
+== Deleting files
+
+To delete a file:
+
+[source,bash]
+----
+git rm filename
+git commit -m "ISIS-nnn: yada yada"
+----
+
+
+
+== Renaming or moving files
+
+To rename or move a file:
+
+
+[source,bash]
+----
+git mv <i>filename</i> <i>newfilename</i>
+git commit -m "ISIS-nnn: yada yada"
+----
+
+
+
+
+== Common Workflows
+
+The xref:cg.adoc#_cg_contributing[contributing] page describes the workflow for non-committers.  The xref:cg.adoc#_cg_git-policy[Git policy] page describes a workflow for Apache Isis **committers**.
+
+
+
+
+
+== Backing up a local branch
+
+If committing to a local branch, the changes are still just that: local, and run risk of a disk failure or other disaster.
+
+To create a new, similarly named branch on the central repo, use:
+
+[source,bash]
+----
+git push -u origin <i>branchname</i>
+----
+
+Using `gitk --all` will show you this new branch, named *origin/branchname*.
+
+Thereafter, you can push subsequent commits using simply:
+
+[source,bash]
+----
+git push
+----
+
+
+Doing this also allows others to collaborate on this branch, just as they would for `master`.
+
+When, eventually, you have reintegrated this branch, you can delete the remote branch using:
+
+[source,bash]
+----
+git push origin --delete <i>branchname</i>
+----
+
+
+For more detail, see these blogs/posts link:http://www.mariopareja.com/blog/archive/2010/01/11/how-to-push-a-new-local-branch-to-a-remote.aspx[here] and link:http://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-both-locally-and-in-github[here].
+
+
+
+== Quick change: stashing changes
+
+If you are working on something but are not ready to commit, then use:
+
+[source,bash]
+----
+git stash
+----
+
+
+If you use `gitk --all` then you'll see new commits are made that hold the current state of your working directory and staging area.
+
+You can then, for example, pull down the latest changes using `git pull --rebase` (see above).
+
+To reapply your stash, then use:
+
+[source,bash]
+----
+git stash pop
+----
+
+Note that stashing works even if switching branches
+
+
+## Ignoring files
+
+Put file patterns into `.gitignore`.  There is one at the root of the git repo, but they can additionally appear in subdirectories (the results are cumulative).
+
+See also:
+
+- link:https://help.github.com/articles/ignoring-files[github's help page]
+- link:http://www.kernel.org/pub/software/scm/git/docs/gitignore.html[man page]
+
+
+
+
+== More advanced use cases
+
+=== If accidentally push to remote
+
+Suppose you committed to `master`, and then pushed the change, and then decided that you didn't intend to do that:
+
+[source,bash]
+----
+C1  -  C2  -  C3  -  C4  -  C5  -  C6  -  C7
+                                          ^
+                                          master
+                                          ^
+                                          origin/master
+----
+
+To go back to an earlier commit, first we wind back the local `master`:
+
+[source,bash]
+----
+git reset --hard C5
+----
+
+where `C5` is the long sha-id for that commit.
+
+This gets us to:
+
+[source,bash]
+----
+C1  -  C2  -  C3  -  C4  -  C5  -  C6  -  C7
+                            ^
+                            master
+                                          ^
+                                          origin/master
+----
+
+Then, do a force push:
+
+[source,bash]
+----
+git push origin master --force
+----
+
+If this doesn't work, it may be that the remote repo has disabled this feature.  There are other hacks to get around this, see for example link:http://stackoverflow.com/questions/1377845/git-reset-hard-and-a-remote-repository[here].
+
+
+
+
+== If you've accidentally worked on `master` branch
+
+If at any time the `git pull` from your upstream fails, it most likely means that you must have made commits on the `master` branch.  You can use `gitk --all` to confirm; at some point in time both `master` and `origin\master` will have a common ancestor.
+
+You can retrospectively create a topic branch for the work you've accidentally done on `master`.  
+
+First, create a branch for your current commit:
+
+[source,bash]
+----
+git branch <i>newbranch</i>
+----
+
+
+Next, make sure you have no outstanding edits.  If you do, you should commit them or stash them:
+
+
+[source,bash]
+----
+git stash
+----
+
+
+Finally, locate the shaId of the commit you want to roll back to (easily obtained in `gitk -all`), and wind `master` branch back to that commit:
+
+
+[source,bash]
+----
+git checkout master
+git reset --hard <i>shaId</i>      # move master branch shaId of common ancestor
+----
+
+
+
+== If you've forgotten to prefix your commits (but not pushed)
+
+One of our committers, Alexander Krasnukhin, has put together some git scripts to help his workflow.  Using one of these, `git prefix`, you can just commit with proper message without bothering about prefix and add prefix only in the end *before* the final push.
+ 
+For example, to prefix all not yet prefixed commits `master..isis/666` with `ISIS-666` prefix, use:
+
+[source,bash]
+----
+git prefix ISIS-666 master..isis/666
+----
+
+
+You can grab this utility, and others, from link:https://github.com/themalkolm/git-boots[this repo].

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
new file mode 100644
index 0000000..e425dae
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
@@ -0,0 +1,69 @@
+[[_cg_ide-templates]]
+= IDE Templates
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+We provide IDE templates (for IntelliJ and Eclipse) for writing Apache Isis domain objects, and also for unit tests (JUnit and JMock).
+
+== Download
+
+The following table lists the templates to download
+
+[cols="1a,1a,1a,1a", options="header"]
+|===
+
+|Template
+|Prefix
+|IntelliJ
+|Eclipse
+
+
+|Apache Isis Domain Objects
+|is
+|link:./resources/templates/isis-templates-idea.xml[Download]
+|link:./resources/templates/isis-templates.xml[Download]
+
+
+|JUnit tests
+|ju
+|link:./resources/templates/junit4-templates-idea.xml[Download]
+|link:./resources/templates/junit4-templates.xml[Download]
+
+
+|JMock tests
+|jm
+|link:./resources/templates/jmock2-templates-idea.xml[Download]
+|link:./resources/templates/jmock2-templates.xml[Download]
+
+|===
+
+
+The most commonly used Apache Isis domain objects templates are also listed on the link:./cheat-sheet.html[Apache Isis cheat sheet].
+
+
+
+== Installation
+
+=== IntelliJ
+
+To install in IntelliJ, copy to the relevant `config/templates` directory, eg:
+
+* Windows `<User home>\.IntelliJIdea14\config\templates`
+* Linux `~/.IntelliJIdea14/config/templates`
+* Mac OS `~/Library/Preferences/IntelliJIdea14/templates`
+
+
+=== Eclipse
+
+To install in Eclipse, go to `Windows > Preferences > Java > Editor > Templates` and choose `Import`.
+
+
+
+== Usage
+
+Enter the prefix (`is`, `ju`, `jm`) and the IDE will list all available templates in that category.  
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_ide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide.adoc
new file mode 100644
index 0000000..264060c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide.adoc
@@ -0,0 +1,16 @@
+[[_cg_ide]]
+= Using an IDE
+:Notice: 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.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+
+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.
+
+This chapter shows how to setup and use two of the most popular IDEs, IntelliJ IDEA and Eclipse.
+
+
+include::_cg_ide_intellij.adoc[leveloffset=+1]
+include::_cg_ide_eclipse.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
new file mode 100644
index 0000000..3efa28d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
@@ -0,0 +1,134 @@
+[[_cg_ide_eclipse]]
+= Developing using Eclipse
+:Notice: 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.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+If you are an http://www.eclipse.org[Eclipse] user, then we recommend you download the "Eclipse JEE package" configuration.
+
+When running an Apache Isis application, it's necessary to setup the development environment so that the Java bytecode can be enhanced by the link:http://www.datanucleus.org[DataNucleus] enhancer.  If working in Eclipse, then JDO enhancement is most easily done by installing the http://www.datanucleus.org/products/datanucleus/jdo/guides/eclipse.html[DataNucleus' Eclipse plugin].  This hooks the bytecode enhancement of your domain objects into Eclipse's normal incremental compilation.
+
+This plugin needs to be configured for each of your domain modules (usually just one in any given app).  The steps are therefore:
+
+* import the project into Eclipse
+* configure the DataNucleus enhancer
+* run the app from the `.launch` file
+
+
+
+
+== Screencast
+
+The following screencast shows how to import an Apache Isis maven-based application into Eclipse and configure to use with the JDO Objectstore
+
+video::RgcYfjQ8yJA[youtube,width="640px",height="480px"]
+
+
+
+
+== Importing the Project
+
+Use File &gt; Import, then Maven &gt; Existing Maven Projects.
+
+
+
+
+== Add DataNucleus support
+
+[TIP]
+====
+Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.
+====
+
+
+In Eclipse, for the _domain object model_ project, first add DataNucleus support:
+
+image::{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png"]
+
+
+Then turn on Auto-Enhancement:
+
+image::{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png"]
+
+
+=== Update the classpath
+
+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.
+
+See the earlier section on xref:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+
+Then, tell DataNucleus to use the project classpath:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"]
+
+When the enhancer runs, it will print out to the console:
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
+
+
+
+=== Workaround for path limits (the DN plugin to use the persistence.xml)
+
+If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
+
+To fix this, we configure the enhancer to read from the `persistence.xml` file.
+
+As a prerequisite, first make sure that your domain object model has a `persistence.xml` file.  Then specify the `persistence-unit` in the project properties:
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png"]
+
+
+=== Workaround: If the enhancer fails
+
+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 `Debug` view:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
+
+
+At any rate, you'll know you've encountered this error if you see the following in the console:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"]
+
+
+
+The best solution is to remove DataNucleus support and then to re-add it:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"]
+
+
+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.
+
+Not ideal, we know. Please feel free to contribute a better solution :-)
+
+
+
+
+== Running the App
+
+The simpleapp archetype automatically provides a `.launch` configurations in the `webapp` module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".
+
+
+[NOTE]
+====
+The screencast above shows this in action.
+====
+
+
+
+
+
+== Other domain projects.
+
+There is nothing to prevent you having multiple domain projects. You might want to do such that each domain project corresponds to a http://www.methodsandtools.com/archive/archive.php?id=97p2[DDD module], thus guaranteeing that there are no cyclic dependencies between your modules.
+
+If you do this, make sure that each project has its own `persistence.xml` file.
+
+And, remember also to configure Eclipse's DataNucleus plugin for these other domain projects.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_intellij.adoc
new file mode 100644
index 0000000..739e062
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_intellij.adoc
@@ -0,0 +1,398 @@
+[[_cg_ide_intellij]]
+= Developing using IntelliJ IDEA
+:Notice: 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.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+This section describes how to install and setup IntelliJ, then how to import an application into IntelliJ and run it.
+
+
+[NOTE]
+====
+This document relates to IntelliJ Community Edition 14.1.x, with screenshots taken for Windows.
+====
+
+
+
+== Installing and Setting up
+
+This section covers installation and setup.
+
+=== Download and Install
+
+https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
+
+Start the wizard, click through the welcome page:
+
+.IntelliJ Installation Wizard - Welcome page
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png[width="400px"]
+
+Choose the location to install the IDE:
+
+.IntelliJ Installation Wizard - Choose Location
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/020-choose-location.png[width="400px"]
+
+Adjust any installation options as you prefer:
+
+.IntelliJ Installation Wizard - Installation Options
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/030-installation-options.png[width="400px"]
+
+and the start menu:
+
+.IntelliJ Installation Wizard - Start Menu Folder
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
+
+and finish up the wizard:
+
+.IntelliJ Installation Wizard - Completing the Wizard
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/050-completing.png[width="400px"]
+
+Later on we'll specify the Apache Isis/ASF code style settings, so for now select `I do not want to import settings`:
+
+.IntelliJ Installation Wizard - Import Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
+
+Finally, if you are young and trendy, set the UI theme to Darcula:
+
+.IntelliJ Installation Wizard Set UI Theme
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
+
+
+
+
+=== New Project
+
+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).
+
+Start off by creating a new project:
+
+.IntelliJ Create New Project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
+
+We want to create a new *Java* project:
+
+.IntelliJ Create New Project - Create a Java project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="600px"]
+
+We therefore need to specify the JDK.
+
+NOTE: at the time of writing Apache Isis supports only Java 7; Java 8 is scheduled for support in Apache Isis v1.9.0
+
+
+.IntelliJ Create New Java Project - Select the JDK
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="300px"]
+
+Specify the directory containing the JDK:
+
+.IntelliJ Create New Project - Select the JDK location
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
+
+Finally allow IntelliJ to create the directory for the new project:
+
+.IntelliJ Create New Project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png[width="200px"]
+
+
+
+=== Import Settings
+
+Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions.  These are bundled as the `settings.jar` JAR file link:resources/appendices/dev-env/intellij/isis-settings.jar[download from the Apache Isis website]).
+
+Import using: `File > Import Settings`, and specify the directory that you have downloaded the file to:
+
+.IntelliJ Import Settings - Specify JAR file
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
+
+Select all the (two) categories of settings available in the JAR file:
+
+.IntelliJ Import Settings - Select all categories
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png[width="300px"]
+
+And then restart:
+
+.IntelliJ Import Settings - Restart
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/030-restart.png[width="200px"]
+
+
+
+=== Other Settings
+
+There are also some other miscellaneous settings that we recommend that you adjust (though these are not critical).
+
+First, specify an up-to-date Maven installation, using `File > Settings` (or `IntelliJ > Preferences` if on MacOS):
+
+.IntelliJ Other Settings - Maven Installation
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png[width="600px"]
+
+Still on the Maven settings page, configure as follows:
+
+.IntelliJ Other Settings - Maven Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png[width="600px"]
+
+On the compiler settings page, ensure that `build automatically` is enabled (and optionally `compile independent modules in parallel`):
+
+.IntelliJ Other Settings - Compiler Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png[width="600px"]
+
+On the auto import page, check the `optimize imports on the fly` and `add unambiguous imports on the fly`
+
+.IntelliJ Other Settings - Auto Import
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png[width="600px"]
+
+
+
+=== Plugins
+
+You might also want to set up some additional plugins, using `File > Settings > Plugins` (or equivalently `File > Other Settings > Configure Plugins`).
+
+Recommended are:
+
+* link:https://plugins.jetbrains.com/plugin/7179?pr=idea[Maven Helper] plugin
++
+More on this below.
+
+* link:https://github.com/asciidoctor/asciidoctor-intellij-plugin[AsciiDoctor] plugin
++
+Useful if you are doing any authoring of documents.
+
+Some others you might like to explore are:
+
+.IntelliJ Plugins
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="600px"]
+
+==== Maven Helper Plugin
+
+This plugin provides a couple of great features.  One is better visualization of dependency trees (similar to Eclipse).
+
+If you open a `pom.xml` file, you'll see an additional "Dependencies" tab:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"]
+
+Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by `mvn dependency:tree`, but filterable.
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"]
+
+The plugin also provides the ability to easily run a Maven goal on a project:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"]
+
+This menu can also be bound to a keystroke so that it is available as a pop-up:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"]
+
+
+
+== Importing and Managing Maven Modules
+
+Let's load in some actual code!  We do this by importing the Maven modules.
+
+First up, open up the Maven tool window (`View > Tool Windows > Maven Projects`).  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 _Maven Projects_ window and corresponding (IntelliJ) modules are shown in the _Projects_ window:
+
+.IntelliJ Maven Module Management - Importing Maven modules
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
+
+We can then import another module (from some other directory).  For example, here we are importing the Isis Addons' todoapp example:
+
+
+.IntelliJ Maven Module Management - Importing another Module
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
+
+You should then see the new Maven module loaded in the _Projects_ window and also the _Maven Projects_ window:
+
+.IntelliJ Maven Module Management -
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
+
+If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from `.m2/repository` folder).  So, for example (assuming that the `<version>` is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.
+
+You can press F4 (or use `File > Project Structure`) to see the resolved classpath for any of the modules loaded into the project.
+
+If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you _could_ remove the module; but better is to ignore those modules.  This will remove from the the _Projects_ window but keep them available in the _Maven Projects_ window for when you next want to work on them:
+
+.IntelliJ Maven Module Management - Ignoring Modules
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
+
+Confirm that it's ok to ignore these modules:
+
+.IntelliJ Maven Module Management - Ignoring Modules (ctd)
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
+
+All being well you should see that the _Projects_ window now only contains the code you are working on.  Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from `.m2/repository`):
+
+.IntelliJ Maven Module Management - Updated Projects Window
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
+
+
+
+== Running
+
+Let's see how to run both the app and the tests.
+
+=== Running the App
+
+Once you've imported your Isis application, we should run it.  We do this by creating a Run configuration, using `Run > Edit Configurations`.
+
+Set up the details as follows:
+
+.IntelliJ Running the App - Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
+
+We specify the `Main class` to be `org.apache.isis.WebServer`; 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.
+
+Also note that `Use classpath of module` is the webapp module for your app, and that the `working directory` is `$MODULE_DIR$`.
+
+Next, and most importantly, configure the DataNucleus enhancer to run for your `dom` goal.  This can be done by defining a Maven goal to run before the app:
+
+.IntelliJ Running the App - Datanucleus Enhancer Goal
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
+
+The `-o` flag in the goal means run off-line; this will run faster.
+
+WARNING: 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.
+
+You should now be able to run the app using `Run > Run Configuration`.  The same configuration can also be used to debug the app if you so need.
+
+
+=== Running the Unit Tests
+
+The easiest way to run the unit tests is just to right click on the `dom` module in the _Project Window_, and choose run unit tests.  Hopefully your tests will pass (!).
+
+.IntelliJ Running the App - Unit Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
+
+As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:
+
+.IntelliJ Running the App - Unit Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
+
+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).
+
+=== Running the Integration Tests
+
+Integration tests can be run in the same way as unit tests, however the `dom` module must also have been enhanced.
+
+One approach is to initially run the tests use the right click on the `integtests` 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):
+
+.IntelliJ Running the App - Integration Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
+
+
+
+
+== Hints and Tips
+
+=== Keyboard Shortcuts Cheat Sheets
+
+You can download 1-page PDFs cheat sheets for IntelliJ's keyboard shortcuts:
+* for link:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf[Windows]
+* for MacOS:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]
+
+Probably the most important shortcut on them is for `Find Action`:
+- `ctrl-shift-A` on Windows
+- `cmd-shift-A` on MacOS.
+
+This will let you search for any action just by typing its name.
+
+### Switching between Tool Windows and Editors
+
+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.
+
+* Use `alt-1` through `alt-9` (or `cmd-1` through `alt-9`) to select the tool windows
+** Press it twice and the tool window will hide itself; so can use to toggle
+* If in the _Project Window_ (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 `Esc`.
+** If in the _Terminal Window_, you'll need to press `Shift-Esc`.
+* If on the editor and want to locate the file in (say) the _Project Window_, use `alt-F1`.
+* To change the size of any tool window, use `ctrl-shift-arrow`
+
+Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse.  Peachy!
+
+=== Navigating Around
+
+For all of the following, you don't need to type every letter, typing "ab" will actually search for ".*a.*b.*".
+
+* to open classes or files or methods that you know the name of:
+** `ctrl-N` to open class
+** `ctrl-shift-N` to open a file
+** (bit fiddly this) `ctrl-shift-alt-N` to search for any symbol.
+* open up dialog of recent files: `ctrl-E`
+* search for any file: `shift-shift`
+
+Navigating around:
+* find callers of a method (the call hierarchy): `ctrl-alt-H`
+* find subclasses or overrides: `ctrl-alt-B`
+* find superclasses/interface/declaration: `ctrl-B`
+
+Viewing the structure (ie outline) of a class
+* `ctrl-F12` will pop-up a dialog showing all members
+** hit `ctrl-F12` again to also see inherited members
+
+
+=== Editing
+
+* Extend selection using `ctrl-W`
+** and contract it down again using `ctrl-shift-W`
+* to duplicate a line, it's `ctrl-D`
+** if you have some text selected (or even some lines), it'll actually duplicate the entire selection
+* to delete a line, it's `ctrl-X`
+* to move a line up or down: `shift-alt-up` and `shift-alt-down`
+** if you have selected several lines, it'll move them all togethe
+* `ctrl-shift-J` can be handy for joining lines together
+** just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")
+
+### Intentions and Code Completion
+
+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.
+
+Code completion usually happens whenever you type '.'.  You can also use `ctrl-space` to bring these up.
+
+In certain circumstances (eg in methods0) you can also type `ctrl-shift-space` to get a smart list of methods etc that you might want to call.  Can be useful.
+
+Last, when invoking a method, use `ctrl-P` to see the parameter types.
+
+
+=== Refactoring
+
+Loads of good stuff on the `Refactor` menu; most used are:
+
+* Rename (`shift-F6`)
+* Extract
+** method: `ctrl-alt-M`
+** variable: `ctrl-alt-V`
+* Inline method/variable: `ctrl-alt-N`
+* Change signature
+
+If you can't remember all those shortcuts, just use `ctrl-shift-alt-T` (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object
+
+
+=== Troubleshooting
+
+When a Maven module is imported, IntelliJ generates its own project files (suffix `.ipr`), and the application is actually built from that.
+
+Occasionally these don't keep in sync (even if auto-import of Maven modules has been enabled).
+
+To fix the issue, try:
+* reimport module
+* rebuild selected modules/entire project
+* remove and then re-add the project
+* restart, invalidating caches
+* hit StackOverflow (!)
+
+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 `File > Synchronize`, `ctrl-alt-Y`.
+
+
+
+
+== Advanced
+
+In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
+
+
+=== Setting up Dynamic Reloading
+
+NOTE: TODO - see link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
+
+
+=== Setting up JRebel
+
+NOTE: TODO

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
new file mode 100644
index 0000000..327f14a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
@@ -0,0 +1,9 @@
+[[_cg_isis-maven-plugin]]
+= Apache Isis Maven Plugin
+:Notice: 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.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+NOTE: TODO
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_policies.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_policies.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_policies.adoc
new file mode 100644
index 0000000..df3b302
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_policies.adoc
@@ -0,0 +1,14 @@
+[[_cg_policies]]
+= Policies
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+This chapter pulls together various policy documents relating to the development of Apache Isis'.
+
+include::_cg_policies_versioning-policy.adoc[leveloffset=+1]
+include::_cg_policies_git-policy.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_policies_git-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_policies_git-policy.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_policies_git-policy.adoc
new file mode 100644
index 0000000..3de8b36
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_policies_git-policy.adoc
@@ -0,0 +1,98 @@
+[[_cg_policies_git-policy]]
+= Git Policy
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:
+
+* git commits form an acyclic graph, with each commit pointing to its parent commit (or commit**s**, if a merge)
+
+* a branch is merely a pointer to one of these commits; git calls the main branch `master`
+
+* git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.
+
+For more background reading, see:
+
+* http://git-scm.com/book[Pro Git] book (free in electronic form)
+* https://github.s3.amazonaws.com/media/book.pdf[Git community book]
+* http://git-scm.com/2011/07/11/reset.html[git reset demystified] - differentiating the working directory vs index/staging area
+
+And, of course, there is loads of good advice on http://stackoverflow.com/questions/tagged/git[stackoverflow.com]
+
+
+
+== Workflow
+
+There are many ways of using Git, but the Apache Isis committers have adopted the following workflow:
+
+* create a topic branch for a feature +
++
+[source,bash]
+----
+git checkout -b ISIS-999
+----
+
+* periodically, push the branch to origin (for safekeeping): +
++
+[source,bash]
+----
+git push origin ISIS-999
+----
+
+
+* `rebase` the topic branch periodically on master. +
++
+How often you do this will depend on whether you are collaborating with others on the feature.  You need to ensure that your co-worker has no outstanding work before you do this; otherwise it'll create merge conflict hell for them:
++
+[source,bash]
+----
+git checkout master
+git pull
+git checkout ISIS-999
+git rebase master
+git push origin ISIS-999 --force
+----
+
+* when feature is complete, rebase once more (as above), then switch to master and perform a `merge --no-ff`: +
++
+[source,bash]
+----
+git checkout master
+git merge --no-ff ISIS-999
+----
+
+* finally, remove the branch +
++
+[source,bash]
+----
+git branch -d ISIS-999
+git push origin --delete ISIS-999
+----
+
+This way of working gives us the full history on the branch as to what the thought processes were for the feature, but only a single commit on to `master` to see the ultimate impact of the changes (acting a bit like a summary).
+
+
+
+
+
+== Commit message
+
+The minimum we expect in a commit messages is:
+
+[source,bash]
+----
+ISIS-nnn: brief summary here
+
+- optionally, longer details
+- should be written here
+- in bullet points
+----
+
+
+where `ISIS-nnn` is a ticket raised in our https://issues.apache.org/jira/browse/ISIS[JIRA issue tracker].
+
+For non-committers we typically expect more detail again; see the xref:cg.adoc#_cg_contributing[contributing] page for the longer format recommended for contributors to use.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_policies_versioning-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_policies_versioning-policy.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_policies_versioning-policy.adoc
new file mode 100644
index 0000000..c04fb4a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_policies_versioning-policy.adoc
@@ -0,0 +1,35 @@
+[[_cg_committers_versioning-policy]]
+= Versioning Policy
+:notice: 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.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+
+## Semantic Versioning
+
+Starting from v1.0.0, Apache Isis has adopted link:http://semver.org[semantic versioning] for its versioning policy.
+
+Version numbers are in the form `x.y.z`:
+
+- x is bumped up whenever there a breaking API change
+- y is bumped up whenever there is a new feature that does not break API
+- z is bumped up for minor bug fixes.
+
+This scheme would be adopted for both core and components.  
+
+
+
+
+
+
+## Version ranges
+
+Version ranges may not be used.  If necessary, end-users can use `<dependencyManagement` elements to have combine components built against different versions of core.
+
+That said, this can introduce instability and so generally we recommend that end-users configure the `maven-enforcer-plugin` and its link:http://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html[DependencyConvergence] rule.  This will help avoid "jar hell" (components having conflicting dependencies of core).
+
+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.

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
deleted file mode 100644
index 57754ac..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_dg_cmd-line]]
-= Developing from the Command Line
-:Notice: 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.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-NOTE: TODO
-

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
deleted file mode 100644
index 625f404..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
+++ /dev/null
@@ -1,136 +0,0 @@
-[[_dg_eclipse]]
-= Setting up Eclipse
-:Notice: 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.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-
-We highly recommend that you develop your Isis application using an IDE. Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
-
-If you are an http://www.eclipse.org[Eclipse] user, then we recommend you download the "Eclipse JEE package" configuration.
-
-When running an Isis application, it's necessary to setup the development environment so that the Java bytecode can be enhanced by the link:http://www.datanucleus.org[DataNucleus] enhancer.  If working in Eclipse, then JDO enhancement is most easily done by installing the http://www.datanucleus.org/products/datanucleus/jdo/guides/eclipse.html[DataNucleus' Eclipse plugin].  This hooks the bytecode enhancement of your domain objects into Eclipse's normal incremental compilation.
-
-This plugin needs to be configured for each of your domain modules (usually just one in any given app).  The steps are therefore:
-
-* import the project into Eclipse
-* configure the DataNucleus enhancer
-* run the app from the `.launch` file
-
-
-
-
-== Screencast
-
-The following screencast shows how to import an Apache Isis maven-based application into Eclipse and configure to use with the JDO Objectstore
-
-video::RgcYfjQ8yJA[youtube,width="640px",height="480px"]
-
-
-
-
-== Importing the Project
-
-Use File &gt; Import, then Maven &gt; Existing Maven Projects.
-
-
-
-
-== Add DataNucleus support
-
-[TIP]
-====
-Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.
-====
-
-
-In Eclipse, for the _domain object model_ project, first add DataNucleus support:
-
-image::{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png"]
-
-
-Then turn on Auto-Enhancement:
-
-image::{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png"]
-
-
-=== Update the classpath
-
-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.
-
-See the earlier section on xref:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-
-Then, tell DataNucleus to use the project classpath:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"]
-
-When the enhancer runs, it will print out to the console:
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
-
-
-
-=== Workaround for path limits (the DN plugin to use the persistence.xml)
-
-If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
-
-To fix this, we configure the enhancer to read from the `persistence.xml` file.
-
-As a prerequisite, first make sure that your domain object model has a `persistence.xml` file.  Then specify the `persistence-unit` in the project properties:
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png"]
-
-
-=== Workaround: If the enhancer fails
-
-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 `Debug` view:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
-
-
-At any rate, you'll know you've encountered this error if you see the following in the console:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"]
-
-
-
-The best solution is to remove DataNucleus support and then to re-add it:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"]
-
-
-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.
-
-Not ideal, we know. Please feel free to contribute a better solution :-)
-
-
-
-
-== Running the App
-
-The simpleapp archetype automatically provides a `.launch` configurations in the `webapp` module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".
-
-
-[NOTE]
-====
-The screencast above shows this in action.
-====
-
-
-
-
-
-== Other domain projects.
-
-There is nothing to prevent you having multiple domain projects. You might want to do such that each domain project corresponds to a http://www.methodsandtools.com/archive/archive.php?id=97p2[DDD module], thus guaranteeing that there are no cyclic dependencies between your modules.
-
-If you do this, make sure that each project has its own `persistence.xml` file.
-
-And, remember also to configure Eclipse's DataNucleus plugin for these other domain projects.
-

[04/10] isis git commit: ISIS-1133: pulling together the contributors guide.

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/key-generation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/key-generation.adoc b/adocs/documentation/src/main/asciidoc/key-generation.adoc
deleted file mode 100644
index aa8ca53..0000000
--- a/adocs/documentation/src/main/asciidoc/key-generation.adoc
+++ /dev/null
@@ -1,572 +0,0 @@
-[[key-generation]]
-= Key Generation
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-In order that a contributor can make a release it is necessary for them to have generated a key and had that key recognized by other members of the Apache Software Foundation. 
-
-For further background information on this topic, see the http://www.apache.org/dev/release-signing.html[release signing page] and the http://www.apache.org/dev/openpgp.html#generate-key[openpgp page] on the Apache wiki.
-
-
-
-== Install and Configure gpg
-
-Download and install GnuPG (gpg), version 1.4.10 or higher.
-
-Then, edit `~/.gnupg/gpg.conf` (on Windows, the file to edit is `C:\Users\xxx\AppData\Roaming\gnupg\gpg.conf`) so that the default is to generate a strong key:
-
-[source,bash]
-----
-personal-digest-preferences SHA512
-cert-digest-algo SHA512
-default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
-----
-
-
-
-
-== Key Generation
-
-The Apache Software Foundation requires that keys are signed with a key (or subkey) based on RSA 4096 bits. To do this:
-
-[source]
-----
-$ gpg --gen-key
-gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Please select what kind of key you want:
-   (1) RSA and RSA (default)
-   (2) DSA and Elgamal
-   (3) DSA (sign only)
-   (4) RSA (sign only)
-Your selection?
-----
-
-Specify RSA key:
-
-[source]
-----
-Your selection? 1
-
-RSA keys may be between 1024 and 4096 bits long.
-What keysize do you want? (2048)
-----
-
-Specify key length as 4096 bits:
-
-[source]
-----
-What keysize do you want? (2048) 4096
-Requested keysize is 4096 bits
-
-Please specify how long the key should be valid.
-         0 = key does not expire
-      <n>  = key expires in n days
-      <n>w = key expires in n weeks
-      <n>m = key expires in n months
-      <n>y = key expires in n years
-Key is valid for? (0)
-----
-
-Specify key as non-expiring:
-
-[source]
-----
-Key is valid for? (0) 0
-Key does not expire at all
-Is this correct? (y/N) y
-
-You need a user ID to identify your key; the software constructs the user ID
-from the Real Name, Comment and Email Address in this form:
-    "Heinrich Heine (Der Dichter) <he...@duesseldorf.de>"
-
-Real name: 
-----
-
-Enter your name, email and comment:
-
-* use your apache.org email
-* the comment should be "CODE SIGNING KEY"
-
-Real name: Xxx Xxxxxxxxx
-Email address: link:mailto:&#x78;&#120;&#120;&#64;&#97;&#x70;&#97;&#99;&#104;&#x65;&#46;&#111;&#x72;&#103;[&#x78;&#120;&#120;&#64;&#97;&#x70;&#97;&#99;&#104;&#x65;&#46;&#111;&#x72;&#103;]
-Comment: CODE SIGNING KEY
-You selected this USER-ID:
- "Xxx Xxxxxxxxx (CODE SIGNING KEY) link:mailto:&#x78;&#x78;&#x78;&#x40;&#97;&#x70;&#97;&#99;h&#101;&#x2e;&#x6f;r&#x67;[&#x78;&#x78;&#x78;&#x40;&#97;&#x70;&#97;&#99;h&#101;&#x2e;&#x6f;r&#x67;]"
-
-Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
-
-You need a Passphrase to protect your secret key.
-Enter passphrase:
-
-Provide a passphrase to secure your key.
-
-[source]
-----
-Enter passphrase:
-Repeat passphrase:
-----
-
-GPG will goes on to generate your key:
-
-[source]
-----
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-...+++++
-.........................+++++
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-....+++++
-...+++++
-gpg: key nnnnnnnn marked as ultimately trusted
-public and secret key created and signed.
-
-gpg: checking the trustdb
-gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
-gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
-pub   4096R/nnnnnnnn yyyy-mm-dd
-      Key fingerprint = xxxx xxxx xxxx xxxx xxxx  xxxx xxxx xxxx xxxx xxxx
-uid                  Xxx Xxxxxx <xx...@apache.org>
-sub   4096R/kkkkkkkk yyyy-mm-dd
-----
-
-The public key with id nnnnnnnn should now be stored in `~/.gnupg/pubring.pgp` (on Windows 7, this is in `c:/Users/xxx/AppData/Roaming/gnupg/pubring.pgp`).
-
-To confirm the key has been generated, use:
-
-[source]
-----
-$ gpg --list-keys --fingerprint
-----
-
-The key Id is the one true way to identify the key, and is also the last 8 digits of the fingerprint. The corresponding secret key for id `nnnnnnnn` is stored in `~/.gnupg/secring.pgp` (on Windows 7, this is in `c:/Users/xxx/AppData/Roaming/gnupg/secring.pgp`).
-
-It's also worth confirming the key has the correct preference of algorithms (reflecting the initial configuration we did earlier). For this, enter the gpg shell for your new key:
-
-[source]
-----
-$ gpg --edit-key nnnnnnnnn
->gpg
-----
-
-where `nnnnnnnn` is your key id. Now, use the 'showpref' subcommand to list details:
-
-[source]
-----
-gpg> showpref
-[ultimate] (1). Xxx Xxxxxxxx (CODE SIGNING KEY) <xx...@apache.org>
-     Cipher: AES256, AES192, AES, CAST5, 3DES
-     Digest: SHA512, SHA384, SHA256, SHA224, SHA1
-     Compression: ZLIB, BZIP2, ZIP, Uncompressed
-     Features: MDC, Keyserver no-modify
-
-gpg>
-----
-
-The Digest line should list SHA-512 first and SHA-1 last. If it doesn't, use the "setpref" command:
-
-[source]
-----
-setpref SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
-----
-
-Finally, remember to take a backup of your key and the keyring (ie, backup the `.gnupg` directory and its contents).
-
-== Subkey Generation
-
-It's recommended to use a subkey with an expiry date to sign releases, rather than your main, non-expiring key. If a subkey is present, then gpg will use it for signing in preference to the main key.
-
-[NOTE]
-====
-After (binary) release artifacts are created, they are deployed to the ASF's Nexus staging repository. However, Nexus seems unable to retrieve a subkey from the public key server. Until we find a fix/workaround for this, all releases should be signed just with a regular non-expiring main key.
-====
-
-
-
-To create a subkey Enter the gpg shell using (the identifier of) your main key:
-
-[source]
-----
-gpg --edit-key xxxxxxxx
-gpg>
-----
-
-Type 'addkey' to create a subkey, and enter your passphrase for the main key:
-
-[source]
-----
-gpg> addkey
-Key is protected.
-[enter your secret passphrase]
-
-You need a passphrase to unlock the secret key for
-user: "Dan Haywood (CODE SIGNING KEY) <da...@apache.org>"
-4096-bit RSA key, ID xxxxxxxx, created 2011-02-01
-
-Please select what kind of key you want:
-   (3) DSA (sign only)
-   (4) RSA (sign only)
-   (5) Elgamal (encrypt only)
-   (6) RSA (encrypt only)
-Your selection?
-----
-
-Select (6) to choose an RSA key for encryption:
-
-[NOTE]
-====
-It would seem that Nexus repository manager does not recognize RSA subkeys with an 'S'ign usage; see this discussion on a mailing list and this issue on Sonatype's JIRA
-====
-
-
-[source]
-----
-Your selection? 6
-
-RSA keys may be between 1024 and 4096 bits long.
-What keysize do you want? (2048) 4096
-
-Requested keysize is 4096 bits
-
-Please specify how long the key should be valid.
-         0 = key does not expire
-      <n>  = key expires in n days
-      <n>w = key expires in n weeks
-      <n>m = key expires in n months
-      <n>y = key expires in n years
-Key is valid for?
-----
-
-Specify that the key is valid for 1 year:
-
-[source]
-----
-Key is valid for? (0) 1y
-
-Key expires at yy/MM/dd hh:mm:ss
-Is this correct? (y/N) y
-Really create? (y/N) y
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-...+++++
-.+++++
-
-pub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: never       usage: SC
-                     trust: ultimate      validity: ultimate
-sub  4096R/xxxxxxxx  created: yyyy-mm-dd  expires: yyYY-mm-dd  usage: E
-[ultimate] (1). Dan Haywood (CODE SIGNING KEY) <da...@apache.org>
-
-gpg>
-----
-
-Quit the gpg shell; you now have a subkey.
-
-== Generate a Revocation Certificate
-
-It's good practice to generate a number of revocation certificates so that the key can be revoked if it happens to be compromised. See the http://www.apache.org/dev/openpgp.html#revocation-certs[gpg page] on the Apache wiki for more background on this topic.
-
-First, generate a "no reason specified" key:
-
-[source]
-----
-$ gpg --output revoke-nnnnnnnn-0.asc --armor --gen-revoke nnnnnnnn
-
-sec  4096R/nnnnnnnn yyyy-mm-dd Xxx Xxxxxxx (CODE SIGNING KEY) <xx...@apache.org>
-Create a revocation certificate for this key? (y/N) Y
-
-Please select the reason for the revocation:
-  0 = No reason specified
-  1 = Key has been compromised
-  2 = Key is superseded
-  3 = Key is no longer used
-  Q = Cancel
-(Probably you want to select 1 here)
-Your decision?
-----
-
-Select 0.
-
-[source]
-----
-Your decision? 0
-
-Enter an optional description; end it with an empty line:
-----
-
-Provide a description:
-
-[source]
-----
-> Generic certificate to revoke key, generated at time of key creation.
->
-Reason for revocation: No reason specified
-Generic certificate to revoke key, generated at time of key creation.
-Is this okay? (y/N)
-----
-
-Confirm this is ok.
-
-[source]
-----
-Is this okay? y
-
-You need a passphrase to unlock the secret key for
-user: "Xxx Xxxxxxx (CODE SIGNING KEY) <xx...@apache.org>"
-4096-bit RSA key, ID nnnnnnnn, created yyyy-mm-dd
-
-Enter passphrase:
-</pre>
-
-Enter a passphrase:
-
-<pre>
-Enter passphrase:
-Revocation certificate created.
-
-Please move it to a medium which you can hide away; if Mallory gets
-access to this certificate he can use it to make your key unusable.
-It is smart to print this certificate and store it away, just in case
-your media become unreadable.  But have some caution:  The print system of
-your machine might store the data and make it available to others!
-----
-
-The file `revoke-nnnnnnnn-0.asc` should be created: Then, backup this file.
-
-Now repeat the process to create two further revocation certificates:
-
-[source,bash]
-----
-gpg --output revoke-nnnnnnnn-1.asc --armor --gen-revoke nnnnnnnn
-----
-
-Specify reason as "1 = Key has been compromised"
-
-and:
-
-[source,bash]
-----
-gpg --output revoke-nnnnnnnn-3.asc --armor --gen-revoke nnnnnnnn
-----
-
-Specify reason as "3 = Key is no longer used"
-
-Backup these files also.
-
-
-
-
-
-== Publish Key
-
-It is also necessary to publish your key. There are several places where this should be done. In most cases, you'll need the "armored" &quot; (ie ASCII) representation of your key. This can be generated using:
-
-[source]
-----
-$ gpg --armor --export nnnnnnnn > nnnnnnnn.asc
-----
-
-where `nnnnnnnn` is the id of your public key.
-
-You'll also need the fingerprint of your key. This can be generated using:
-
-[source]
-----
-$ gpg --fingerprint nnnnnnnn
-----
-
-The output from this command includes a line beginning "Key fingerprint", followed by a (space delimited) 40 character hexadecimal fingerprint. The last 8 characters should be the same as the key id (`nnnnnnnn`).
-
-=== Publish to a public key server
-
-To a publish your key to a public key server (eg the MIT key server hosted at http://pgp.mit.edu[http://pgp.mit.edu]), use the procedure below. Public key servers synchronize with each other, so publishing to one key server should be sufficient. For background reading on this, see the http://www.apache.org/dev/release-signing.html#keyserver-upload[release signing page] on the Apache wiki, and the http://maven.apache.org/developers/release/pmc-gpg-keys.html[gpg key page] on the Maven wiki.
-
-To send the key up to the key server:
-
-[source]
-----
-$ gpg --send-keys --keyserver pgp.mit.edu nnnnnnnn
-----
-
-where `nnnnnnnn` is the key Id.
-
-Alternatively, you can browse to the http://pgp.mit.edu/[MIT key server] and paste in the armored representation of your key.
-
-Confirm the key has been added by browsing to submitting the following URL:
-
-`http://pgp.mit.edu:11371/pks/lookup?search=0xnnnnnnnnn&amp;op=vindex`
-
-again, where `nnnnnnnn` is the key Id.
-
-=== Publish to your Apache home directory
-
-The armored representation of your public key should be uploaded to your home directory on `people.apache.org`, and renamed as `.pgpkey`. Make sure this is readable by all.
-
-=== Publish to your Apache HTML home directory
-
-The armored representation of your public key should be uploaded to your `public_html` home directory on `people.apache.org`, named `nnnnnnnn.asc`. Make sure this is readable by all.
-
-Check the file is accessible by browsing to:
-
-`http://people.apache.org/~xxxxxxxx/nnnnnnnn.asc`
-
-where
-
-* `xxxxxxxx` is your apache LDAP user name
-* `nnnnnnnn` is your public key id.
-
-=== FOAF
-
-First, check out the committers/info directory:
-
-Go to Apache http://people.apache.org/foaf/foafamatic.html[FOAF-a-matic] web page to generate the FOAF file text (we copy this text out in a minute):
-
-* enter ASF LDAP user name
-* enter First name, Last name
-* for PGP key fingerprints, add Key
-* paste in the key id
-* paste in the fingerprint
-* press "Create"
-
-In the box below, you should have a FOAF file, something like:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<rdf:RDF
-      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-      xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
-      xmlns:foaf="http://xmlns.com/foaf/0.1/"
-      xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
-      xmlns:pm="http://www.web-semantics.org/ns/pm#"
-      xmlns:wot="http://xmlns.com/wot/0.1/"
-      xmlns:rss="http://purl.org/rss/1.0/"
-      xmlns:dc="http://purl.org/dc/elements/1.1/"
-      xmlns:ical="http://www.w3.org/2002/12/cal/ical#"
-      xmlns:doap="http://usefulinc.com/ns/doap#">
-  <foaf:Person rdf:ID="danhaywood">
-    <foaf:name>Xxx Xxxxxxxx</foaf:name>
-    <foaf:givenname>Xxx</foaf:givenname>
-    <foaf:family_name>Xxxxxxxx</foaf:family_name>
-    <wot:hasKey>
-      <wot:PubKey>
-        <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
-        <wot:hex_id>nnnnnnnn</wot:hex_id>
-      </wot:PubKey>
-    </wot:hasKey>
-  </foaf:Person>
-</rdf:RDF>
-----
-
-(If you are creating the FOAF file for the first time, you may want to add additional details).
-
-From this, copy out the `wot:key`, and paste into your FDF file in `committers/info`:
-
-[source,xml]
-----
-<wot:hasKey>
-  <wot:PubKey>
-    <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
-    <wot:hex_id>nnnnnnnn</wot:hex_id>
-  </wot:PubKey>
-</wot:hasKey>
-----
-
-Then, manually add in a `&lt;wot:pubkeyAddress&gt;` element within `&lt;wot:PubKey&gt;`:
-
-[source,xml]
-----
-<wot:hasKey>
-  <wot:PubKey>
-    <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn  nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
-    <wot:hex_id>nnnnnnnn</wot:hex_id>
-    <wot:pubkeyAddress rdf:resource="http://people.apache.org/~username/nnnnnnnn.asc/">
-  </wot:PubKey>
-</wot:hasKey>
-----
-
-ie, referencing your publically exported public key
-
-Finally, commit your changes.
-
-=== Save to `KEYS`
-
-The armored representation of the public key should be saved to Apache Isis' `KEYS` file, http://www.apache.org/dist/isis/KEYS[http://www.apache.org/dist/isis/KEYS] (that is, in the ASF distribution directory for Apache Isis).
-
-First, in a new directory, checkout this file:
-
-[source]
-----
-svn -N co https://svn.apache.org/repos/asf/isis/ .
-----
-
-This should bring down the `KEYS` file.
-
-Then, export your signature and armored representation.
-
-[source]
-----
-gpg --list-sigs nnnnnnnn >>KEYS
-gpg --armor --export nnnnnnnn >>KEYS
-----
-
-Then commit.
-
-=== id.apache.org
-
-Log onto `id.apache.org` and ensure that the finger print of your public key is correct.
-
-== Attend Key Signing Party (Apache web of trust)
-
-It is strongly advised that the contributor attend a key signing party at an Apache event, in order that other Apache committers/members can in person verify their identity against the key. The process for this is described http://www.apache.org/dev/release-signing.html#key-signing-party[here] and http://wiki.apache.org/apachecon/PgpKeySigning[here].
-
-== Update Maven Settings file (`~/.m2/settings.xml`)
-
-The Maven release plugin will automatically sign the release, however it is necessary to update the `~/.m2/settings.xml` file with your GPG acronym passphrase in order that it can use your secret key. This is defined under a profile so that it is activated only when we perform a release (as defined by `[org,apache:apache]` parent POM.
-
-Therefore, make the following edits:
-
-[source,xml]
-----
-<settings>
-  ...
-  <profiles>
-    <profile>
-      <id>apache-release</id>
-      <properties>
-        <gpg.passphrase>xxx xxx xxx xxx xxx xxx xxx</gpg.passphrase>
-      </properties>
-    </profile>
-  </profiles>
-</settings>
-----
-
-In addition, to allow the release plugin to tag SVN changes, you must either add in your LDAP username/password or configure `.ssh`:
-
-[source,xml]
-----
-<settings>
-  ...
-  <servers>
-    ...
-    <server>
-      <id>apache.releases.https</id>
-      <username>xxxx</username>
-      <password>xxxx</password>
-    </server>
-  </servers>
-</settings>
-----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/pmc-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pmc-notes.adoc b/adocs/documentation/src/main/asciidoc/pmc-notes.adoc
deleted file mode 100644
index 8ccbadb..0000000
--- a/adocs/documentation/src/main/asciidoc/pmc-notes.adoc
+++ /dev/null
@@ -1,73 +0,0 @@
-[[pmc-note]]
-= PMC Notes
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-
-[NOTE]
-====
-These are some general jottings on occasionally performed tasks by the PMC.  ASF documents can be found http://www.apache.org/dev/pmc.html[here]
-====
-
-
-
-== Accessing `people.apache.org`
-
-Must be accessed via ssh.
-
-eg:
-
-[source]
-----
-ssh danhaywood@people.apache.org
-----
-
-and when prompted, provide passphrase for private key... though I've forgotten what I did to set this up in the first place, though :-(
-
-
-
-
-== LDAP Access (UNIX groups)
-
-Whenever we get a new committer, the ASF LDAP entries must be maintained to grant access to our repos and various other 'karma'.
-
-Log onto `people.apache.org`, then use:
-
-[source]
-----
-list_unix_group.pl isis
-----
-
-to list committers
-
-[source]
-----
-list_committee.pl isis
-----
-
-to list the PMC committee members (in Apache Isis, every committer should be on the PMC committee)
-
-To change membership of either the committers or the PMC, use:
-
-[source]
-----
-modify_unix_group.pl isis --add joebloggs
-modify_unix_group.pl isis --remove joebloggs
-----
-
-and
-
-[source]
-----
-modify_committee.pl gump --add joebloggs
-modify_committee.pl gump --remove joebloggs
-----
-
-respectively.
-
-Further details are in http://www.apache.org/dev/pmc.html#SVNaccess[these ASF docs]. (They talk about SVN access, but really it is LDAP access).
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/recreating-an-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/recreating-an-archetype.adoc b/adocs/documentation/src/main/asciidoc/recreating-an-archetype.adoc
deleted file mode 100644
index 8073dc4..0000000
--- a/adocs/documentation/src/main/asciidoc/recreating-an-archetype.adoc
+++ /dev/null
@@ -1,337 +0,0 @@
-[[recreating-an-archetype]]
-= Recreating an Archetype
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-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.
-
-
-
-== Setup environment variables
-
-To recreate the *simpleapp* archetype:
-
-[source,bash]
-----
-cd example/application/simpleapp
-
-export ISISTMP=/c/tmp   # or as required
-export ISISART=simpleapp-archetype
-export ISISDEV=1.9.0-SNAPSHOT
-export ISISREL=1.8.0
-export ISISPAR=1.8.0
-export ISISRC=RC1
-
-export ISISCPT=$(echo $ISISART | cut -d- -f2)
-export ISISCPN=$(echo $ISISART | cut -d- -f1)
-
-env | grep ISIS | sort
-----
-
-nb: `$ISISPAR` is the version of the Apache Isis core that will act as the archetype's parent. Usually this is the same as `$ISISREL`.
-
-
-
-== Check the example app
-
-Make sure you are in the correct directory, and update the parent `pom.xml` to reference the _released_ version of Apache Isis core:
-
-[source,xml]
-----
-<properties>
-    <isis.version>1.8.0</isis.version>
-    ...
-</properties>
-----
-
-Alternatively, you could just load up each `pom.xml` and inspect manually:
-
-[source,bash]
-----
-vi `/bin/find . -name pom.xml | grep -v target`
-----
-
-... and search for `SNAPSHOT`.
-
-Next, check for and fix any missing license header notices:
-
-[source,bash]
-----
-mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o
-for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done
-----
-
-Finally, double check that the app is running satisfactorily:
-
-first, as self-hosted webconsole (browse to http://localhost:8080[http://localhost:8080]):
-
-[source,bash]
-----
-mvn clean install
-mvn antrun:run -P self-host
-----
-
-then using mvn jetty plugin:
-
-[source,bash]
-----
-cd webapp
-mvn jetty:run     
-----
-
-Browse to http://localhost:8080/simpleapp-webapp/[http://localhost:8080/simpleapp-webapp/].
-
-Check the about page and confirm built against non-SNAPSHOT versions of the Apache Isis jars.
-
-
-
-=== Create the archetype (manual)
-
-[IMPORTANT]
-====
-The archetype can be created either by hand or with a script. The section describes the manual approach; the scripted approach is in the section after.
-====
-
-
-Before we generate the archetype, we clear out all non source code artifacts.
-
-Start by doing the regular `mvn clean`:
-
-[source,bash]
-----
-mvn clean
-----
-
-To view the remaining files/directories that needs removing, use:
-
-[source,bash]
-----
-for a in .project .classpath .settings bin .idea target-ide; do /bin/find . -name $a -print; done
-/bin/find . -name "*.iml" -print
-/bin/find . -name "*.log" -print
-/bin/find . -name "pom.xml.*" -print
-----
-
-To actually delete these files, use:
-
-[source,bash]
-----
-for a in .project .classpath .settings bin .idea target-ide; do /bin/find . -name $a -exec rm -r {} \;; done
-/bin/find . -name "*.iml" -exec rm {} \;
-/bin/find . -name "*.log" -exec rm {} \;
-/bin/find . -name "pom.xml.*" -exec rm {} \;
-----
-
-Quickly check that the remaining files are all source files:
-
-[source,bash]
-----
-/bin/find .
-----
-
-Now we can create the archetype.
-
-[source,bash]
-----
-mvn archetype:create-from-project
-----
-
-and then update the generated files:
-
-[source,bash]
-----
-groovy ../../../scripts/updateGeneratedArchetypeSources.groovy -n $ISISCPN -v $ISISPAR
-----
-
-where:
-
-* `$ISISCPN` is the component name set earlier (`simpleapp`)
-* `$ISISPAR` is the version of Apache isis core that is to be the parent of the generated archetype,
-** this will usually be the same as `$ISISREL` unless a patch/interim release of the archetype.
-
-
-
-
-=== Test the archetype
-
-First, build the archetype:
-
-[source,bash]
-----
-cd target/generated-sources/archetype
-mvn clean install
-cd ../../..
-----
-
-Then, _in a different session_, create a new app from the archetype:
-
-Set up environment variables:
-
-To test the *simpleapp* archetype:
-
-[source,bash]
-----
-export ISISTMP=/c/tmp    # or as required
-export ISISCPN=simpleapp
-env | grep ISIS | sort
-----
-
-Then recreate:
-
-[source,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
-----
-
-Build the newly generated app and test:
-
-[source,bash]
-----
-cd myapp
-mvn clean install
-mvn antrun:run -P self-host    # runs as standalone app using webconsole
-cd webapp
-mvn jetty:run                  # runs as mvn jetty plugin
-----
-
-
-=== Check the archetype source code into git
-
-Back in the _original session_ (at `example/application/simpleapp`), we are ready to check the archetype source code into git:
-
-[source,bash]
-----
-git rm -rf ../../archetype/$ISISCPN
-rm -rf ../../archetype/$ISISCPN
-----
-
-In either case make sure that the `archetype/$ISISCPN` directory was fully removed, otherwise the next command will not copy the regenerated source into the correct location.
-
-Then, copy over the generated source of the archetype:
-
-[source,bash]
-----
-mv target/generated-sources/archetype ../../archetype/$ISISCPN
-git add ../../archetype/$ISISCPN
-----
-
-Next, confirm that the `-SNAPSHOT` version of the archetype is correct:
-
-[source,bash]
-----
-vi ../../archetype/$ISISCPN/pom.xml
-----
-
-If this a new archetype, then add a reference to the archetype to the root `pom.xml`, eg:
-
-[source,xml]
-----
-<modules>
-    ...
-    <module>example/archetype/newapp</module>
-    ...
-</modules>
-----
-
-Finally, commit the changes:
-
-[source,bash]
-----
-git commit -am "ISIS-nnn: updating $ISISCPN archetype"
-----
-
-=== Create the archetype (scripted)
-
-[IMPORTANT]
-====
-Using the script does not generate an app from the archetype to test it works.
-====
-
-Make sure you are in the correct directory and environment variables are correct.
-
-To recreate the *simpleapp* archetype:
-
-[source,bash]
-----
-cd example/application/simpleapp
-
-env | grep ISIS | sort
-----
-
-If the environment variables look wrong, use the commands at the top of this page to setup.
-The script will also double check that all required environment variables are set.
-
-Then, run the script:
-
-[source,bash]
-----
-sh ../../../scripts/recreate-archetype.sh ISIS-nnn
-----
-
-The script automatically commits changes; if you wish use `git log` and
-`git diff` (or a tool such as SourceTree) to review changes made.
-
-=== Releasing the Archetype
-
-{note
-Releasing the archetype is performed from the *example/archetype* directory,
-NOT the _example/application_ directory.
-}
-
-The procedure for releasing the archetype is the same as for any other releasable module.
-
-First, confirm environment variables set correctly:
-
-[source,bash]
-----
-env | grep ISIS | sort
-----
-
-Then switch the correct directory and release:
-
-[source]
-----
-cd ../../../example/archetype/$ISISCPN
-
-rm -rf $ISISTMP/checkout
-
-mvn release:prepare -P apache-release \
-                -DreleaseVersion=$ISISREL \
-                -DdevelopmentVersion=$ISISDEV \
-                -Dtag=$ISISART-$ISISREL
-mvn release:perform -P apache-release \
-                -DworkingDirectory=$ISISTMP/checkout
-----
-
-Next, log onto http://repository.apache.org[repository.apache.org] and close the staging repo.
-
-Then push branch:
-
-[source,bash]
-----
-git push -u origin prepare/$ISISART-$ISISREL
-----
-
-and push tag:
-
-[source]
-----
-git push origin refs/tags/$ISISART-$ISISREL-$ISISRC:refs/tags/$ISISART-$ISISREL-$ISISRC
-git fetch
-----
-
-See the link:release-process.html[release process] for full details.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/release-checklist.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/release-checklist.adoc b/adocs/documentation/src/main/asciidoc/release-checklist.adoc
deleted file mode 100644
index 5747096..0000000
--- a/adocs/documentation/src/main/asciidoc/release-checklist.adoc
+++ /dev/null
@@ -1,87 +0,0 @@
-[[release-checklist]]
-= Release Checklist
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-This page contains a release checklist to support the link:./release-process.html[full release process] and link:./release-process-one-pager.html[one-pager].
-
-
-
-
-.Prepare
-[cols="1,1,1,1,1,1,1,1,1,1", options="header"]
-|===
-
-
-|Artifact
-|Env?
-|Update parent POM ver.
-|Newer plugin versions
-|Newer deps
-|Formatting
-|License headers (RAT)
-|License check
-|Recreate archetype
-|Commit changes
-
-|isis
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|n/a
-|&nbsp;
-
-|simpleapp-archetype
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-
-|===
-
-
-
-.Release
-[cols="1,1,1,1,1,1,1", options="header"]
-|===
-
-|Artifact
-|prepare dryrun
-|prepare
-|confirm
-|perform
-|stage (nexus)
-|git push
-
-|isis
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-
-|simpleapp-archetype
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-|&nbsp;
-
-|===
-

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc b/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc
deleted file mode 100644
index 2e78554..0000000
--- a/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc
+++ /dev/null
@@ -1,240 +0,0 @@
-[[release-process-1-pager]]
-= Release Process (1 pager)
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-See also the link:release-process.html[full release process] and the link:release-checklist.html[release checklist].
-
-
-
-== Switch to correct directory, parameterize the release
-
-[WARNING]
-====
-Make sure you are in the correct directory (eg `core`, or `example/archetype/zzz`)
-====
-
-
-if you are releasing `core`:
-
-[source]
-----
-cd core
-
-export ISISTMP=/c/tmp              # or whatever
-export ISISART=isis
-export ISISDEV=1.9.0-SNAPSHOT
-export ISISREL=1.8.0
-export ISISRC=RC1
-
-export ISISCOR="Y"
-env | grep ISIS | sort
-----
-
-See link:recreating-an-archetype.html[here] for details on recreating and releasing an archetype. 
-
-
-== Get code
-
-Pull down latest, create branch (eg `prepare/isis-1.8.0`):
-
-[source]
-----
-git checkout master
-git pull --ff-only
-git checkout -b $ISISART-$ISISREL
-----
-
-
-== Update parent pom
-
-Check:
-
-* parent is `org.apache:apache` (non-SNAPSHOT version)
-
-
-== Check for SNAPSHOT dependencies
-
-Search for any non-`SNAPSHOT` usages (including tck project, if any):
-
-[source]
-----
-grep SNAPSHOT `/bin/find . -name pom.xml | grep -v target | sort`
-----
-
-or (more thoroughly):
-
-[source]
-----
-vi `/bin/find . -name pom.xml | grep -v target | sort`
-----
-
-== Sanity check
-
-[WARNING]
-====
-Make sure you are in the correct directory (eg `core`, or `example/archetype/zzz`)
-====
-
-
-Clean all local mvn artifacts and rebuild with `-o` flag:
-
-[source]
-----
-cd core
-
-rm -rf ~/.m2/repository/org/apache/isis
-mvn clean install -o
-----
-
-== Check versions
-
-[TIP]
-====
-Actually, you may want to defer this and do after cutting the release (ie beginning of a new dev cycle)
-====
-
-=== Update plugin versions
-
-
-[source]
-----
-mvn versions:display-plugin-updates > /tmp/foo
-grep "\->" /tmp/foo | /bin/sort -u
-----
-
-=== Newer dependencies:
-
-[source]
-----
-mvn versions:display-dependency-updates > /tmp/foo
-grep "\->" /tmp/foo | /bin/sort -u
-----
-
-== Update license information
-
-=== Missing license headers in files:
-
-[source]
-----
-mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o
-for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done
-----
-
-=== Missing/spurious `supplemental-models.xml`
-
-[source]
-----
-mvn license:download-licenses
-if [ "$ISISCOR" == "Y" ]; then
-    groovy ../scripts/checkmissinglicenses.groovy
-else
-    groovy ../../../scripts/checkmissinglicenses.groovy
-fi
-----
-
-== Commit changes
-
-Commit any changes from the preceding steps:
-
-[source]
-----
-git commit -am "ISIS-nnnn: updates to pom.xml etc for release"
-----
-
-== Release
-
-[WARNING]
-====
-Make sure you are in the correct directory (eg `core`, or `example/archetype/zzz`)
-====
-
-=== Prepare:
-
-
-first the dry run:
-
-[source]
-----
-mvn release:prepare -P apache-release \
-                    -DdryRun=true \
-                    -DreleaseVersion=$ISISREL \
-                    -DdevelopmentVersion=$ISISDEV \
-                    -Dtag=$ISISART-$ISISREL-$ISISRC
-----
-
-then "for real": 
-
-[source]
-----
-mvn release:prepare -P apache-release -DskipTests=true -Dresume=false \
-                    -DreleaseVersion=$ISISREL \
-                    -DdevelopmentVersion=$ISISDEV \
-                    -Dtag=$ISISART-$ISISREL-$ISISRC
-----
-
-=== Confirm:
-
-[source]
-----
-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
-----
-
-=== Perform:
-
-[source]
-----
-mvn release:perform -P apache-release \
-    -DworkingDirectory=$ISISTMP/$ISISART-$ISISREL/checkout
-----
-
-[NOTE]
-====
-The `workingDirectory` property is to avoid 260 char path issue if building on Windows.
-====
-
-
-== Nexus staging
-
-Log onto http://repository.apache.org[repository.apache.org] and close the staging repo.
-
-== Git branches/tags
-
-Push branch:
-
-[source]
-----
-git push -u origin $ISISART-$ISISREL
-----
-
-Then push tag:
-
-[source]
-----
-git push origin refs/tags/$ISISART-$ISISREL-$ISISRC:refs/tags/$ISISART-$ISISREL-$ISISRC
-git fetch
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/release-process.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/release-process.adoc b/adocs/documentation/src/main/asciidoc/release-process.adoc
deleted file mode 100644
index 72d19a6..0000000
--- a/adocs/documentation/src/main/asciidoc/release-process.adoc
+++ /dev/null
@@ -1,1046 +0,0 @@
-[[formal-release-process]]
-= Formal Release Process
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-pass:[<br/><br/>]
-
-This page details the process for formally releasing Isis modules.
-
-If you've done this before and just want the bare essentials, see this link:release-process-one-pager.html[one-pager]
-(that also parameterizes some of the steps listed here 'long-hand'. There is also an experimental
-link:resources/release.sh[script] for automating the latter part of the process.
-
-See also the link:release-checklist.html[release checklist] for keeping track of where you are while releasing (possibly multiple) components.
-
-
-
-== Intro
-
-Apache Isis consists of two separately releasable modules. Relative to the root of the
-https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=tree[source code repo], these are:
-
-* `core`
-* `component/example/archetypes/simpleapp`
-
-Previously there were many other components, but these have either been mothballed or moved into core. The only
-remaining component that is not in core (though has not yet been released) is `component/viewer/scimpi`. There is
-currently no plan to release this component.
-
-
-
-== Process Prerequisites
-
-Before releasing `core`, ensure there is consensus on the link:../support.html[dev mailing list] that this is the right
-time for a release. The discussion should include confirming the version number to be used, and to confirm content.
-
-Once agreed, the formal release can begin. The steps are:
-
-* create a branch locally in which to prepare the release
-* use `mvn release:prepare` to generate the signed artifacts and create a tag in the source code control system
-* use `mvn release:perform` to upload the signed artifacts to the Apache staging repository
-* vote on the staged artifacts (in particular, the signed source release ZIP from which the remaining artifacts are derivable)
-* on a successful vote:
-* promote the staged artifacts
-* distribute the source zip
-* merge in the branch back to into master
-* on a failed vote:
-* drop the staging repository
-* delete the branch and tag
-* fix the problems and go round round the loop again.
-
-Before any of this can happen, there are a number of prerequisites, in terms of (a) the codebase itself,
-(b) the community process, and (c) the committer acting as release manager and performing the release.
-
-
-
-
-=== Set up local environment
-
-==== Public/private key
-
-The most important configuration you require is to set up public/private key pair. This is used by the `maven-release-plugin` to sign the code artifacts. See the page on link:key-generation.html[key generation] for more details.
-
-In order to prepare the release, you'll (need to) have a `~/.gnupg` directory with the relevant files (`gpg.conf`, `pubring.gpg`, `secring.gpg` etc), and have `gpg` on your operating system PATH.
-
-
-[NOTE]
-====
-If on Windows, the equivalent directory is `c:\users\xxx\appdata\roaming\gnupg`. For `gpg`, use either http://cygwin.com[cygwin.com] or http://www.gpg4win.org[gpg4win.org]. Note also that the mSysGit version of `gpg` (as provided by GitHub's bash client) is not compatible with that provided by cygwin; move it to one side and check that `gpg.exe` being used is that from gpg4win.
-
-====
-
-
-
-==== Maven `settings.xml`
-
-During the release process the `maven-deploy-plugin` uploads the generated artifacts to a staging repo on the http://repository.apache.org[Apache repository manager]. This requires your Apache LDAP credentials to be specified in your `~/.m2/settings.xml` file:
-
-[source,xml]
-----
-<settings>
-  <servers>
-    <server>
-      <id>apache.releases.https</id>
-      <username>xxxxxxx</username>
-      <password>yyyyyyy</password>
-    </server>
-    ...
-  </servers>
-  ...
-</settings>
-----
-
-where `xxxxxxx` and `yyyyyyy` are your Apache LDAP username and password. For more information, see these http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env[ASF docs].
-
-
-[NOTE]
-====
-It is also possible to configure to use `.ssh` secure keys, and thereby avoid hardcoding your Apache LDAP password into your `.m2/settings.xml` file. A description of how to do this can be found, for example, http://bval.apache.org/release-setup.html[here].
-====
-
-
-Also, set up keyphrase for `gpg`; this avoids being prompted during release:
-
-[source,xml]
-----
-<profiles>
-  <profile>
-    <id>gpg</id>
-    <properties>
-      <gpg.executable>gpg2</gpg.executable>
-      <gpg.passphrase>this is not really my passphrase</gpg.passphrase>
-    </properties>
-  </profile>
-  ...
-</profiles>
-
-<activeProfiles>
-  <activeProfile>gpg</activeProfile>
-  ...
-</activeProfiles>
-----
-
-
-==== Pull down code to release
-
-Set the HEAD of your local git repo to the commit to be released. In many cases this will be the tip of the origin's `master` branch:
-
-[source,bash]
-----
-git checkout master
-git pull --ff-only
-----
-
-Then, determine/confirm the version number of the module being released. This should be in line with our link:versioning-policy.html[semantic versioning policy].
-
-Next, create a release branch in your local Git repo, using the version number determined and as per link:release-branch-and-tag-names.html[these standards]. For example, to prepare release candidate #1 for a release 1.9.0 of `core`, use:
-
-[source,bash]
-----
-git checkout -b isis-1.9.0
-----
-
-All release preparation is done locally; if we are successful, this branch will be pushed back to master.
-
-Finally, make sure you have a JIRA ticket open against which to perform all commits.
-
-
-
-
-== Set Environment Variables
-
-If you are releasing `core`:
-
-[source,bash]
-----
-cd core
-
-export ISISTMP=/c/tmp              # or whatever
-export ISISART=isis
-export ISISDEV=1.10.0-SNAPSHOT
-export ISISREL=1.9.0
-export ISISRC=RC1
-
-export ISISCOR="Y"
-env | grep ISIS | sort
-----
-
-== Code Prerequisites
-
-{note
-Unless otherwise stated, you should assume that all remaining steps should be performed in the base directory of the module being released.
-}
-
-Before making any formal release, there are a number of prerequisites that should always be checked.
-
-=== Update the version number
-
-The version number of the parent pom should reflect the branch name that you are now on (with a `-SNAPSHOT` suffix). In many cases this will have been done already during earlier development; but confirm that it has been updated. If it has not, make the change.
-
-For example, if releasing `core` version `1.9.0`, the POM should read:
-
-[source,xml]
-----
-<groupId>org.apache.isis.core</groupId>
-<artifactId>isis</artifactId>
-<version>1.9.0</version>
-----
-
-=== Update parent (Apache Isis Core)
-
-If releasing Apache Isis Core, check (via link:http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache%22%20a%3A%22apache%22[search.maven.org]) whether there is a newer version of the Apache parent `org.apache:apache`.
-
-
-If there is, update the `&lt;version&gt;` in the `&lt;parent&gt;` element in the parent POM to match the newer version:
-
-[source,xml]
-----
-<parent>
-    <groupId>org.apache</groupId>
-    <artifactId>apache</artifactId>
-    <version>NN</version>
-    <relativePath />
-</parent>
-----
-
-where `NN` is the updated version number.
-
-=== Check no SNAPSHOT dependencies
-
-There should be no snapshot dependencies; the only mention of `SNAPSHOT` should be for the Isis modules about to be released. 
-
-As a quick check, do a grep for `SNAPSHOT`:
-
-[source,bash]
-----
-grep SNAPSHOT `/bin/find . -name pom.xml | grep -v target | sort`
-----
-
-Or, for a more thorough check, load up each `pom.xml` and inspect manually:
-
-[source,bash]
-----
-vi `/bin/find . -name pom.xml | grep -v target | sort`
-----
-
-... and search for `SNAPSHOT`.
-
-
-[TIP]
-====
-Obviously, don't update Apache Isis' `SNAPSHOT` references; these get updated by the `mvn release:prepare` command we run later.
-====
-
-
-
-=== Update plugin versions
-
-The `maven-versions-plugin` should be used to determine if there are newer versions of any of the plugins used to build Apache Isis. Since this goes off to the internet, it may take a minute or two to run:
-
-[source,bash]
-----
-mvn versions:display-plugin-updates > /tmp/foo
-grep "\->" /tmp/foo | /bin/sort -u
-----
-
-Review the generated output and make updates as you see fit. (However, if updating, please check by searching for known issues with newer versions).
-
-
-
-=== Update dependency versions
-
-The `maven-versions-plugin` should be used to determine if there are newer versions of any of Isis' dependencies. Since this goes off to the internet, it may take a minute or two to run:
-
-[source,bash]
-----
-mvn versions:display-dependency-updates > /tmp/foo
-grep "\->" /tmp/foo | /bin/sort -u
-----
-
-Update any of the dependencies that are out-of-date. That said, do note that some dependencies may show up with a new dependency, when in fact the dependency is for an old, badly named version. Also, there may be new dependencies that you do not wish to move to, eg release candidates or milestones.
-
-For example, here is a report showing both of these cases:
-
-[source,bash]
-----
-[INFO]   asm:asm ..................................... 3.3.1 -> 20041228.180559
-[INFO]   commons-httpclient:commons-httpclient .......... 3.1 -> 3.1-jbossorg-1
-[INFO]   commons-logging:commons-logging ......... 1.1.1 -> 99.0-does-not-exist
-[INFO]   dom4j:dom4j ................................. 1.6.1 -> 20040902.021138
-[INFO]   org.datanucleus:datanucleus-api-jdo ................ 3.1.2 -> 3.2.0-m1
-[INFO]   org.datanucleus:datanucleus-core ................... 3.1.2 -> 3.2.0-m1
-[INFO]   org.datanucleus:datanucleus-jodatime ............... 3.1.1 -> 3.2.0-m1
-[INFO]   org.datanucleus:datanucleus-rdbms .................. 3.1.2 -> 3.2.0-m1
-[INFO]   org.easymock:easymock ................................... 2.5.2 -> 3.1
-[INFO]   org.jboss.resteasy:resteasy-jaxrs ............. 2.3.1.GA -> 3.0-beta-1
-----
-
-For these artifacts you will need to search http://search.maven.org[Maven central repo] directly yourself to confirm there are no newer dependencies not shown in this list.
-
-=== Code cleanup / formatting
-
-Make sure that all source code has been cleaned up and formatted according to the Apache Isis and ASF conventions. Use link:resources/Apache-code-style-formatting.xml[this] Eclipse template and link:resources/isis.importorder[this] import order.
-
-=== License header notices (RAT tool)
-
-The Apache Release Audit Tool `RAT` (from the http://creadur.apache.org[Apache Creadur] project) checks for missing license header files. The parent `pom.xml` of each releasable module specifies the RAT Maven plugin, with a number of custom exclusions.
-
-To run the RAT tool, use:
-
-[source,bash]
-----
-mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o
-----
-
-where `rat.numUnapprovedLicenses` 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. 
-
-
-[WARNING]
-====
-Do _not_ use `mvn rat:check`; depending on your local Maven configuratoin this may bring down the obsolete `mvn-rat-plugin` from the Codehaus repo.
-====
-
-
-All being well the command should complete. For each failing submodule, it will have written out a `target\rat.txt`; missing license notes are indicated using the key `!???`. You can collate these together using something like:
-
-[source,bash]
-----
-for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done
-----
-
-Investigate and fix any reported violations, typically by either:
-
-* adding genuinely missing license headers from Java (or other) source files, or
-* updating the `&lt;excludes&gt;` element for the `apache-rat-plugin` plugin to ignore test files, log files and any other non-source code files
-* also look to remove any stale `&lt;exclude&gt;` entries
-
-To add missing headers, you can if you wish use the groovy script `addmissinglicenses.groovy` (in the `scripts` directory) to automatically insert missing headers for certain file types. The actual files checked are those with extensions specified in the line `def fileEndings = [&quot;.java&quot;, &quot;.htm&quot;]`:
-
-Run this in dry run mode first (shown here relative to the `core` module):
-
-[source,bash]
-----
-groovy ../scripts/addmissinglicenses.groovy
-----
-
-When happy, perform the updates by specifying the `-x` (execute) flag:
-
-[source,bash]
-----
-groovy addmissinglicenses.groovy -x
-----
-
-Once you've fixed all issues, confirm once more that `apache-rat-plugin` no longer reports any license violations, this time leaving the `rat.numUnapprovedLicenses` property to its default, 0:
-
-[source,bash]
-----
-mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=0 -o
-for a in `find . -name rat.txt -print`; do grep '!???' $a; done
-----
-
-=== Missing License Check
-
-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 `DEPENDENCIES` file and generated Maven site indicating dependencies as having "unknown" licenses.
-
-Fortunately, Maven allows the missing information to be provided by configuring the `maven-remote-resources-plugin`. This is stored in the `src/main/appended-resources/supplemental-models.xml` file, relative to the root of each releasable module.
-
-To capture the missing license information, use:
-
-[source,bash]
-----
-mvn license:download-licenses
-----
-
-This Maven plugin creates a `license.xml` file in the `target/generated-resources` directory of each module.
-
-Then, run the following script (shown here relative to the `core` module).
-
-[source,bash]
-----
-groovy ../scripts/checkmissinglicenses.groovy
-----
-
-This searches for all `licenses.xml` files, and compares them against the contents of the `supplemental-models.xml` file. For example, the output could be something like:
-
-[source,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]
-----
-
-If any missing entries are listed or are spurious, then update `supplemental-models.xml` and try again.
-
-
-[NOTE]
-====
-Ignore any missing license warnings for the TCK modules; this is a result of the TCK modules for the viewers (eg `isis-viewer-bdd-concordion-tck`) depending on the TCK dom, fixtures etc.
-====
-
-
-
-== Sanity check
-
-Before you cut the release, perform one last sanity check on the codebase.
-
-=== Sanity check for `core`
-
-First, check that there are _NO SNAPSHOT_ dependencies in any of the `pom.xml` of the modules of the core.
-
-Next, delete all Isis artifacts from your local Maven repo:
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-----
-
-Next, check that `core` builds independently, using the `-o` offline flag:
-
-[source,bash]
-----
-mvn clean install -o
-----
-
-Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
-
-=== Sanity check for non-`core` components
-
-You should already have changed the parent POM of the releasable module to reference a released version of `org.apache.isis.core:isis`. Now, also check that there are remaining _NO SNAPSHOT_ dependencies in any of the `pom.xml` of the modules of the component.
-
-Next, delete all Isis artifacts from your local Maven repo:
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-----
-
-Next, build the component, though without the offline flag. Maven should pull down the component's dependencies from the Maven central repo, including the non-spshot of Apache Isis core:
-
-[source,bash]
-----
-mvn clean install
-----
-
-Confirm that the versions of the Isis artifacts now cached in your local repository are correct (both those pulled down from Maven central repo, as well as those of the component built locally). The versions of `core` should not be a SNAPSHOT.
-
-
-
-== Commit changes
-
-Before going any further, remember to commit any changes from the preceding steps:
-
-[source,bash]
-----
-git commit -am "ISIS-nnn: updates to pom.xml etc for release"
-----
-
-== Preparing a Release (`mvn release:prepare`)
-
-Most of the work is done using the `mvn release:prepare` 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.
-
-=== Dry-run
-
-Run the dry-run as follows:
-
-[source,bash]
-----
-mvn release:prepare -P apache-release -D dryRun=true \
-    -DreleaseVersion=$ISISREL \
-    -Dtag=$ISISART-$ISISREL \
-    -DdevelopmentVersion=$ISISDEV
-----
-
-where:
-
-* `releaseVersion` just strip off the `-SNAPSHOT` suffix:
-* `tag` should follow our link:release-branch-and-tag-names.html[standard] (concatenation of the `artifactId` and the version entered above _without a `-RCn` suffix_)
-* `developmentVersion` should increment as required, and have `-SNAPSHOT` appended.
-
-This is not quite fully automated; you may be prompted for the gpg passphrase. (Experiments in using `--batch-mode -Dgpg.passphrase=&quot;...&quot;` to fully automate this didn't work; for more info, see http://maven.apache.org/plugins/maven-gpg-plugin/sign-mojo.html[here] (maven release plugin docs) and http://maven.apache.org/maven-release/maven-release-plugin/examples/non-interactive-release.html[here] (maven gpg plugin docs).
-
-Or, if you want to be prompted for the versions, you can omit the properties, eg:
-
-[source,bash]
-----
-mvn release:prepare -P apache-release -D dryRun=true
-----
-
-Some modules might have additional profiles to be activated. For example, the (now mothballed) SQL ObjectStore required `-P apache-release,integration-tests` so that its integration tests are also run.
-
-This should generate something like:
-
-[source,bash]
-----
-$ mvn release:prepare -P apache-release -D dryRun=true
-[INFO] Scanning for projects...
-[INFO] ------------------------------------------------------------------------
-[INFO] Reactor Build Order:
-[INFO]
-[INFO] Apache Isis Core
-[INFO] Apache Isis Core AppLib
-[INFO] Apache Isis Core Unit Test Support
-[INFO] Apache Isis Core MetaModel
-[INFO] Apache Isis Core Runtime
-[INFO] Apache Isis Core WebServer
-       ...
-[INFO] Apache Isis Core Integration Testing Support
-[INFO]
-[INFO] ------------------------------------------------------------------------
-[INFO] Building Apache Isis Core 1.9.0
-[INFO] ------------------------------------------------------------------------
-[INFO]
-[INFO] --- maven-release-plugin:2.3.2:prepare (default-cli) @ isis ---
-[INFO] Resuming release from phase 'map-release-versions'
-What is the release version for "Apache Isis Core"? (org.apache.isis.core:isis)
-1.9.0: :
-----
-
-If you didn't provide the `releaseVersion`, `tag` and `developmentVersion` tags, then you'll be prompted for them. You can generally accept the defaults that Maven offers.
-
-Assuming this completes successfully, re-run the command, but without the `dryRun` flag and specifying `resume=false` (to ignore the generated `release.properties` file that gets generated as a side-effect of using `git`). You can also set the `skipTests` flag since they would have been run during the previous dry run:
-
-[source,bash]
-----
-mvn release:prepare -P apache-release -D resume=false -DskipTests=true
-        -DreleaseVersion=$ISISREL \
-        -Dtag=$ISISART-$ISISREL \
-        -DdevelopmentVersion=$ISISDEV
-----
-
-
-[TIP]
-====
-If any issues here, then explicitly delete the generated `release.properties` file first.
-====
-
-
-
-=== Post-prepare sanity check
-
-You should end up with artifacts in your local repo with the new version `1.9.0`. There are then a couple of sanity checks that you can perform:
-
-* unzip the source-release ZIP and check it builds. +
-+
-For example, if building core, then the ZIP file will be called `isis-1.9.0-source-release.zip` and should reside in `~/.m2/repository/org/apache/isis/core/isis/1.9.0` directory. +
-+
-Unzip in a new directory, and build.
-
-* Inspect the `DEPENDENCIES` file. +
-+
-This file should be in the root of the extracted ZIP. In particular, check that there are no category-x dependencies.
-
-If you find problems and the release was performed on a branch, then just delete the branch and start over.
-
-
-
-
-== Upload Release for Voting
-
-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).
-
-The Apache staging repository runs on Nexus server, hosted at https://repository.apache.org[repository.apache.org]. 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.
-
-Before you start, make sure you've defined the staging repo in your local `~/.m2/settings.xml` file (see earlier on this page).
-
-
-=== Perform the Release
-
-If running on *nix, then the command to stage the release is:
-
-[source,bash]
-----
-mvn release:perform -P apache-release
-----
-
-but if using mSysGit on windows, specify a different working directory:
-
-[source,bash]
-----
-mvn release:perform -P apache-release \
-    -DworkingDirectory=$ISISTMP/$ISISART-$ISISREL/checkout
-----
-
-You may (again) be prompted for gpg passphrase.
-
-The command starts off by checking out the codebase from the tag (hence different working directory under Windows to avoid 260 char path limit). It then builds the artifacts, then uploads them to the Apache staging repository:
-
-[source,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 isis-1.9.0 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 isis-1.9.0 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 isis-1.9.0"
-[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'...
-...
-----
-
-All being well this command will complete successfully. Given that it is uploading code artifacts, it could take a while to complete. 
-
-=== Check the Repository
-
-If the `mvn release:perform` has worked then it will have put release artifacts into a newly created staging repository .
-
-Log onto http://repository.apache.org[repository.apache.org] (using your ASF LDAP account):
-
-image::{_imagesdir}release-process/nexus-staging-0.png[width="600px",link="{_imagesdir}release-process/nexus-staging-0.png"]
-
-And then check that the release has been staged (select `staging repositories` from left-hand side):
-
-image::{_imagesdir}release-process/nexus-staging-1.png[width="600px",link="{_imagesdir}release-process/nexus-staging-1.png"]
-
-If nothing appears in a staging repo you should stop here and work out why.
-
-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 `org.apache.isis-008`.
-
-=== Close the Repository
-
-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.
-
-Press the Close button and complete the dialog:
-
-image::{_imagesdir}release-process/nexus-staging-2.png[width="600px",link="{_imagesdir}release-process/nexus-staging-2.png"]
-
-Nexus should start the process of closing the repository.
-
-image::{_imagesdir}release-process/nexus-staging-2a.png[width="600px",link="{_imagesdir}release-process/nexus-staging-2a.png"]
-
-All being well, the close should (eventually) complete successfully (keep hitting refresh):
-
-image::{_imagesdir}release-process/nexus-staging-3.png[width="600px",link="{_imagesdir}release-process/nexus-staging-3.png"]
-
-The Nexus repository manager will also email you with confirmation of a successful close.
-
-If Nexus has problems with the key signature, however, then the close will be aborted:
-
-image::{_imagesdir}release-process/nexus-staging-4.png[width="600px",link="{_imagesdir}release-process/nexus-staging-4.png"]
-
-Use `gpg --keyserver hkp://pgp.mit.edu --recv-keys nnnnnnnn` to confirm that the key is available.
-
-
-[NOTE]
-====
-Unfortunately, Nexus does not seem to allow subkeys to be used for signing. See link:key-generation.html[Key Generation] for more details.
-====
-
-
-=== Push changes
-
-Finally, push both the branch and the tag created locally to the central origin server. For the tag, we append an `-RCn` suffix until the vote succeeds. 
-
-To push the branch, for example:
-
-[source,bash]
-----
-git checkout prepare/$ISISART-$ISISREL
-git push -u origin prepare/$ISISART-$ISISREL
-----
-
-To push the tag, with the `-RCn` suffix, for example:
-
-[source,bash]
-----
-git push origin refs/tags/$ISISART-$ISISREL:refs/tags/$ISISART-$ISISREL-$ISISRC
-git fetch
-----
-
-The remote tag isn't visible locally (eg via `gitk --all`), but can be seen https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=summary[online].
-
-
-
-== Voting
-
-Once the artifacts have been uploaded, you can call a vote.
-
-In all cases, votes last for 72 hours and require a +3 (binding) vote from members.
-
-=== Start voting thread on link:mailto:&#100;e&#118;&#x40;&#x69;&#x73;&#x69;&#115;&#x2e;&#x61;p&#97;&#x63;&#104;e&#46;&#111;&#114;g[&#100;e&#118;&#x40;&#x69;&#x73;&#x69;&#115;&#x2e;&#x61;p&#97;&#x63;&#104;e&#46;&#111;&#114;g]
-
-The following boilerplate is for a release of the Apache Isis Core. Adapt as required:
-
-Use the following subject:
-
-[source,bash]
-----
-[VOTE] Apache Isis Core release 1.8.0 RC1
-----
-
-And use the following body:
-
-[source,bash]
-----
-I've cut a release for Apache Isis Core and the simpleapp archetype:
-* Core 1.8.0
-* SimpleApp Archetype 1.8.0
-
-The source code artifacts have been uploaded to staging repositories on repository.apache.org:
-
-* http://repository.apache.org/content/repositories/orgapacheisis-10xx/org/apache/isis/core/isis/1.9.0/isis-1.9.0-source-release.zip
-* http://repository.apache.org/content/repositories/orgapacheisis-10xx/org/apache/isis/archetype/simpleapp-archetype/1.9.0/simpleapp-archetype-1.9.0-source-release.zip
-
-For each zip there is a corresponding signature file (append .asc to the zip's url).
-
-In the source code repo the code has been tagged as isis-1.8.0-RC1 and simpleapp-archetype-1.8.0-RC1.
-
-For instructions on how to verify the release (build from binaries and/or use in Maven directly), see http://isis.apache.org/contributors/verifying-releases.html
-
-Please verify the release and cast your vote.  The vote will be open for a minimum of 72 hours.
-
-[ ] +1
-[ ]  0
-[ ] -1
-----
-
-Remember to update:
-
-* the version number (1.9.0 or whatever)
-* the release candidate number (`RC1` or whatever)
-* the repository id, as provided by Nexus earlier (`orgapacheisis-10xx` or whatever)
-
-Note that the email also references the procedure for other committers to link:verifying-releases.html[verify the release].
-
-== After the vote
-
-Once the vote has completed, post the results to the isis-dev mailing list.
-
-For example, use the following subject for a vote on Apache Isis Core:
-
-[source,bash]
-----
-[RESULT] [VOTE] Apache Isis Core release 1.9.0
-----
-
-using the body (alter last line as appropriate):
-
-[source,bash]
-----
-The vote has completed with the following result :
-
-  +1 (binding): <i>list of names</i>
-  +1 (non binding): <i>list of names</i>
-
-  -1 (binding): <i>list of names</i>
-  -1 (non binding): <i>list of names</i>
-
-The vote is (UN)SUCCESSFUL.
-----
-
-=== For a successful vote
-
-If the vote has been successful, then replace the `-RCn` tag with another without the qualifier.
-
-You can do this using the `scripts/promoterctag.sh` script; for example:
-
-[source,bash]
-----
-sh scripts/promoterctag isis-1.9.0 RC1    # $ISISART-$SISREL $ISISRC
-----
-
-Or, if you like to execute the steps in that script by hand:
-
-* add the new remote tag, for example: +
-+
-[source,bash]
-----
-git push origin refs/tags/isis-1.9.0:refs/tags/isis-1.9.0
-git fetch
-----
-
-* delete the `-RCn` remote tag, for example: +
-+
-[source,bash]
-----
-git push origin –delete refs/tags/isis-1.9.0-RC1 # $ISISART-$SISREL-$ISISRC
-git fetch
-----
-
-
-* delete the `-RCn` local tag, for example: +
-+
-[source,bash]
-----
-git tag -d isis-1.9.0-RC1 # $ISISART-$SISREL-$ISISRC
-git fetch
-----
-
-
-
-Then, continue onto the next section for the steps to promote and announce the release.
-
-=== For an unsuccessful vote
-
-If the vote has been unsuccessful, then:
-
-* delete the remote branch, for example: +
-+
-[source,bash]
-----
-git push origin –delete isis-1.9.0 # $ISISART-$SISREL
-----
-
-
-
-* delete your local branch, for example: +
-+
-[source,bash]
-----
-git branch -D isis-1.9.0 # $ISISART-$SISREL
-----
-
-
-* delete the remote origin server's tag, for example: +
-+
-[source,bash]
-----
-git push origin –delete refs/tags/isis-1.9.0-RC1
-----
-
-
-* delete the tag that was created locally, for example: +
-+
-[source,bash]
-----
-git tag -d isis-1.9.0 # $ISISART-$SISREL
-----
-
-
-* drop the staging repository in http://repository.apache.org[Nexus]
-
-Address the problems identified in the vote, and go again.
-
-
-
-
-== Promoting Release to Distribution
-
-=== Release Binaries to Maven Central Repo
-
-From the Nexus pages, select the staging repository and select 'release' from the top menu.
-
-
-image::{_imagesdir}release-process/nexus-release-1.png[width="600px",link="{_imagesdir}release-process/nexus-release-1.png"]
-
-This moves the release artifacts into an Apache releases repository; from there they will be automatically moved to the Maven repository.
-
-=== Release Source Zip
-
-As described in the http://www.apache.org/dev/release-publishing.html#distribution_dist[Apache documentation], each Apache TLP has a `release/TLP-name` directory in the distribution Subversion repository at https://dist.apache.org/repos/dist[https://dist.apache.org/repos/dist]. Once a release vote passes, the release manager should `svn add` the artifacts (plus signature and hash files) into this location. The release is then automatically pushed to http://www.apache.org/dist/[http://www.apache.org/dist/] by `svnpubsub`. Only the most recent release of each supported release line should be contained here, old versions should be deleted.
-
-Each project is responsible for the structure of its directory. The directory structure of Apache Isis reflects the directory structure in our git source code repo:
-
-[source]
-----
-isis/
-  core/
-  component/
-    objectstore/  # empty, JDO now part of core
-    security/     # empty, Shiro now part of core
-    viewer/       # empty, Restful and Wicket viewers now part of core
-  example/
-    archetype/
-      simpleapp/
-  tool/
-    maven-isis-plugin/   # not yet released
-----
-
-If necessary, checkout this directory structure:
-
-[source,bash]
-----
-svn co https://dist.apache.org/repos/dist/release/isis isis-dist
-----
-
-Next, add the new release into the appropriate directory, and delete any previous release. You can use link:upd_sh[the upd.sh script] to help; this downloads the artefacts from the Nexus release repository, adds the artefacts to subsversion and deletes the previous version.
-
-At the end, commit the changes:
-
-[source]
-----
-svn commit -m "publishing isis source releases to dist.apache.org"
-----
-
-== Update JIRA and generate Release notes
-
-=== Close All JIRA tickets for the release
-
-Close all JIRA tickets for the release, or moved to future releases if not yet addressed. Any tickets that were partially implemented should be closed, and new tickets created for the functionality on the ticket not yet implemented.
-
-=== Generate Release Notes in JIRA
-
-Use JIRA to http://confluence.atlassian.com/display/JIRA/Creating+Release+Notes[generate release notes]:
-
-image::{_imagesdir}release-process/jira-create-release-notes.png[width="400px",link="{_imagesdir}release-process/jira-create-release-notes.png"]
-<img src="resources/jira-create-release-notes.png" width="400px"></img>
-
-If any of the tickets closed are tasks/subtasks, then please edit the contents of the file to associate them back together again.
-
-=== Mark the JIRA versions as released
-
-In JIRA, go to the administration section for the Apache Isis project and update the versions as released.
-
-=== Update ISIS website
-
-Update the Apache Isis CMS website:
-
-* Using the JIRA-generated release notes as a guide, update the relevant page of the Apache Isis site. +
-+
-Use this regex to convert links.  From:
-+
-[source,bash]
-----
-<li>\[<a href='(.+)?'>(.+?)<\/a>\].*-[\s]*(.*)$
-----
-+
-to:
-+
-[source,bash]
-----
-* link:$1[$2] - $3
-----
-+
-and use this regex to convert headings.  From:
-+
-[source,bash]
-----
-<h2>\s+(\S+)\n</h2>
-----
-+
-to:
-+
-[source,bash]
-----
-=== $1
-----
-
-
-
-Typically this be will a new page in the core section or for one of the components. Make a note of the URL of this new page (for use in the mailing list announcement).
-
-For example, a new release of Apache Isis Core would require:
-
-* Do a search for `x.y.0-SNAPSHOT` and replace with `x.y.0`
-
-* Update the version number on the link:./index.html[home (index)] pages.
-
-* Update the version number on the link:./simpleapp-archetype.html[simpleapp archetype] pages.
-
-
-In addition:
-
-* Update the link:./download.html[download page] with a link to the source release zip file (under https://dist.apache.org/repos/dist/release/isis[https://dist.apache.org/repos/dist/release/isis])
-
-* The link:./doap_isis.rdf[DOAP RDF] file (which provides a machine-parseable description of the project) should also be updated with details of the new release. Validate using the http://www.w3.org/RDF/Validator/[W3C RDF Validator] service.
-
-For more information on DOAP files, see these http://projects.apache.org/doap.html[Apache policy docs].
-
-* The `STATUS` file (in root of Apache Isis' source) should be updated with details of the new release.
-
-
-
-== Announce the release
-
-Announce the release to link:mailto:users@isis.apache.org[users mailing list].
-
-For example, for a release of Apache Isis Core, use the following subject:
-
-[source,bash]
-----
-[ANN] Apache Isis version 1.9.0 Released
-----
-
-And use the following body (summarizing the main points as required):
-
-[source]
-----
-The Apache Isis team is pleased to announce the release of:
-* Apache Isis Core version 1.9.0
-* SimpleApp Archetype 1.9.0
-
-New features in this release include:
-- ...
-
-Full release notes are available on the Apache Isis website at [1].
-
-Note that:
-* ...
-
-You can access this release directly from the Maven central repo [2],
-or download the release and build it from source [3].
-
-Enjoy!
-
---The Apache Isis team
-
-[1] http://isis.apache.org/core/release-notes/isis-1.9.0.html
-[2] http://search.maven.org
-[3] http://isis.apache.org/download.html
-----
-
-=== Blog post
-
-Finally, https://blogs.apache.org/roller-ui/login.rol[log onto] the http://blogs.apache.org/isis/[Apache blog] and create a new post. Copy-n-paste the above mailing list announcement should suffice.
-
-== Prepare for next iteration
-
-=== Merge changes from branch back into `master` branch
-
-Because we release from a branch, the changes made in the branch (changes to `pom.xml` made by the `maven-release-plugin`, or any manual edits) should be merged back from the release branch back into the `master` branch:
-
-[source,bash]
-----
-git checkout master                   # update master with latest
-git pull
-git merge isis-1.9.0                  # merge branch onto master
-git branch -d isis-1.9.0              # branch no longer needed
-git push origin --delete isis-1.9.0   # remote branch no longer needed
-----
-
-If the core was updated, then you'll most likely need to update other POMs to the new `-SNAPSHOT`.
-
-Next, do a sanity check that everything builds ok:
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-mvn clean install
-----
-
-... and run up an Isis application.
-
-=== Update `STATUS` file
-
-The trunk holds a https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=blob_plain;f=STATUS;hb=HEAD[STATUS] file which is a brief summary of the current status of the project. Update this file with details of the release.
-
-=== Push changes
-
-Finally, push the changes up to origin:
-
-[source,bash]
-----
-git fetch    # check no new commits on origin/master
-git push
-----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/screencasts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/screencasts.adoc b/adocs/documentation/src/main/asciidoc/screencasts.adoc
index df3207d..3714490 100644
--- a/adocs/documentation/src/main/asciidoc/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/screencasts.adoc
@@ -53,7 +53,7 @@ _How to import an Apache Isis maven-based application into Eclipse and configure
 
 NB: when configuring DataNucleus for the *dom* project, make sure you are in the 'Java perspective', not the 'Java EE perspective'). +
 
-Learn more link:./guides/dg.html#_dg_eclipse[here]
+Learn more link:./guides/cg.html#_cg_ide_eclipse[here]
 
 |video::RgcYfjQ8yJA[youtube,width="420px",height="315px"]
 
@@ -63,7 +63,7 @@ Learn more link:./guides/dg.html#_dg_eclipse[here]
 
 _How to import an Apache Isis maven-based application into IntelliJ and run the app._ +
 
-Learn more link:./guides/dg.html#_dg_intellij[here]
+Learn more link:./guides/cg.html#_cg_ide_intellij[here]
 
 |video::lwKsyTbTSnA[youtube,width="420px",height="315px"]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc
deleted file mode 100644
index 2ee008e..0000000
--- a/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc
+++ /dev/null
@@ -1,208 +0,0 @@
-[[simpleapp-archetype]]
-= SimpleApp Archetype
-:notice: 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.
-:_basedir: ./
-:_imagesdir: images/
-:toc: right
-
-
-
-pass:[<br/><br/>]
-
-The quickest way to get started with Apache Isis is to run the simple archetype.  This will generate a very simple one-class domain model, called `SimpleObject`, with a single property `name`.  There is also a corresponding `SimpleObjectRepository` domain service.  From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
-
-
-
-
-
-== Generating the App
-
-Create a new directory, and `cd` into that directory.
-
-Then run the following command:
-
-[source,bash]
-----
-mvn archetype:generate  \
-    -D archetypeGroupId=org.apache.isis.archetype \
-    -D archetypeArtifactId=simpleapp-archetype \
-    -D archetypeVersion=1.8.0 \
-    -D groupId=com.mycompany \
-    -D artifactId=myapp \
-    -D version=1.0-SNAPSHOT \
-    -B
-----
-
-where:
-
-- `groupId` represents your own organization, and
-- `artifactId` is a unique identifier for this app within your organization.
-- `version` is the initial (snapshot) version of your app
-
-The archetype generation process will then run; it only takes a few seconds.
-
-
-
-
-=== Snapshot release
-
-We also maintain the archetype for the most current `-SNAPSHOT`; an app generated with this archetype will contain the latest features of Apache Isis, but the usual caveats apply: some features still in development may be unstable.
-
-The process is almost identical to that for stable releases, however the `archetype:generate` goal is called with slightly different arguments:
-
-[source,bash]
-----
-mvn archetype:generate  \
-    -D archetypeGroupId=org.apache.isis.archetype \
-    -D archetypeArtifactId=simpleapp-archetype \
-    -D archetypeVersion=1.9.0-SNAPSHOT \
-    -D groupId=com.mycompany \
-    -D artifactId=myapp \
-    -D version=1.0-SNAPSHOT \
-    -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
-    -B
-----
-
-where as before:
-
-- `groupId` represents your own organization, and
-- `artifactId` is a unique identifier for this app within your organization.
-- `version` is the initial (snapshot) version of your app
-
-but also:
-
-- `archetypeVersion` is the SNAPSHOT version of Apache Isis.
-- `archetypeRepository` specifies the location of our snapshot repo (hosted on [CloudBees](http://www.cloudbees.com)), and
-
-The archetype generation process will then run; it only takes a few seconds.
-
-
-
-
-== Building the App
-
-Switch into the root directory of your newly generated app, and build your app:
-
-[source,bash]
-----
-cd myapp
-mvn clean install
-----
-
-where `myapp` is the `artifactId` entered above.
-
-
-
-
-== Running the App
-
-The `simpleapp` archetype generates a single WAR file, configured to run both the link:./guides/ug.html#_ug_wicket-viewer[Wicket viewer] and the link:./guides/ug.html#_ug_restfulobjects-viewer[Restful Objects viewer].   The archetype also configures the JDO/DataNucleus objectstore to use an in-memory HSQLDB connection.  
-
-Once you've built the app, you can run the WAR in a variety of ways. 
-
-The recommended approach when getting started is to run the self-hosting version of the WAR, allowing Apache Isis to run as a standalone app; for example:
-
-[source,bash]
-----
-java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar
-----
-
-
-
-This can also be accomplished using an embedded Ant target provided in the build script:
-
-
-[source,bash]
-----
-mvn -P self-host antrun:run
-----
-
-
-    
-The first is to simply deploying the generated WAR (`webapp/target/myapp-webapp-1.0-SNAPSHOT.war`) to a servlet container.
-
-
-Alternatively, you could run the WAR in a Maven-hosted Jetty instance, though you need to `cd` into the `webapp` module:
-
-[source,bash]
-----
-cd webapp
-mvn jetty:run -D jetty.port=9090
-----
-
-
-In the above, we've passed in a property to indicate a different port from the default port (8080).
-
-Note that if you use `mvn jetty:run`, then the context path changes; check the console output (eg [http://localhost:9090/myapp-webapp](http://localhost:9090/myapp-webapp)).
-
-Finally, you can also run the app by deploying to a standalone servlet container such as [Tomcat](http://tomcat.apache.org).
-
-
-
-
-=== With Fixtures
-
-It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory
-testing.  This is done by specifying a _fixture script_ on the command line:
-
-
-[source,bash]
-----
-java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar \
-     --initParam isis.persistor.datanucleus.install-fixtures=true  \
-     --initParam isis.fixtures=fixture.simple.SimpleObjectsFixture
-----
-
-    
-where (in the above example) `fixture.simple.SimpleObjectsFixture` is the fully qualified class name of the fixture 
-script to be run.
-
-
-
-
-== Using the App
-
-The archetype provides a welcome page that explains the classes and files generated, and provides detailed guidance and what to do next.
-
-The app itself is configured to run using shiro security, as configured in the `WEB-INF/shiro.ini` config file.  To log in, use `sven/pass`.
-
-
-
-== Modifying the App
-
-Once you are familiar with the generated app, you'll want to start modifying it.  Check out our the link:.guides/ug.html[User Guide], which has how-tos and a complete reference guide (as well as some background concepts and discussion of more advanced techniques).   
-
-If you use IntelliJ or Eclipse, you'll also want to set up your IDE; this is also described in the link:dg.adoc[Developers' Guide].
-
-
-== App Structure
-
-As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
-
-
-.Table caption
-[cols="1,1a", options="header"]
-|===
-| Module 
-| Description
-
-
-|myapp
-|The parent (aggregator) module
-
-|myapp-dom
-|The domain object model, consisting of <tt>SimpleObject</tt> and <tt>SimpleObjects</tt> (repository) domain service.
-
-|myapp-fixture
-|Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
-
-|myapp-integtests
-|End-to-end integration tests, that exercise from the UI through to the database
-
-|myapp-webapp
-|Run as a webapp (from `web.xml`) using either the Wicket viewer or the RestfulObjects viewer
-
-|===
-
-
-If you run into issues, please don't hesitate to ask for help on the link:../../support.html[users mailing list].