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 2017/03/31 07:10:49 UTC
[13/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
new file mode 100644
index 0000000..d113a6b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
@@ -0,0 +1,665 @@
+[[_cgcom_post-release-successful]]
+= Post Release (Successful)
+: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 xref:cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
+* the release manager performing post-release tasks, for either a successful or an xref:cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote (former documented below)
+
+For a vote to succeed, there must be +3 votes from PMC members, and the vote must have been open at least 72 hours. If there are not +3 votes after this time then it is perfectly permissible to keep the vote open longer.
+
+This section describes the steps to perform if the vote has been successful.
+
+
+
+
+== Inform dev ML
+
+Post the results to the `dev@isis.a.o` mailing list:
+
+[source,bash]
+----
+[RESULT] [VOTE] Apache Isis Core release 1.14.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 SUCCESSFUL.
+----
+
+
+
+== Update tags
+
+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.sh isis-1.14.0 RC1
+sh scripts/promoterctag.sh simpleapp-archetype-1.14.0 RC1
+----
+
+This script pushes the tag under `refs/tags/rel`. As per Apache policy (communicated on 10th Jan 2016 to Apache PMCs),
+this path is 'protected' and is unmodifiable (guaranteeing the provenance that the ASF needs for releases).
+
+Then, continue onto the next section for the steps to promote and announce the release.
+
+
+
+
+== Release to Maven Central
+
+From the http://repository.apache.org[ASF Nexus repository], 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 link: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 link: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/
+ example/
+ archetype/
+ simpleapp/
+----
+
+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. The `upd.sh` script (also downloadable from link:https://gist.github.com/danhaywood/aa79c18d993df1b1e2c5a9933e48bcbc[this gist]) can be used to automate this:
+
+[source,bash]
+----
+old_ver=$1
+new_ver=$2
+
+
+# constants
+repo_root=https://repository.apache.org/content/repositories/releases/org/apache/isis
+
+zip="source-release.zip"
+asc="$zip.asc"
+md5="$zip.md5"
+
+
+#
+# isis-core
+#
+type="core"
+fullname="isis"
+pushd isis-core
+
+curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$asc
+svn add $fullname-$new_ver-$asc
+curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$md5
+svn add $fullname-$new_ver-$md5
+curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$zip
+svn add $fullname-$new_ver-$zip
+
+svn delete $fullname-$old_ver-$asc
+svn delete $fullname-$old_ver-$md5
+svn delete $fullname-$old_ver-$zip
+
+popd
+
+
+#
+# simpleapp-archetype
+#
+type="archetype"
+fullname="simpleapp-archetype"
+pushd $type/$fullname
+
+curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$md5
+svn add $fullname-$new_ver-$md5
+curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$asc
+svn add $fullname-$new_ver-$asc
+curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$zip
+svn add $fullname-$new_ver-$zip
+
+svn delete $fullname-$old_ver-$md5
+svn delete $fullname-$old_ver-$asc
+svn delete $fullname-$old_ver-$zip
+
+popd
+----
+
+[source,bash]
+----
+sh upd.sh 1.14.0 1.15.0
+----
+
+The script downloads the artifacts from the Nexus release repository, adds the artifacts to subversion and deletes the previous version.
+
+
+
+Double check that the files are correct; there is sometimes a small delay in the files becoming available in the release repository. It should be sufficient to check just the `md5` or `.asc` files that these look valid (aren't HTML 404 error pages):
+
+[source,bash]
+----
+vi `find . -name *.md5`
+----
+
+Assuming all is good, commit the changes:
+
+[source]
+----
+svn commit -m "publishing isis source releases to dist.apache.org"
+----
+
+If the files are invalid, then revert using `svn revert . --recursive` and try again in a little while.
+
+
+
+== Update JIRA
+
+=== Generate Release Notes
+
+From the root directory, generate the release notes for the current release, in Asciidoc format; eg:
+
+[source,bash]
+----
+sh scripts/jira-release-notes.sh ISIS 1.14.0 > /tmp/1
+----
+
+
+=== Close tickets
+
+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.
+
+
+
+=== Mark the version as released
+
+In JIRA, go to the link:https://issues.apache.org/jira/plugins/servlet/project-config/ISIS/versions[administration section] for the Apache Isis project and update the version as being released.
+
+In the link:https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=87[Kanban view] this will have the effect of marking all tickets as released (clearing the "done" column).
+
+
+=== Create new JIRA
+
+Create a new JIRA ticket as a catch-all for the _next_ release.
+
+
+=== Update the ASF Reporter website
+
+Log the new release in the link:https://reporter.apache.org/addrelease.html?isis[ASF Reporter website].
+
+
+
+== Update website
+
+Update the Apache Isis (asciidoc) website:
+
+* Paste in the JIRA-generated release notes generated above, adding to top of `adocs/documentation/src/main/asciidoc/release-notes.adoc`. Also add a summary line for the release.
+
+* Search for any `-SNAPSHOT` suffices, and remove
+
+* Search these release procedures, and update any hard-coded reference to the release to the next release (so when they are followed next time the text will be correct).
+
+* Update the link:../downloads.html[downloads 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])
+
+* Update any pages (`.adoc`, `.md`, `.html` etc) that describe how to run the archetype, and ensure they reference the correct version. +
++
+A search for `archetypeGroupId=org.apache.isis.archetype` should find these pages.
+
+* update 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].
+
+* Update the https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=blob_plain;f=STATUS;hb=HEAD[STATUS] file (in root of Apache Isis' source) should be updated with details of the new release.
+
+
+Don't forget to commit the `.adoc` changes and publish to the isis-site repo.
+
+
+
+
+
+== 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.14.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 v1.14.0.
+
+New features in this release include:
+* ...
+
+Full release notes are available on the Apache Isis website at [1]. Please also read the migration notes [2].
+
+You can access this release directly from the Maven central repo [3], or download the release and build it from
+source [4].
+
+Enjoy!
+
+--The Apache Isis team
+
+[1] http://isis.apache.org/release-notes.html#r1.14.0
+[2] http://isis.apache.org/migration-notes.html#_migration-notes_1.13.0-to-1.14.0
+[3] http://search.maven.org
+[4] http://isis.apache.org/downloads.html
+----
+
+
+
+
+== Blog post
+
+link: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.
+
+
+
+
+
+== Merge in release 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 release-1.14.0-RC1 # merge branch onto master
+git push origin --delete release-1.14.0-RC1 # remote branch no longer needed
+git branch -d release-1.14.0-RC1 # branch no longer needed
+----
+
+
+Finally, update the simpleapp's root `pom.xml` to reference the next SNAPSHOT release (`1.15.0-SNAPSHOT`)
+
+
+
+== Update dependencies
+
+With the release complete, now is a good time to bump versions of dependencies (so that there is a full release cycle to identify any possible issues).
+
+You will probably want to create a new JIRA ticket for these updates (or if minor then use the "catch-all" JIRA ticket raised earlier for the next release).
+
+
+=== Update parent of 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 `<version>` in the `<parent>` 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.
+
+
+
+=== 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 formatting
+
+This is also a good time to make 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.
+
+
+
+== Push changes
+
+Finally, push the changes up to origin:
+
+[source,bash]
+----
+git fetch # check no new commits on origin/master
+git push
+----
+
+
+
+[[__cgcom_post-release-successful_release-non-asf-modules]]
+== Release (non-ASF) Modules
+
+There are two libraries of modules, both non-ASF but open source, that should be released.
+
+* link:http://isisaddons.org[Isis Addons] - modules addressing technical concerns
+* link:http://catalog.incodehq.org[Incode Catalog] - modules for various generic business subdomains
+
+These each use a common parent, `org.incode:incode-parent`.
+This must be released first, then both set of modules afterwards.
+
+
+[[__cgcom_post-release-successful_release-non-asf-modules_prereqs]]
+=== Prereqs
+
+Save this link:https://gist.github.com/danhaywood/e80daf6d25f5c1fb1093effba85d088a[gist] as `last_modified.sh` in an appropriate parent directory of both sets of repos.
+
+For example, if the isisaddons modules are cloned to `/c/github/isisaddons/isis-module-xxx` and the incode catalog modules are cloned to `/c/github/incodehq/incode-module-xxx`, then save in `/c/github`.
+
+
+
+[[__cgcom_post-release-successful_release-non-asf-modules_incode-parent]]
+=== Release `incode-parent`
+
+The `org.incode:incode-parent` Maven module is used as a parent for both sets of modules:
+
+* update its dependency on Apache Isis to reference the newly released version: +
++
+[source,bash]
+----
+sh bumpver_isis.sh 1.14.0
+----
+
+* update the README
+
+** replace each version with next (ie the "How to Configure/Use" section, and the "Release to Maven Central" section at the end):
+
+*** replace 1.14.0-SNAPSHOT with 1.15.0-SNAPSHOT
+*** replace 1.13.0 with 1.14.0
+
+** update the "Change Log" section
+
+* Release using: +
++
+[source,bash]
+----
+sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" "this is not really my password"
+----
+
+
+
+[[__cgcom_post-release-successful_release-non-asf-modules_incode-mavendeps]]
+=== Release `incode-mavendeps`
+
+The three `org.incode:mavendeps-isisXXX` module should be released next.
+
+* update its dependency on Apache Isis to reference the newly released version: +
++
+[source,bash]
+----
+foreach -g incodehq/mavendeps sh bumpver_isis.sh 1.14.0
+----
+
+* update the README
+
+** replace each version with next (ie the "How to Configure/Use" section, and the "Release to Maven Central" section at the end):
+
+*** replace 1.14.0-SNAPSHOT with 1.15.0-SNAPSHOT
+*** replace 1.13.0 with 1.14.0
+
+** update the "Change Log" section
+
+* Release using: +
++
+[source,bash]
+----
+foreach -g incodehq/mavendeps sh sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
+----
+
+* update its dependency on Apache Isis to reference the next SNAPSHOT: +
++
+[source,bash]
+----
+foreach -g incodehq/mavendeps sh bumpver_isis.sh 1.15.0-SNAPSHOT
+----
+
+
+
+[[__cgcom_post-release-successful_release-non-asf-modules_isisaddons]]
+=== Release Isis Addons
+
+Once the Apache Isis release is available, all of the (non-ASF) link:http://isisaddons.org[Isis Addons] should also be released.
+
+Using this link:https://gist.github.com/danhaywood/21b5b885433fd8bc440da3fab88c91cb[gist] to invoke operations across all (or selected) addons:
+
+* update its dependency on Apache Isis to reference the newly released version: +
++
+[source,bash]
+----
+foreach -g isisaddons sh bumpver_isis.sh 1.14.0
+----
++
+and use: +
++
+[source,bash]
+----
+foreach -g isisaddons git diff HEAD^ HEAD
+----
++
+and: +
++
+[source,bash]
+----
+foreach -g isisaddons git status --branch --porcelain
+----
++
+to review changes made.
+
+* update the README for each repository.
+
+** if using Windows, then: +
++
+[source,bash]
+----
+"C:\Program Files (x86)\Notepad++\notepad++.exe" isisaddons/isis-m*/README.adoc isisaddons/isis-w*/README.adoc
+----
+
+** replace each version with next (ie the "How to Configure/Use" section, and the "Release to Maven Central" section at the end):
+
+*** replace `1.14.0` with `1.15.0`
+*** replace `1.13.0` with `1.14.0` as necessary (pretty much everywhere apart from the "Change Log")
+
+** update the "Change Log" section
+
+* release the metamodel/module/wicket modules to mvn central (contains a sanity check before hand that everything compiles): +
++
+[source,bash]
+----
+foreach -g isisaddons/isis-[mw] sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
+----
+
+* In the parent directory where the `last_modified.sh` script has been saved (see xref:cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_prereqs[above]), use to check that all modules were released successfully: +
++
+[source,bash]
+----
+foreach -g isisaddons/isis-[mw] sh ../../last-modified.sh 1.14.0
+----
++
+[IMPORTANT]
+====
+Wait at least 10 minutes to check; sync'ing to Maven central from the Sonatype OSS repository isn't instaneous.
+====
+
+* Assuming everything did get published ok, then push branch and tag: +
++
+[source,bash]
+----
+foreach -g isisaddons/isis-[mw] "git push origin master && git push origin 1.14.0"
+----
+
+
+[[__cgcom_post-release-successful_release-non-asf-modules_incode-catalog]]
+=== Release Incode Catalog Modules
+
+Similarly, all of the (non-ASF) link:http://catalog.incode.org[Incode Catalog] modules should also be released.
+
+Using this link:https://gist.github.com/danhaywood/21b5b885433fd8bc440da3fab88c91cb[gist] to invoke operations across all (or selected) addons:
+
+* update its dependency on Apache Isis to reference the newly released version: +
++
+[source,bash]
+----
+foreach -g incodehq/incode-module sh bumpver_isis.sh 1.14.0
+----
+
+* update the README for each repository. +
++
+eg if using Windows, then:
++
+[source,bash]
+----
+"C:\Program Files (x86)\Notepad++\notepad++.exe" incodehq/incode-*/README.adoc
+----
+
+** Replace each version with next (ie the "How to Configure/Use" section, and the "Release to Maven Central" section at the end):
+
+*** replace `1.14.0` with `1.15.0`
+*** replace `1.13.0` with `1.14.0` as necessary (pretty much everywhere apart from the "Change Log")
+
+** update the "Change Log" section
+
+* update cross-module dependencies +
++
+Some of the incode catalog modules depend on isisaddons modules, and also on each other. +
++
+eg if using Windows, then: +
++
+[source,bash]
+----
+"C:\Program Files (x86)\Notepad++\notepad++.exe" incodehq/incode-module*/pom.xml incodehq/incode-module-*/dom/pom.xml incodehq/incode-module-*/module/pom.xml
+----
++
+[TIP]
+====
+See xref:cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_incode-catalog_cross-module-dependencies[below] for a list of the dependencies to update.
+====
+
+* If necessary, adjust the `_repos.txt` file (used by `foreach` function) so that repositories are released in the correct sequence (with respect to their mutual dependencies).
+For example, `incode-module-base` must be released prior to `incode-module-alias`.
+
+* release the `incode-module-???` modules to mvn central (contains a sanity check before hand that everything compiles): +
++
+[source,bash]
+----
+foreach -g incodehq/incode-module-[a-w] sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
+----
+
+* In the parent directory where the `last_modified.sh` script has been saved (see xref:cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_prereqs[above]), use to check that all modules were released successfully: +
++
+[source,bash]
+----
+foreach -g incodehq/incode-module-[a-w] sh ../../last-modified.sh 1.14.0
+----
++
+[IMPORTANT]
+====
+Wait at least 10 minutes to check; sync'ing to Maven central from the Sonatype OSS repository isn't instaneous.
+====
+
+* Assuming everything did get published ok, then push branch and tag: +
++
+[source,bash]
+----
+foreach -g incodehq/incode-module-[a-w] "git push origin master && git push origin 1.14.0"
+----
+
+
+[[__cgcom_post-release-successful_release-non-asf-modules_incode-catalog_cross-module-dependencies]]
+==== Cross-module dependencies
+
+As of v1.14.0, the list of dependencies that needed to be updated (across all modules) were:
+
+** `<isis-module-fakedata.version>1.14.0</isis-module-fakedata.version>`
+** `<isis-module-freemarker.version>1.14.0</isis-module-freemarker.version>`
+** `<isis-wicket-fullcalendar2-cpt.version>1.14.0</isis-wicket-fullcalendar2-cpt.version>`
+** `<isis-wicket-gmap3-cpt.version>1.14.0</isis-wicket-gmap3-cpt.version>`
+** `<isis-module-poly.version>1.14.0</isis-module-poly.version>`
+** `<isis-module-security.version>1.14.0</isis-module-security.version>`
+** `<incode-module-base.version>1.14.0</incode-module-base.version>`
+** `<incode-module-fixturesupport.version>1.14.0</incode-module-fixturesupport.version>`
+** `<incode-module-unittestsupport.version>1.14.0</incode-module-unittestsupport.version>`
+** `<incode-module-integtestsupport.version>1.14.0</incode-module-integtestsupport.version>`
+** `<incode-module-country.version>1.14.0</incode-module-country.version>`
+** `<incode-module-document.version>1.14.0</incode-module-document.version>`
+** `<incode-module-docrendering-freemarker.version>1.14.0</incode-module-docrendering-freemarker.version>`
+** `<incode-module-docrendering-stringinterpolator.version>1.14.0</incode-module-docrendering-stringinterpolator.version>`
+** `<incode-module-docrendering-xdocreport.version>1.14.0</incode-module-docrendering-xdocreport.version>`
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
new file mode 100644
index 0000000..bf9e40e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
@@ -0,0 +1,94 @@
+[[_cgcom_post-release-unsuccessful]]
+= Post Release (Unsuccessful)
+: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 xref:cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
+* the release manager performing post-release tasks, for either a xref:cgcom.adoc#_cgcom_post-release-successful[successful] or an unsuccessful vote (latter documented below).
+
+If the vote did not succeed (did not achieve +3 votes after 72 hours and/or is unlikely to do so), then the vote should be closed and the following steps performed.
+
+Note that a release manager may also decide to cancel a vote before 72 hours has elapsed (for example if an error is quickly discovered).
+
+
+== Inform dev ML
+
+Post the results to the `dev@isis.a.o` mailing list.
+
+For example, use the following subject for a vote on Apache Isis Core:
+
+[source,bash]
+----
+[RESULT] [VOTE] Apache Isis Core release 1.14.0
+----
+
+using the body (alter last line as appropriate):
+
+[source,bash]
+----
+The vote has completed with the following result :
+
+ +1 (binding): _list of names_
+ +1 (non binding): _list of names_
+
+ -1 (binding): _list of names_
+ -1 (non binding): _list of names_
+
+The vote is UNSUCCESSFUL.
+----
+
+
+== Tidy up branches
+
+Tidy up remote branches in the git repo:
+
+* delete the remote branch, for example: +
++
+[source,bash]
+----
+git push --delete origin release-1.14.0-RC1
+----
+
+
+* delete the remote origin server's tags, for example: +
++
+[source,bash]
+----
+git push --delete origin isis-1.14.0-RC1
+git push --delete origin simpleapp-archetype-1.14.0-RC1
+----
+
+
+* delete the tags that were created locally, for example: +
++
+[source,bash]
+----
+git tag -d isis-1.14.0
+git tag -d isis-1.14.0-RC1
+git tag -d simpleapp-archetype-1.14.0
+git tag -d simpleapp-archetype-1.14.0-RC1
+----
+
+
+== Tidy up the Nexus repo
+
+Drop staging repositories:
+
+* drop the staging repository in http://repository.apache.org[Nexus]
+
+
+
+
+== Reset
+
+Finally, rewind the release branch to prior to the previous release candidate, and continue from there.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc
new file mode 100644
index 0000000..e021a10
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc
@@ -0,0 +1,80 @@
+[[_cgcom_release-process-for-interim-releases]]
+= Interim 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
+
+
+The intent of an "interim" release is to allow a developer team to release their application based on a `-SNAPSHOT` version of the framework. Since `-SNAPSHOT` changes on a day-to-day basis, the idea is to tag a particular revision and to release this, thereby providing stability/traceability for the application being developed.
+
+Whereas xref:cgcom.adoc#_cgcom_cutting-a-release.adoc[formal release]s and xref:cgcom.adoc#_cgcom_relesae-process-for-snapshots.adoc[snapshot release]s are public (released through the Maven repository maintained by Apache Software Foundation), interim releases are non-public and rely on infrastructure provided by a developer team. The tagged release resides _not_ in the link:../downloads.adoc#_downloads_source_code[official Apache Isis git repository], but instead in a fork/clone maintained by the developer team.
+
+[NOTE]
+====
+The procedure developed here was put together for the team working on the link:../powered-by.adoc#_powered-by_estatio[Estatio app], which maintains its own link:https://github.com/incodehq/isis[fork on github] and uses link:https://www.cloudbees.com/[CloudBees] as a Jenkins build server/private Maven repo.
+====
+
+
+== Prerequisites
+
+Create a remote fork/clone of the Apache Isis repository (eg using link:http://github.com[github] or link:http://bitbucket.org[bitbucket] or similar), and ensure that your local fork specifies this remote.
+
+Also, set up a CI server against your fork/clone, to build against any branches called `origin/interim/*`. To build it should use the command:
+
+[source,bash]
+----
+mvn clean install -Dskip.app -Dskip.arch
+----
+
+that is, skipping the example simpleapp and archetype; only `core` framework is built
+
+The CI server should then also publish the resultant artifacts to a local Maven repository. For example, Jenkins provides post-build plugins to perform such a task.
+
+
+
+== Sanity Check
+
+Ensure that the framework builds ok using the same command that your CI server is set up to execute (see section above).
+
+
+
+== Release
+
+Deploy the framework using:
+
+[source,bsah]
+----
+sh interim-release.sh xxx yyyyy
+----
+
+where `xxx` is the most recent release of Isis (to act as the base), and `yyyyy` is the name of the remote.
+
+For example,
+
+[source,bash]
+----
+sh interim-release.sh 1.13.0 incodehq
+----
+
+This will result in a new branch and tagged being pushed to the remote, with an appropriate version (details below).
+
+As noted in the prereqs (above), the CI server configured should then detect the new branch (or tag, if you prefer), build the framework (skipping application and architecture, as in the prerequisites) and then publish the resultant artifacts to a private Maven repo.
+
+
+
+=== Implementation details
+
+The script itself:
+
+* removes any local branches called `interim/*`
+* creates a new branch called `interim/YYYYmmDD-HHMM`
+** eg `interim/1.13.0.20160909-0758`
+* updates the version of the pom.xml to the baseline plus the date
+** eg `<version>1.13.0.20160909-0758</version>`
+* commits the changes and tags the new commit
+** eg `isis-1.13.0.20160909-0758`
+* removes any remote branches called `interim/*`
+* pushes both the branch and the tag to the remote.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-snapshots.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-snapshots.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-snapshots.adoc
new file mode 100644
index 0000000..eded8d4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-snapshots.adoc
@@ -0,0 +1,86 @@
+[[_cgcom_release-process-for-snapshots]]
+= Snapshot 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
+
+
+Snapshot releases allows the current `-SNAPSHOT` version of the `core` modules of the framework to be released to the Maven snapshot repository maintained by Apache Software Foundation.
+
+[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 framework builds ok:
+
+[source,bash]
+----
+cd core
+mvn clean install -o
+----
+
+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
+
+Deploy the framework using:
+
+[source,bsah]
+----
+cd core
+mvn -D deploy=snapshot deploy
+----
+
+This will deploy all the modules that make up a release.
+
+[TIP]
+====
+Expect this to take about 10 minutes, give or take.
+====
+
+To confirm that they are present, browse to Apache's https://repository.apache.org[Nexus repository manager] and search for "isis".
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
new file mode 100644
index 0000000..ac758da
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
@@ -0,0 +1,92 @@
+[[_cgcom_release-process-prereqs]]
+= Appendix: Release Prereqs
+: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 (appendix) describes the prerequisites for the xref:cgcom.adoc#_cgcom_release-process[release process].
+
+
+
+== Configure toolchains plugin
+
+Apache Isis releases are built using Java 7, enforced using the maven toolchains plugin.
+Ensure that Java 7 is installed and the toolchains plugin is configured, as described in the xref:__dg_building-isis_configure-maven-toolchains-plugin[contributors' guide].
+
+
+
+== 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:cgcom.adoc#_cgcom_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.exe` (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.
+
+If you use Atlassian's SourceTree, this also bundles a version of `gpg.exe` that is not compatible (in `C:\Users\xxx\AppData\Local\Atlassian\SourceTree\git_local\usr\bin`); again, move it to one side and instead use the one provided by 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>
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
new file mode 100644
index 0000000..7d92b73
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
@@ -0,0 +1,305 @@
+[[_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 xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype1] 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 archetypeVersion=1.14.0 \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp \
+ -D version=1.0-SNAPSHOT \
+ -B \
+ -o
+
+cd myapp
+mvn clean install -o
+cd webapp
+mvn jetty:run
+----
+
+Adjust the version as necessary. 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.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
new file mode 100644
index 0000000..d447116
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
@@ -0,0 +1,67 @@
+[[cgcom]]
+= Committers' 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:
+
+
+[[__cgcom]]
+== Committers' Guide
+
+This committers' guide is for committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.
+
+
+
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.
+
+The user guides available are:
+
+* xref:../ugfun/ugfun.adoc#[Fundamentals]
+* xref:../ugvw/ugvw.adoc#[Wicket viewer]
+* xref:../ugvro/ugvro.adoc#[Restful Objects viewer]
+* xref:../ugodn/ugodn.adoc#[DataNucleus object store]
+* xref:../ugsec/ugsec.adoc#[Security]
+* xref:../ugtst/ugtst.adoc#[Testing]
+* xref:../ugbtb/ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:../rgant/rgant.adoc#[Annotations]
+* xref:../rgsvc/rgsvc.adoc#[Domain Services]
+* xref:../rgcfg/rgcfg.adoc#[Configuration Properties]
+* xref:../rgcms/rgcms.adoc#[Classes, Methods and Schema]
+* xref:../rgmvn/rgmvn.adoc#[Apache Isis Maven plugin]
+* xref:../rgfis/rgfis.adoc#[Framework Internal Services]
+
+The remaining guides are:
+
+* xref:../dg/dg.adoc#[Developers' Guide] (this guide)
+* xref:../cgcom/cgcom.adoc#[Committers' Guide] (release procedures and related practices)
+
+
+
+This guide provides guidance for Apache Isis' own committers.
+
+// for some reason this doesn't seem to include:: correctly; that said, it's incomplete anyway
+//include::_cgcom_applying-patches.adoc[leveloffset=+1]
+
+include::_cgcom_merging-a-pull-request.adoc[leveloffset=+1]
+include::_cgcom_cutting-a-release.adoc[leveloffset=+1]
+include::_cgcom_verifying-releases.adoc[leveloffset=+1]
+include::_cgcom_post-release-successful.adoc[leveloffset=+1]
+include::_cgcom_post-release-unsuccessful.adoc[leveloffset=+1]
+include::_cgcom_release-process-for-snapshots.adoc[leveloffset=+1]
+include::_cgcom_release-process-for-interim-releases.adoc[leveloffset=+1]
+
+include::_cgcom_asciidoc-publish-procedure.adoc[leveloffset=+1]
+
+include::_cgcom_key-generation.adoc[leveloffset=+1]
+
+include::_cgcom_release-process-prereqs.adoc[leveloffset=+1]
+
+include::_cgcom_policies.adoc[leveloffset=+1]
+include::_cgcom_pmc-notes.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/committers/github-pr-history.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/committers/github-pr-history.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/images/committers/github-pr-history.png
new file mode 100644
index 0000000..00e1f08
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/cgcom/images/committers/github-pr-history.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/jira-create-release-notes.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/jira-create-release-notes.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/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/cgcom/images/release-process/jira-create-release-notes.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-release-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-release-1.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/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/cgcom/images/release-process/nexus-release-1.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-0.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-0.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/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/cgcom/images/release-process/nexus-staging-0.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-1.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/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/cgcom/images/release-process/nexus-staging-1.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-2.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/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/cgcom/images/release-process/nexus-staging-2.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-2a.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-2a.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/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/cgcom/images/release-process/nexus-staging-2a.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-3.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-3.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/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/cgcom/images/release-process/nexus-staging-3.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-4.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/images/release-process/nexus-staging-4.png b/adocs/documentation/src/main/asciidoc/guides/cgcom/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/cgcom/images/release-process/nexus-staging-4.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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 efd8065..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-[[dg]]
-= Developers' 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:
-
-
-[[_dg]]
-== Developers' Guide
-
-This developers' guide is for:
-
-* 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.
-
-
-
-=== Other Guides
-
-Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.
-
-The user guides available are:
-
-* xref:ugfun.adoc#[Fundamentals]
-* xref:ugvw.adoc#[Wicket viewer]
-* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugodn.adoc#[DataNucleus object store]
-* xref:ugsec.adoc#[Security]
-* xref:ugtst.adoc#[Testing]
-* xref:ugbtb.adoc#[Beyond the Basics]
-
-The reference guides are:
-
-* xref:rgant.adoc#[Annotations]
-* xref:rgsvc.adoc#[Domain Services]
-* xref:rgcfg.adoc#[Configuration Properties]
-* xref:rgcms.adoc#[Classes, Methods and Schema]
-* xref:rgmvn.adoc#[Apache Isis Maven plugin]
-* xref:rgfis.adoc#[Framework Internal Services]
-
-The remaining guides are:
-
-* xref:dg.adoc#[Developers' Guide] (this guide)
-* xref:cgcom.adoc#[Committers' Guide] (release procedures and related practices)
-
-
-
-
-include::_dg_ide.adoc[leveloffset=+1]
-
-include::_dg_building-isis.adoc[leveloffset=+1]
-
-include::_dg_asciidoc.adoc[leveloffset=+1]
-
-include::_dg_contributing.adoc[leveloffset=+1]
-
-include::_dg_git-cookbook.adoc[leveloffset=+1]
-include::_dg_working-with-many-repos.adoc[leveloffset=+1]
-include::_dg_asciidoc-syntax.adoc[leveloffset=+1]
-include::_dg_asciidoc-templates.adoc[leveloffset=+1]
-include::_dg_project-lombok.adoc[leveloffset=+1]
-include::_dg_agilej.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc
new file mode 100644
index 0000000..a951fa4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_agilej.adoc
@@ -0,0 +1,55 @@
+[[_dg_agilej]]
+= Appendix: 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. AgileJ has however provided a complimentary copy of its software to Apache Isis committers.
+====
+
+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/2669a971/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc
new file mode 100644
index 0000000..bf48cd2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc
@@ -0,0 +1,985 @@
+[[_dg_asciidoc-syntax]]
+= Appendix: Asciidoc Syntax
+: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 main syntax conventions when writing Asciidoctor/Asciidoc.
+
+For more info, see:
+
+* link:_resources/asciidoc-syntax-quick-reference.pdf[asciidoc-syntax-quick-reference.pdf]
+
+* link:_resources/asciidoc-writers-guide.pdf[asciidoc-writers-guide.pdf]
+
+* link:https://powerman.name/doc/asciidoc[online cheat sheet]
+
+* link:http://asciidoctor.org/docs/user-manual/[asciidoctor online user manual]
+
+* link:http://www.methods.co.nz/asciidoc/userguide.html[asciidoc online user manual]
+
+
+[[__markup-docs_asciidoc_headings]]
+== Headings
+
+The number of preceding `=` signs indicates the heading level.
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Meaning
+
+|....
+= Level 1
+....
+
+|There can only be one level 1 per .adoc (at the very top).
+
+The paragraph immediately following the heading is the "preamble", and is rendered in a larger font.
+It's therefore a good place to summarize the content of the document.
+
+|....
+== Level 2
+....
+
+|Level 2
+
+|....
+=== Level 3
+....
+
+|Level 3
+
+|....
+==== Level 4
+....
+|Level 4
+
+|===
+
+
+[[__markup-docs_asciidoc_paragraphs]]
+== Paragraphs
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Example
+
+|....
+Paragraphs are separated by one or more blank lines.
+
+So, this is a separate paragraph.
+....
+
+|Paragraphs are separated by one or more blank lines.
+
+So, this is a separate paragraph.
+
+
+|....
+All consecutive sentences are rendered in the same paragraph.
+This is another sentence in the para.
+And another one.
+Yet another.
+....
+
+|Sentences without a blank line are in the same paragraph.
+Don't worry about word wrapping, just start the next sentence on the next line.
+
+|===
+
+
+In general, there's no need to indent paragraphs; keep things left-aligned.
+Let the markup specify the logical indentation.
+
+.Start each sentence on a new line
+****
+Don't worry about wrapping sentences at 80 characters, just start each new sentence on a new line.
+Asciidoc will take care of the rendering.
+
+This simple tip has a number of other benefits:
+
+1. when the document is edited (eg correct a typo or insert a missing word), then only a single line in the file is changed. +
++
+This will reduce change of merge conflicts, too.
+
+2. You can easily see if a sentence is too long, and should be split
+
+3. You can easily see if all sentences are the same length: good writing should vary the length of sentences
+
+4. You can easily see if successive sentences start with the same phrase (that might be a good thing, or a bad thing, depending).
+
+****
+
+
+[[__markup-docs_asciidoc_bulleted-lists]]
+== Bulleted lists
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Example
+
+|....
+The blank line after this para is required:
+
+* Bullet 1 +
++
+Indented paragraph (note the '+' to to chain this para with the bullet)
+
+* Bullet 2
+
+** Child bullets +
++
+More indenting
+
+** Another child bullet
+
+* Bullet 3
+....
+
+|The blank line after this para is required:
+
+* Bullet 1 +
++
+Indented paragraph (note the '+' to chain this para with the bullet)
+
+* Bullet 2
+
+** Child bullets +
++
+More indenting
+
+** Another child bullet
+
+* Bullet 3
+
+|===
+
+
+[[__markup-docs_asciidoc_numbered-lists]]
+== Numbered lists
+
+There's no need to keep track of numbers, just use '1' or 'a' etc:
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Example
+
+|....
+The blank line after this para is required:
+
+1. Bullet 1 +
++
+Indented paragraph
+
+2. Bullet 2
+
+a. Child bullets +
++
+More indenting
+
+b. Another child bullet
+
+3. Bullet 3
+....
+
+|The blank line after this para is required:
+
+1. Bullet 1 +
++
+Indented paragraph
+
+2. Bullet 2
+
+a. Child bullets +
++
+More indenting
+
+b. Another child bullet
+
+3. Bullet 3
+
+|===
+
+While it isn't necessary to maintain the ordering manually (could just use '1' for all bullets), this does generate warnings when the document is built.
+
+
+[[__markup-docs_asciidoc_links-and-xrefs]]
+== Links and Cross-references
+
+[cols="3a,2a,3a", options="header"]
+|===
+
+| Syntax
+| Example
+| Purpose
+
+|....
+link:http://ciserver:8080[CI Server]
+....
+|link:http://ciserver:8080[CI Server]
+|Link to an external hyperlink
+
+|....
+link:http://ciserver:8080[CI Server^]
+....
+|link:http://ciserver:8080[CI Server^]
+|Link to an external hyperlink, with `target=blank`
+
+|....
+xref:_markup-docs_background[background]
+....
+|xref:_markup-docs_background[background]
+|Cross-reference to section in same asciidoc document
+
+|....
+xref:../../setting-up/concepts/concepts.adoc#[concepts]
+....
+|xref:../../setting-up/concepts/concepts.adoc#[concepts]
+|Cross-reference to top-level of different asciidoc document
+
+|....
+xref:../../setting-up/concepts/concepts.adoc#_concepts_ci-as-a-service[CI as a service]
+....
+|xref:../../setting-up/concepts/concepts.adoc#_concepts_ci-as-a-service[CI as a service]
+|Cross-reference to section within different asciidoc document
+
+|===
+
+
+
+[[__markup-docs_asciidoc_tables]]
+== Tables
+
+....
+.Some table
+[cols="3a,2a", options="header"]
+|===
+
+| Header col 1
+| Header col 2
+
+| Row 1 col 1
+| Row 1 col 2
+
+| Row 2 col 1
+| Row 2 col 2
+
+|===
+....
+
+renders as:
+
+.Some table
+[cols="3a,2a", options="header"]
+|===
+
+| Header col 1
+| Header col 2
+
+| Row 1 col 1
+| Row 1 col 2
+
+| Row 2 col 1
+| Row 2 col 2
+
+|===
+
+where:
+
+* the `cols` attribute says how many columns there are and their respective widths.
+* the "a" suffix indicates that the contents is parsed as Asciidoc
+
+=== Column Attributes
+
+Other options are (link:http://mrhaki.blogspot.co.uk/2014/11/awesome-asciidoctor-styling-columns-and.html[credit]):
+
+* e: emphasized
+* a: Asciidoc markup
+* m: monospace
+* h: header style, all column values are styled as header
+* s: strong
+* l: literal, text is shown in monospace font and line breaks are kept
+* d: default
+* v: verse, keeps line breaks
+
+For example:
+
+....
+.Table with column style e,a,m
+[cols="e,a,m"]
+|===
+| Emphasized (e) | Asciidoc (a) | Monospaced (m)
+
+| Asciidoctor
+| NOTE: *Awesome* way to write documentation
+| It is just code
+
+|===
+....
+
+renders as
+
+.Table with column style e,a,m
+[cols="e,a,m"]
+|===
+| Emphasized (e) | Asciidoc (a) | Monospaced (m)
+
+| Asciidoctor
+| NOTE: *Awesome* way to write documentation
+| It is just code
+
+|===
+
+and:
+
+....
+.Table with column style h,s,l
+[cols="h,s,l"]
+|===
+| Header (h) | Strong (s) | Literal (l)
+
+| Asciidoctor
+| Awesome way to write documentation
+| It is
+just code
+
+|===
+....
+
+renders as
+
+.Table with column style h,s,l
+[cols="h,s,l"]
+|===
+| Header (h) | Strong (s) | Literal (l)
+
+| Asciidoctor
+| Awesome way to write documentation
+| It is
+just code
+
+|===
+
+and:
+
+....
+.Table with column style d,v
+[cols="d,v"]
+|===
+| Default (d) | Verse (v)
+
+| Asciidoctor
+| Awesome way
+to write
+documentation
+
+|===
+....
+
+renders as
+
+.Table with column style d,v
+[cols="d,v"]
+|===
+| Default (d) | Verse (v)
+
+| Asciidoctor
+| Awesome way
+to write
+documentation
+
+|===
+
+
+=== Column Alignment
+
+This can be combined with alignment markers (link:http://mrhaki.blogspot.co.uk/2014/11/awesome-asciidoctor-table-column-and.html[credit]):
+
+* <: top align values (default)
+* >: bottom align values
+* ^: center values
+
+For example:
+
+....
+[cols="^.>,<.<,>.^", options="header"]
+|===
+
+| Name
+| Description
+| Version
+
+| Asciidoctor
+| Awesome way to write documentation
+| 1.5.0
+|===
+....
+
+renders as:
+
+[cols="^.>,<.<,>.^", options="header"]
+|===
+
+| Name
+| Description
+| Version
+
+| Asciidoctor
+| Awesome way to write documentation
+| 1.5.0
+|===
+
+where:
+
+* the first column is centered and bottom aligned,
+* the second column is left and top aligned and
+* the third column is right aligned and centered vertically.
+
+
+=== Column/Row Spanning
+
+We can also have columns or rows spanning multiple cells (link:http://mrhaki.blogspot.co.uk/2014/12/awesome-asciidoctor-span-cell-over-rows.html[credit]):
+
+For example:
+
+....
+.Cell spans columns
+|===
+| Name | Description
+
+| Asciidoctor
+| Awesome way to write documentation
+
+2+| The statements above say it all
+
+|===
+....
+
+renders as:
+
+
+.Cell spans columns
+|===
+| Name | Description
+
+| Asciidoctor
+| Awesome way to write documentation
+
+2+| The statements above say it all
+
+|===
+
+The `N+` sign notation tells Asciidoctor to span this cell over N columns.
+
+
+while:
+
+....
+.Cell spans rows
+|===
+| Name | Description
+
+.2+| Asciidoctor
+| Awesome way to write documentation
+
+| Works on the JVM
+
+|===
+....
+
+renders as:
+
+
+.Cell spans rows
+|===
+| Name | Description
+
+.2+| Asciidoctor
+| Awesome way to write documentation
+
+| Works on the JVM
+
+|===
+
+The `.N+` notation tells Asciidoctor to span this cell over N rows.
+
+
+and:
+
+....
+.Cell spans both rows and columns
+|===
+
+| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3
+
+2.2+| Cell spans 2 cols, 2 rows
+| Row 2, Col 3
+| Row 3, Col 3
+
+|===
+....
+
+renders as:
+
+.Cell spans both rows and columns
+|===
+
+| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3
+
+2.2+| Cell spans 2 cols, 2 rows
+| Row 2, Col 3
+| Row 3, Col 3
+
+|===
+
+The `N.M+` notation tells Asciidoctor to span this cell over N columns and M rows.
+
+
+
+[[__markup-docs_asciidoc_admonitions]]
+== Admonitions
+
+Callout or highlight content of particular note.
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Example
+
+|....
+NOTE: the entire note must be a single sentence.
+....
+
+|NOTE: the entire note must be a single sentence.
+
+|....
+[NOTE]
+====
+the note is multiple paragraphs, and can have all the usual styling,
+* eg bullet points:
+* etc etc
+====
+....
+
+|
+[NOTE]
+====
+the note is multiple paragraphs, and can have all the usual styling,
+
+* eg bullet points:
+* etc etc
+====
+
+|....
+[TIP]
+====
+Here's something worth knowing...
+====
+....
+
+|
+[TIP]
+====
+Here's something worth knowing...
+====
+
+
+|....
+[WARNING]
+====
+Be careful...
+====
+....
+
+|
+[WARNING]
+====
+Be careful...
+====
+
+|....
+[IMPORTANT]
+====
+Don't forget...
+====
+....
+
+|
+[IMPORTANT]
+====
+Don't forget...
+====
+
+|===
+
+
+[[__markup-docs_asciidoc_source-code]]
+== Source code
+
+Use `[source]` macro to specify source content:
+
+....
+[source,powershell]
+----
+get-command -module BomiArtifact
+----
+....
+
+will render as:
+
+[source,powershell]
+----
+get-command -module BomiArtifact
+----
+
+Some languages support syntax highlighting.
+For example:
+
+....
+[source,java]
+----
+public class SomeClass extends SomeOtherClass {
+ ...
+}
+----
+....
+
+will render as:
+
+[source,java]
+----
+public class SomeClass extends SomeOtherClass {
+ ...
+}
+----
+
+Callouts can also be added using an appropriate comment syntax.
+For example:
+
+....
+[source,java]
+----
+public class SomeClass
+ extends SomeOtherClass { // \<1>
+ public static void main(String[] args) { // \<2>
+ ...
+ }
+}
+----
+<1> inherits from `SomeOtherClass`
+<2> entry point into the program
+....
+
+will render as:
+
+[source,java]
+----
+public class SomeClass
+ extends SomeOtherClass { //<1>
+ public static void main(String[] args) { //<2>
+ ...
+ }
+}
+----
+<1> inherits from `SomeOtherClass`
+<2> entry point into the program
+
+
+and
+
+....
+[source,xml]
+----
+<a>
+ <b c="foo"> \<!--1-->
+</a>
+----
+<1> some comment
+....
+
+renders as:
+
+[source,xml]
+----
+<a>
+ <b c="foo"> <!--1-->
+</a>
+----
+<1> some comment
+
+
+It's also possible to include source code snippets; see the guides linked previously
+
+
+[[__markup-docs_asciidoc_images]]
+== Images
+
+Use the `image:` macro to reference images.
+For example:
+
+....
+image:_images/vscode.png[]
+....
+
+will render as:
+
+image:_images/vscode.png[]
+
+
+to make the image clickable, add in the `link` attribute:
+
+....
+image:_images/vscode.png[link="_images/vscode.png"]
+....
+
+will render as:
+
+image:_images/vscode.png[link="_images/vscode.png"]
+
+
+to make the image clickable, add in the `link` attribute:
+
+
+It's also possible to specify the width using `scaledwidth` (for PDF/HTML) or `width` and `height` (for HTML only).
+
+
+
+[[__markup-docs_asciidoc_child-documents]]
+== Child Documents
+
+
+Use the `include:` macro to break up a document into multiple sections.
+
+For example, the xref:../../setting-up/concepts/concepts.adoc#[concepts] document is broken into several files:
+
+....
+concepts.adoc
+_concepts_why-a-new-platform.adoc
+_concepts_ci-as-a-service.adoc
+_concepts_git-intro.adoc
+....
+
+and so on.
+
+These are included using:
+
+[source,asciidoc]
+----
+\include::_concepts_why-a-new-platform.adoc[leveloffset=+1]
+\include::_concepts_ci-as-a-service.adoc[leveloffset=+1]
+\include::_concepts_git-intro.adoc[leveloffset=+1]
+----
+
+The `leveloffset=+1` means that each included file's heading levels are automatically adjusted.
+The net effect is that all documents can and should use heading 1 as their top-level.
+
+Child documents should have '_' as prefix.
+This ensures that they are ignored by the build; only .html and PDF files are created for the top-level parent documents.
+
+The CI/documentation platform also supports the "Improve this doc" button, allowing any document to be edited via the TFS portal; very useful for small fixes.
+To make this work, it relies upon the following naming conventions:
+
+* every document should have an id anchor for its level heading corresponding to its file name
+* every child document's name should be an '_ followed by the name of its parent.
+
+For example, `concepts.adoc` is:
+
+[source,asciidoc]
+----
+[[concepts]]
+= Concepts
+...
+----
+
+while its child document `_concepts_why-a-new-platform.adoc` starts with:
+
+[source,asciidoc]
+----
+[[_concepts_why-a-new-platform]]
+= Why a new platform?
+...
+----
+
+In general, we 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
+----
+
+
+
+[[__markup-docs_asciidoc_metadata]]
+== Metadata
+
+The top-level document must include the `_basedir` attribute; this points to the parent directory `src/main/asciidoc`.
+This attribute is set immediately after the top-level heading.
+
+In addition, the `:toc:` adds a table of contents.
+
+For example, the `setting-up/concepts/concepts.adoc` file starts:
+
+[source,asciidoc]
+----
+[[concepts]]
+= Concepts
+:_basedir: ../../
+:toc: right
+...
+----
+
+
+
+[[__markup-docs_asciidoc_uml]]
+== UML diagrams
+
+Asciidoctor includes support for the link:http://plantuml.com/[plantuml], allowing simple UML diagrams to be easily sketched.
+
+For example:
+
+....
+[plantuml,_images/plantuml-demo,png]
+--
+class Car
+
+Driver - Car : drives >
+Car *- Wheel : have 4 >
+Car -- Person : < owns
+--
+....
+
+renders as:
+
+[plantuml,_images/plantuml-demo,png]
+--
+class Car
+
+Driver - Car : drives >
+Car *- Wheel : have 4 >
+Car -- Person : < owns
+--
+
+
+
+
+[[__markup-docs_asciidoc_ditaa]]
+== Ditaa diagrams
+
+Asciidoctor includes support for the link:http://ditaa.sourceforge.net/[ditaa], allowing boxes-and-lines diagrams to be easily sketched.
+
+For example:
+
+....
+[ditaa,_images/ditaa-demo,png]
+----
+ +--------+ +-------+ +-------+
+ | | --+ ditaa +--> | |
+ | Text | +-------+ |diagram|
+ |Document| |!magic!| | |
+ | {d}| | | | |
+ +---+----+ +-------+ +-------+
+ : ^
+ | Lots of work |
+ +-------------------------+
+----
+....
+
+renders as:
+
+[ditaa,_images/ditaa-demo,png]
+----
+ +--------+ +-------+ +-------+
+ | | --+ ditaa +--> | |
+ | Text | +-------+ |diagram|
+ |Document| |!magic!| | |
+ | {d}| | | | |
+ +---+----+ +-------+ +-------+
+ : ^
+ | Lots of work |
+ +-------------------------+
+----
+
+
+[[__markup-docs_asciidoc_graphviz]]
+== Graphviz diagrams
+
+
+Asciidoctor includes support for the link:http://ditaa.sourceforge.net/[ditaa], allowing boxes-and-lines diagrams to be easily sketched.
+
+For example:
+
+....
+[graphviz,_images/graphviz-demo,png]
+----
+digraph automata_0 {
+ size ="8.5, 11";
+ node [shape = circle];
+ 0 [ style = filled, color=lightgrey ];
+ 2 [ shape = doublecircle ];
+ 0 -> 2 [ label = "a " ];
+ 0 -> 1 [ label = "other " ];
+ 1 -> 2 [ label = "a " ];
+ 1 -> 1 [ label = "other " ];
+ 2 -> 2 [ label = "a " ];
+ 2 -> 1 [ label = "other " ];
+ "Machine: a" [ shape = plaintext ];
+}
+----
+....
+
+renders as:
+
+[graphviz,_images/graphviz-demo,png]
+----
+digraph automata_0 {
+ size ="8.5, 11";
+ node [shape = circle];
+ 0 [ style = filled, color=lightgrey ];
+ 2 [ shape = doublecircle ];
+ 0 -> 2 [ label = "a " ];
+ 0 -> 1 [ label = "other " ];
+ 1 -> 2 [ label = "a " ];
+ 1 -> 1 [ label = "other " ];
+ 2 -> 2 [ label = "a " ];
+ 2 -> 1 [ label = "other " ];
+ "Machine: a" [ shape = plaintext ];
+}
+----
+
+[IMPORTANT]
+====
+This requires graphviz to be installed and the `dot.exe` on the PATH.
+Alternatively, specify the location, eg using:
+
+....
+:graphvizdot: c:\Program Files (x86)\Graphviz2.38\bin\dot.exe
+....
+====
+