You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2016/01/04 16:23:00 UTC
[5/9] isis git commit: ISIS-1287: splitting out contributors vs
committers guides
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcom_verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcom_verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcom_verifying-releases.adoc
new file mode 100644
index 0000000..efd8054
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcom_verifying-releases.adoc
@@ -0,0 +1,304 @@
+[[_cgcom_verifying-releases]]
+= Verifying 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
+
+
+The release process consists of:
+
+* the release manager xref:cgcom.adoc#_cgcom_cutting-a-release[cutting the release]
+* members of the Apache Isis PMC verifying and voting on the release (documented below)
+* the release manager performing post-release tasks, for either a xref:cgcom.adoc#_cgcom_post-release-successful[successful] or an xref:cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote.
+
+This section describes some guidance on what a voter (members of the Apache Isis PMC and anyone else who wishes) is expected to do before casting their vote in order to verify a release.
+
+
+
+== Background
+
+Whenever a release manager announces a vote on a release (as per the xref:cgcom.adoc#_cgcom_release-process[release process]) 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.
+
+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
+----
+
+
+Also, we will be rebuilding Isis from source. Therefore delete all Isis artifacts from your local Maven repo:
+
+[source,bash]
+----
+rm -rf ~/.m2/repository/org/apache/isis
+----
+
+
+== Verifying source artifacts
+
+You can either verify the source artifacts xref:cgcom.adoc#_cgcom_verifying-releases_manual-procedure[manuall], or use a script that xref:cgcom.adoc#_cgcom_verifying-releases_automated-procedure[automates] the steps.
+
+
+[[_cgcom_verifying-releases_manual-procedure]]
+=== Manual procedure
+
+The following section describes the steps to perform to manually verify a release.
+
+==== Download the artifacts
+
+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 source artifacts
+
+Assuming the ZIP file verifies, it should be unpacked, and then the artifact built from source.
+
+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
+
+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 binary artifacts
+
+You can verify the binary releases by configuring your local Maven install to point to the 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 `<activeProfile>` 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.
+
+
+
+
+[[_cgcom_verifying-releases_automated-procedure]]
+=== Automated procedure
+
+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 script to local machine
+
+Copy the following script, save to `verify-isis-release.sh`:
+
+
+[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
+----
+
+[NOTE]
+====
+The script could be enhanced in many ways, feel free to contribute improvements!
+====
+
+
+==== 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.
+
+
+
+==== Execute the script
+
+Execute...
+
+[source,bash]
+----
+./verify-isis-release.sh
+----
+
+\... and get yourself a cup of coffee.
+
+
+
+
+[[_cgcom_verifying-releases_creadur]]
+== (Optional) 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 xref:cgcom.adoc#_cgcom_cutting-a-release[release process].
+
+Creadur's remaining tools - link:http://creadur.apache.org/tentacles/[Tentacles] and link:http://creadur.apache.org/whisker/[Whisker] - are to support the verification process.
+
+For example, Tentacles generates a report called `archives.html`. 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 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)'
+
+
+
+
+
+== 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.12.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:cgcom.adoc#_cgcom_verifying-releases[vote]!
+
+
+
+
+== 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/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_asciidoc-templates.adoc
new file mode 100644
index 0000000..c8f7a9f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_asciidoc-templates.adoc
@@ -0,0 +1,741 @@
+[[_cgcon_asciidoc-templates]]
+= Appendix: Asciidoc 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
+
+
+
+This appendix lists the (IntelliJ) live templates available for xref:cgcon.adoc#_cgcon_asciidoc[writing documentation] using Asciidoc. Instructions for installing the templates can be found xref:cgcon.adoc#_cgcon_ide-templates[here].
+
+In the examples below the text `xxx`, `yyy`, `zzz` are correspond to template variables (ie placeholders).
+
+== Callouts
+
+The Asciidoctor terminology is an "admonition".
+
+[cols="1,4,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+|`adadmimportant`
+| `[IMPORTANT] +
+==== +
+xxx +
+====`
+|[IMPORTANT]
+====
+xxx
+====
+
+|`adadmnote`
+| `[NOTE] +
+==== +
+xxx +
+====`
+|[NOTE]
+====
+xxx
+====
+
+|`adadmtip`
+| `[TIP] +
+==== +
+xxx +
+====`
+|[TIP]
+====
+xxx
+====
+
+|`adadmwarning`
+| `[WARNING] +
+==== +
+xxx +
+====`
+|[WARNING]
+====
+xxx
+====
+
+|===
+
+
+== TODO notes
+
+Add as a placeholder for documentation still to be written or which is work-in-progress.
+
+[cols="1,4a,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+|`adtodo`
+|pass:[<pre>NOTE: TODO</pre>]
+|NOTE: TODO
+
+|`adwip`
+|pass:[<pre>NOTE: WIP - xxx</pre>]
+
+where:
+
+* `xxx` is additional explanatory text
+
+|NOTE: WIP - cool new feature
+
+|===
+
+
+
+
+== Xref to Guides
+
+Cross-references (links) to the various guides
+
+[cols="1,4a,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+
+|`adcgcom`
+|pass:[<pre>xref:cgcom.adoc#xxx[ttt\]</pre>]
+
+a hyperlink to a bookmark within the committers' guide, where:
+
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink
+
+for example:
+
+pass:[<pre>xref:cgcon.adoc#_cgcom_cutting-a-release[Cutting a release\]</pre>]
+
+|`adcgcon`
+|pass:[<pre>xref:cgcom.adoc#xxx[ttt\]</pre>]
+
+a hyperlink to a bookmark within the contributors' guide, where:
+
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink
+
+for example:
+
+pass:[<pre>xref:cgcon.adoc#_cgcon_asciidoc-templates[Asciidoc templates\]</pre>]
+
+|xref:cgcon.adoc#_cgcon_asciidoc-templates[Asciidoc templates]
+
+
+
+|`adrgcfg`
+|pass:[<pre>xref:rgcfg.adoc#xxx[ttt\]</pre>]
+
+a hyperlink to a bookmark within configuration properties guide, where:
+
+* `xxx` is the bookmark
+* `ttt` is the text to display as the hyperlink
+
+for example:
+
+pass:[<pre>xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core\]</pre>]
+
+|xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]
+
+
+
+|`adrgcs`
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_xxx[`xxx`\]</pre>]
+
+a hyperlink to the "man page" for a superclass, where:
+
+* `xxx` is the superclass (eg `AbstractDomainService`)
+
+for example:
+
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`\]</pre>]
+
+|xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]
+
+
+
+|`adrgcu`
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_utility_xxx[`xxx`\]</pre>]
+
+a hyperlink to the "man page" for a utility class, where:
+
+* `xxx` is the utility class (eg `TitleBuffer`)
+
+for example:
+
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_utility_TitleBuffer[`TitleBuffer`\]</pre>]
+
+|xref:rgcms.adoc#_rgcms_classes_utility_TitleBuffer[`TitleBuffer`]
+
+
+
+|`adrgcv`
+|pass:[<pre>xref:rgcms.adoc#_rgcms_classes_value-types_xxx[`xxx`\]</pre>]
+
+
+a hyperlink to the "man page" for an applib value class, where:
+
+* `xxx` is the utility class (eg `Blob`)
+
+for example:
+
+pass:[<pre>xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`\]</pre>]
+
+|xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
+
+
+
+|`adrgmp`
+|pass:[<pre>xref:rgcms.adoc#_rgcms_methods_prefixes_xxx[`xxx...()`\]</pre>]
+
+a hyperlink to the "man page" for a prefixed method, where:
+
+* `xxx` is the method prefix (eg `disable...()`)
+
+for example:
+
+pass:[<pre>xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`\]</pre>]
+
+|xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
+
+
+
+|`adrgmr`
+|pass:[<pre></pre>]
+
+a hyperlink to the "man page" for a reserved method, where:
+
+* `xxx` is the method prefix (eg `title()`)
+
+for example:
+
+pass:[<pre>xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`\]</pre>]
+
+|xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
+
+
+
+|`adrgna`
+|pass:[<pre>xref:rgant.adoc#_rgant-xxx[`@xxx`]</pre>]
+
+a hyperlink to the "man page" for an annotation, where:
+
+* `xxx` is the annotation type (eg `@Action`)
+
+for example:
+
+pass:[<pre>xref:rgant.adoc#_rgant-Action[`@Action`\]</pre>]
+
+|xref:rgant.adoc#_rgant-Action[`@Action`]
+
+
+
+|`adrgnt`
+|pass:[<pre>xref:rgant.adoc#_rgant-xxx_ttt[`@xxx#ttt()`]</pre>]
+
+a hyperlink to the "man page" for the specific attribute (field) of an annotation, where:
+
+* `xxx` is the annotation type (eg `@Action`)
+* `ttt` is the attribute (eg `@semantics`)
+
+for example:
+
+pass:[<pre>xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`\]</pre>]
+
+|xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]
+
+
+
+|`adrgsa`
+|pass:[<pre></pre>]
+
+a hyperlink to the "man page" for an (API) domain service, where:
+
+* `xxx` is the domain service (eg `DomainObjectContainer`)
+
+for example:
+
+pass:[<pre>xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`\]</pre>]
+
+|xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
+
+
+
+|`adrgss`
+|pass:[<pre></pre>]
+
+a hyperlink to the "man page" for an (SPI) domain service, where:
+
+* `xxx` is the domain service (eg `ContentMappingService`)
+
+for example:
+
+pass:[<pre>xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`\]</pre>]
+|xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]
+
+
+
+
+|`adugfun`
+|pass:[<pre>xref:ugfun.adoc#xxx[ttt\]</pre>]
+
+a hyperlink to a bookmark within the fundamentals users' guide, where:
+
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink
+
+for example:
+
+pass:[<pre>xref:ugfun.adoc#_ugfun_core-concepts[Core concepts\]</pre>]
+
+|xref:ugfun.adoc#_ugfun_core-concepts[Core concepts]
+
+
+
+
+|`adugvw`
+|pass:[<pre>xref:ugvw.adoc#xxx[ttt\]</pre>]
+
+A hyperlink to a bookmark within the Wicket viewer guide, where:
+
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
+
+for example:
+
+pass:[<pre>xref:ugvw.adoc#_ugvw_customisation[Customisation\]</pre>]
+
+|xref:ugvw.adoc#_ugvw_customisation[Customisation]
+
+
+|`adugvro`
+|pass:[<pre>xref:ugvro.adoc#xxx[ttt\]</pre>]
+
+A hyperlink to a bookmark within the Restful Objects viewer guide, where:
+
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
+
+for example:
+
+pass:[<pre>xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification\]</pre>]
+
+|xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]
+
+
+
+
+|`adugsec`
+|pass:[<pre>xref:ugsec.adoc#xxx[ttt\]</pre>]
+
+A hyperlink to a bookmark within the Secrurity guide, where:
+
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
+
+for example:
+
+pass:[<pre>xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features\]</pre>]
+
+|xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]
+
+
+|`adugtst`
+|pass:[<pre>xref:ugtst.adoc#xxx[ttt\]</pre>]
+
+A hyperlink to a bookmark within the Testing guide, where:
+
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
+
+for example:
+
+pass:[<pre>xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support\]</pre>]
+
+|xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]
+
+
+|`adugbtb`
+|pass:[<pre>xref:ugbtb.adoc#xxx[ttt\]</pre>]
+
+A hyperlink to a bookmark within the 'Beyond the Basics' user guide, where:
+
+* `xxx` is the bookmark's anchor
+* `ttt` is the text to display as the hyperlink.
+
+for example:
+
+pass:[<pre>xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration\]</pre>]
+
+|xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration]
+
+
+
+|`adugsimpleapp`
+|pass:[<pre>xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype\]</pre>]
+
+A hyperlink to the `simpleapp` archetype in the "getting started" chapter.
+
+|xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
+
+
+
+|===
+
+
+
+
+== Link to Isis Addons
+
+Links to (non-ASF) link:http://isisaddons.org[Isis Addons]
+
+[cols="1,4a,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+
+|`adlinkaddons`
+|pass:[<pre>(non-ASF) link:http://isisaddons.org[Isis Addons\]</pre>]
+
+link to the Isis Addons website.
+
+|(non-ASF) link:http://isisaddons.org[Isis Addons]
+
+
+
+|`adlinkaddonsapp`
+|pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-app-xxx[Isis addons' xxx]</pre>]
+
+link to the github repo for an example app from the Isis addons; where:
+
+* `xxx` is the name of the example app being linked to
+
+for example:
+
+pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp\]</pre>]
+
+|(non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]
+
+
+
+|`adlinkaddonsmodule`
+|pass:[<pre></pre>]
+
+link to the github repo for a module from the Isis addons; where:
+
+* `xxx` is the name of the module being linked to
+
+for example:
+
+pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security\] module</pre>]
+
+|(non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module
+
+
+
+|`adlinkaddonswicket`
+|pass:[<pre></pre>]
+
+link to the github repo for a wicket UI component from the Isis addons; where:
+
+* `xxx` is the name of the wicket UI component being linked to
+
+for example:
+
+pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3 \] wicket extension</pre>]
+
+
+|(non-ASF) http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3 ] wicket extension
+
+|===
+
+
+
+
+== Source code
+
+[cols="1,4a,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+|`adsrcjava`
+|`[source,java] +
+---- +
+xxx +
+----`
+
+where:
+
+* `xxx` is the source code snippet.
+
+|[source,java]
+----
+public class Foo {
+ ...
+}
+----
+
+
+|`adsrcjavac`
+|as for `adsrcjava`, but with a caption above
+|
+
+
+
+|`adsrcjavascript`
+|`[source,javascript] +
+---- +
+xxx +
+----`
+
+where:
+
+* `xxx` is the source code snippet.
+
+|[source,javascript]
+----
+$(document).ready(function() {
+ ...
+});
+----
+
+
+
+|`adsrcjavascriptc`
+|as for `adsrcjavascript`, but with a caption above
+
+|
+
+|`adsrcother`
+|`[source,nnn] +
+---- +
+xxx +
+----`
+
+where:
+
+* `nnn` is the programming language
+* `xxx` is the source code snippet.
+
+|
+
+|`adsrcotherc`
+|as for `adsrcother`, but with a caption above
+
+
+|
+
+|`adsrcxml`
+|`[source,javascript] +
+---- +
+xxx +
+----`
+
+where:
+
+* `xxx` is the source code snippet.
+
+|[source,xml]
+----
+<html>
+ <title>
+ hello world!
+ </title>
+</html>
+----
+
+
+|`adsrcxmlc`
+|as for `adsrcxml`, but with a caption above
+|
+
+|===
+
+
+== Images
+
+[cols="1,4a,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+|`adimgfile`
+|pass:[<pre>image::{_imagesdir}xxx/yyy.png[width="WWWpx",link="{_imagesdir}xxx/yyy.png"\]</pre>]
+
+embeds specified image, where:
+
+* `xxx` is the subdirectory under the `images/` directory
+* `yyy` is the image
+* `WWW` is the width, in pixels.
+
+for example:
+
+pass:[<pre>image::{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="300px",link="{_imagesdir}wicket-viewer/layouts/estatio-Lease.png"\]</pre>]
+
+|image::{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="300px",link="{_imagesdir}wicket-viewer/layouts/estatio-Lease.png"]
+
+
+
+|`adimgfilec`
+|as for `adimgfile`, but with a caption above
+|
+
+
+|`adimgurl`
+|pass:[<pre>image::xxx[width="WWWpx",link="xxx"\]</pre>]
+
+embeds image from specified URL, where:
+
+* `xxx` is the URL to the image
+* `WWW` is the width, in pixels.
+
+|
+
+
+
+|`adimgurlc`
+|as for `adimgurl`, but with a caption above
+|
+
+
+|===
+
+
+
+== YouTube (screencasts)
+
+Embedded youtube screencasts
+
+[cols="1,4a,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+|`adyoutube`
+|pass:[<pre>video::xxx[youtube,width="WWWpx",height="HHHpx"\]</pre>]
+
+where:
+
+* `xxx` is the youtube reference
+* `WWW` is the width, in pixels
+* `HHH` is the height, in pixels
+
+for example:
+
+pass:[<pre>video::bj8735nBRR4[youtube,width="210px",height="118px"\] </pre>]
+
+|video::bj8735nBRR4[youtube,width="210px",height="118px"]
+
+
+|`adyoutubec`
+|as for `youtube`, but with a caption above
+|
+
+|===
+
+
+== Tables
+
+[cols="1,4a,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+|`adtbl3`
+|Table with 3 columns, 3 rows.
+|
+
+
+|===
+
+
+== Misc.
+
+[cols="1,4a,2a", options="header"]
+|===
+| Abbrev.
+| Produces
+| Example
+
+|`adai`
+|pass:[<pre>Apache Isis</pre>] +
+
+That is, the literal text "Apache Isis".
+|Apache Isis
+
+
+
+|`adlink`
+|pass:[<pre>link:xxx[ttt\]</pre>]
+
+, where:
+
+* `xxx` is
+* `ttt` is the text to display as the hyperlink
+
+for example:
+
+pass:[<pre>link:http://isis.apache.org[Apache Isis website\]</pre>]
+
+|link:http://isis.apache.org[Apache Isis website]
+
+
+
+
+|`adanchany`
+|pass:[<pre>= anchor:[xxx\]</pre>]
+
+defines an inline anchor to any heading, where:
+
+* `xxx` is the anchor text.
+
+For example:
+
+pass:[<pre>= anchor:[_ugfun_i18n\] Internationalization</pre>]
+
+An alternative (more commonly used in our documentation) is to use the `[[...]]` directly above the heading:
+
+pass:[<pre>[[_ugfun_i18n\]\]
+= Internationalization</pre>]
+
+|
+
+
+|`adxrefany`
+|pass:[<pre>xref:[xxx\]</pre>]
+
+cross-reference to any document/anchor, where:
+
+* `xxx` is the fully qualified document with optional anchor
+
+|
+
+
+|`adfootnote`
+|pass:[<pre>.footnote:[\]</pre>]
+
+defines a footnote
+|.footnote:[this is a footnote]
+
+
+
+|===
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_asciidoc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_asciidoc.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_asciidoc.adoc
new file mode 100644
index 0000000..5bca34a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_asciidoc.adoc
@@ -0,0 +1,205 @@
+[[_cgcon_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].
+
+And to help write the Asciidoc text itself, we provide some xref:cgcon.adoc#_cgcon__cg_ide-templates[templates].
+
+
+== 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/
+----
+
+
+
+== Writing the docs
+
+We highly recommend that you install the (IntelliJ) live templates for Asciidoctor, as described in xref:cgcon.adoc#_cgcon_ide-templates[IDE templates]. These provide a large number of helper templates.
+
+An xref:cgcon.adoc#_cgcon_appendix_asciidoc-templates[appendix] lists all the templates available, demonstrating their intended usage and output.
+
+
+== Build and Review (using Maven)
+
+To (re)build the documentation locally prior to release, change into the `adocs/documentation` directory and 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 compile` command, regenerating any changed Asciidoctor files to the relevant `target/site` directory. Moreover if any included files are changed then it rebuilds the parent (per the above naming convention).
+
+=== One-time setup
+
+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 download the required Ruby dependencies, use:
+
+[source,bash]
+----
+gem install bundler
+bundle install
+----
+
+=== Instant Rebuild
+
+To run, we typically just use:
+
+[source,bash]
+----
+sh monitor.sh
+----
+
+This script simply runs `mvn clean compile && ruby monitor.rb -b`. The `mvn` command performs a clean rebuild of the site, and then the ruby script monitors for any further changes under `src/main/asciidoc`.
+
+The script also starts 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. The `-b` flag passed through means that the script also starts a web browser pointing at the newly generated docs.
+
+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:cgcom.adoc#[Committers' 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 `adocs/documentation` directory of 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]
+----
+sh publish.sh "ISIS-nnnn: a custom commit message"
+----
+
+Behind the scenes this just calls `mvn clean install -Dmessage=...`.
+
+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].
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_building-isis.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_building-isis.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_building-isis.adoc
new file mode 100644
index 0000000..69ec333
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_building-isis.adoc
@@ -0,0 +1,222 @@
+[[_cgcon_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:cgcon.adoc#_cgcon_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 "origin"]` 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,bash]
+----
+export MAVEN_OPTS="-Xms512m -Xmx1024m"
+----
+
+
+[NOTE]
+====
+Previously we suggested `-XX:MaxPermSize=256m`, but this option has been removed in Java 8. (As of 1.9.0, Apache Isis is built using Java 8 but with source and target set to JDK 1.7).
+====
+
+
+== 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). To save more time still, we also recommend that you build in parallel. (Per this link:http://zeroturnaround.com/rebellabs/your-maven-build-is-slow-speed-it-up/[blog post]), you could also experiment with a number of JDK parameters that we've found also speed up Maven:
+
+[source,bash]
+----
+export MAVEN_OPTS="-Xms512m -Xmx1024m -XX:+TieredCompilation -XX:TieredStopAtLevel=1"
+mvn clean install -o -T1C
+----
+
+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.
+
+
+
+== Checking for Vulnerabilities
+
+Apache Isis configures the link:https://www.owasp.org/index.php/Main_Page[OWASP] link:https://www.owasp.org/index.php/OWASP_Dependency_Check[dependency check] link:http://jeremylong.github.io/DependencyCheck/dependency-check-maven/index.html[Maven plugin] to determine whether the framework uses libraries that are known to have security vulnerabilities.
+
+To check, run:
+
+[source,bash]
+----
+mvn org.owasp:dependency-check-maven:aggregate -Dowasp
+----
+
+This will generate a single report under `target/dependency-check-report.html`.
+
+
+[NOTE]
+====
+The first time this runs can take 10~20 minutes to download the NVD data feeds.
+====
+
+To disable, either run in offline mode (add `-o` or `--offline`) or omit the `owasp` property.
+
+
+
+== Checking for use of internal JDK APIs
+
+Apache Isis configures the link:https://maven.apache.org/plugins-archives/maven-jdeps-plugin-3.0.0/[jdeps maven plugin] to check for any usage of internal JDK APIs. This is in preparation for Java 9 module system (Jigsaw) which will prevent such usage of APIs.
+
+To check, run:
+
+[source,bash]
+----
+mvn clean install -Djdeps
+----
+
+This will fail the build on any module that currently uses an internal JDK API.
+
+
+[NOTE]
+====
+At the time of writing the `isis-core-schema` module fails the build.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_cmd-line.adoc
new file mode 100644
index 0000000..b487c16
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_cmd-line.adoc
@@ -0,0 +1,9 @@
+[[_cgcon_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/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_contributing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_contributing.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_contributing.adoc
new file mode 100644
index 0000000..389de1a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_contributing.adoc
@@ -0,0 +1,255 @@
+[[_cgcon_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:cgcon.adoc#_cgcon_ide[set up your IDE] and learn xref:cgcon.adoc#_cgcon_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:cgcon.adoc#_cgcon_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/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_git-cookbook.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_git-cookbook.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_git-cookbook.adoc
new file mode 100644
index 0000000..66fe524
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_git-cookbook.adoc
@@ -0,0 +1,258 @@
+[[_cgcon_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 appendix describes the commands often used while working with git. In addition to these basic commands, please make sure you have read:
+
+* xref:cgcon.adoc#_cgcon_building-isis[building Apache Isis]
+* xref:cgcon.adoc#_cgcon_policies_git-policy[Git policy]
+* xref:cgcon.adoc#_cgcon_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:cgcon.adoc#_cgcon_contributing[contributing] page describes the workflow for non-committers. The xref:cgcon.adoc#_cgcon_policies_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/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide-templates.adoc
new file mode 100644
index 0000000..ac36e05
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide-templates.adoc
@@ -0,0 +1,95 @@
+[[_cgcon_ide-templates]]
+= Code and File 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 parameterized templates, for both IntelliJ and Eclipse, to help you write your domain applications.
+
+On IntelliJ we provide both file templates (`File > Settings > Editor > File and Code Templates`) and also live templates (`File > Settings > Editor > Live Templates`). The former are used to create new classes or files (eg a new domain entity), while the latter are intended to modify an existing file (eg create a new property or add a `toString()` method etc).
+
+On Eclipse we provide only the latter sort of template (Windows > Preferences > Java > Editor > Templates).
+
+There are templates for writing Apache Isis domain objects, for writing unit tests (JUnit and JMock), and also for writing Asciidoc documentation (see also the xref:cgcon.adoc#_cgcon_asciidoc-templates[appendix]).
+
+
+== Download
+
+The following table lists the templates available to download:
+
+[cols="2a,2a,1a,2a,2a", options="header"]
+|===
+
+
+|Purpose
+|IntelliJ +
+file template
+|Prefix
+|IntelliJ +
+live template
+|Eclipse +
+template
+
+|Domain Objects
+|link:../resources/templates/intellij-settings-file-templates-for-apache-isis.jar[Download]
+|`is`
+|link:../resources/templates/isis-templates-idea.xml[Download]
+|link:../resources/templates/isis-templates.xml[Download]
+
+|JUnit tests
+|(none)
+|`ju`
+|link:../resources/templates/junit4-templates-idea.xml[Download]
+|link:../resources/templates/junit4-templates.xml[Download]
+
+
+|JMock tests
+|(none)
+|`jm`
+|link:../resources/templates/jmock2-templates-idea.xml[Download]
+|link:../resources/templates/jmock2-templates.xml[Download]
+
+|Asciidoc
+|(none)
+|`ad`
+|link:../resources/templates/isis-asciidoc-templates-idea.xml[Download]
+|(none)
+
+|===
+
+
+The most commonly used domain objects (live) templates are also listed on the link:../cheat-sheet.html[Apache Isis cheat sheet].
+
+
+
+== Installation
+
+=== IntelliJ
+
+To install in the live templates IntelliJ (Community edition 15), copy to the relevant `config/templates` directory, eg:
+
+* Windows `<User home>\.IdeaIC15\config\templates`
+* Linux `~/.IdeaIC14/config/templates`
+* Mac OS `~/Library/Preferences/IdeaIC15/templates`
+
+If using the Ultimate edition, the directory is `.IntelliJIdea15` rather than `IdeaIC15`.
+
+
+To install the file templates, use `File > Import Settings`.
+
+
+=== Eclipse
+
+To install in Eclipse, go to `Windows > Preferences > Java > Editor > Templates` and choose `Import`.
+
+
+
+== Usage
+
+For the live templates, enter the prefix in the editor (`is`, `ju`, `jm`) and the IDE will list all available templates
+in that category.
+
+For the file templates (IntelliJ only), these are available from `File > New`.
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide.adoc
new file mode 100644
index 0000000..0e6f35d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide.adoc
@@ -0,0 +1,19 @@
+[[_cgcon_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::_cgcon_ide_intellij.adoc[leveloffset=+1]
+include::_cgcon_ide_eclipse.adoc[leveloffset=+1]
+include::_cgcon_ide_project-lombok.adoc[leveloffset=+1]
+include::_cgcon_ide_agilej.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_agilej.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_agilej.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_agilej.adoc
new file mode 100644
index 0000000..3798e49
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_agilej.adoc
@@ -0,0 +1,55 @@
+[[_cgcon_ide_agilej]]
+= AgileJ
+: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]
+====
+This material does not constitute an endorsement; AgileJ Structure Views is not affiliated to Apache Software Foundation in any way.
+====
+
+link:http://www.agilej.com/[AgileJ Structure Views] is a commercial product to reverse engineer and visualize Java classes from source code.
+
+The key to using the tool is in developing a suitable filter script, a DSL. You can use the following script as a starting point for visualizing Apache Isis domain models:
+
+[source,AgileJ]
+----
+// use CTRL+SPACE for completion suggestions
+hide all fields
+hide setter methods
+hide private methods
+hide methods named compareTo
+hide methods named toString
+hide methods named inject*
+hide methods named disable*
+hide methods named default*
+hide methods named hide*
+hide methods named autoComplete*
+hide methods named choices*
+hide methods named title
+hide methods named iconName
+hide methods named validate*
+hide methods named modify*
+hide protected methods
+hide types annotated as DomainService
+hide types named Constants
+hide types named InvoicingInterval
+hide enums
+hide constructors
+hide inner types named *Event
+hide inner types named *Functions
+hide inner types named *Predicates
+show getter methods in green
+show methods annotated as Programmatic in orange
+show methods annotated as Action in largest
+hide dependency lines
+hide call lines
+hide method lines
+----
+
+For more information on AgileJ, see Paul Wells' 8-part tutorial series on Youtube; the first can be found link:https://www.youtube.com/watch?v=YrZQ7lMSsH0[here] (view the "show more" comments to click through to other parts).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/49ccfd90/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_eclipse.adoc
new file mode 100644
index 0000000..2be2ad2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcon_ide_eclipse.adoc
@@ -0,0 +1,160 @@
+[[_cgcon_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
+
+
+[NOTE]
+====
+This material does not constitute an endorsement; Eclipse foundation is not affiliated to Apache Software Foundation in any way.
+====
+
+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 > Import, then Maven > 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:ugfun.adoc#_ugfun_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:ugfun.adoc#_ugfun_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.
+
+
+
+== 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
+
+link:github.com/dcevm/dcevm[DCEVM] enhances the JVM with true hot-swap adding/removing of methods as well as more
+reliable hot swapping of the implementation of existing methods.
+
+In the context of Apache Isis, this is very useful for contributed actions and mixins and also view models; you should
+then be able to write these actions and have them be picked up without restarting the application.
+
+Changing persisting domain entities is more problematic, for two reasons: the JDO/DataNucleus enhancer needs to run on
+domain entities, and also at runtime JDO/DataNucleus would need to rebuild its own metamodel. You may find that adding
+actions will work, but adding new properties or collections is much less likely to.
+
+For details of setting up DCEVM, see the xref:cgcon.adoc#_cgcon_ide_intellij_advanced_dcevm[corresponding section] in the IntelliJ documentation.
+