You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/07/10 09:41:37 UTC
[08/10] isis git commit: ISIS-1133: pulling together the contributors
guide.
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
new file mode 100644
index 0000000..74f5cda
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
@@ -0,0 +1,145 @@
+[[_cg_committers_verifying-releases]]
+= Verifying Releases
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+Whenever a committer announces a vote on a release on the link:../support.html[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release. Anyone else can also vote, but only members of the Apache Isis PMC's vote are binding.
+
+This page provides some guidance on what a voter is expected to verify before casting their vote.
+
+Per this http://www.apache.org/dev/release.html[ASF documentation], the legal requirements for an ASF release are:
+
+* a source zip file + corresponding signature (signed by the release manager, which is in the ASF web of trust and in our KEYS file)
+* all source files have the Apache license (this is ensured by the running of the rat plugin prior to release; you could run it on the unzipped source)
+* all dependencies are appropriately licensed; see the `DEPENDENCIES` file which is automatically generated from the POMs plus the supplemental-models.xml file
+
+Note that the binaries are _not_ an ASF release, they merely exist on the Maven central repo as a convenience. That said, you might also want to verify the release by pulling the binaries from the Maven staging repository. Details of how to do this are also documented below.
+
+
+
+== Prerequisites
+
+To verify the source ZIP files, you will need to have imported the public keys used for signing Apache Isis releases. These can be downloaded from the root of the Apache Isis source tree.
+
+Since the Apache Isis source is mirrored on github.com, you can just use:
+
+[source,bash]
+----
+curl http://www.apache.org/dist/isis/KEYS > /tmp/KEYS
+gpg --import /tmp/KEYS
+----
+
+
+
+
+== Verifying the source release artifacts
+
+
+[NOTE]
+====
+Note: to automate this next stage, there is also a xref:cg.adoc#_cg_committers_verifying-releases-using-a-script[script] available; but read what follows first before using the script.
+====
+
+
+Download both the ZIP and .ASC files from the location specified in the voting email. To verify that the signature is correct, use:
+
+[source,bash]
+----
+gpg --verify isis-x.y.z.zip.asc isis-x.y.z.zip
+----
+
+
+
+
+== Building the source release artifacts
+
+Assuming the ZIP file verifies, it should be unpacked, and then the artifact built from source.
+
+First, delete all Isis artifacts from your local Maven repo:
+
+[source,bash]
+----
+rm -rf ~/.m2/repository/org/apache/isis
+----
+
+
+To build Apache Isis core, first download any dependencies:
+
+[source]
+----
+mvn dependency:go-offline
+----
+
+Check that no Isis artifacts have yet been downloaded, ie there is no `~/.m2/org/repository/org/apache/isis` directory. If there are, it could indicate that the release being verified incorrectly references previous versions of Apache Isis core.
+
+Assuming all is ok, build using the `-o` offline flag:
+
+[source]
+----
+mvn clean install -o
+----
+
+Confirm that the versions of the Isis artifacts now cached in your local repository are correct.
+
+
+
+
+
+== Verifying the binary release artifacts (using the Maven staging repository)
+
+If you wish, you can verify the binary releases by configuring your local Maven install to point to the Maven Maven staging repository (or repositories) and then using them, eg to run the link:../intro/getting-started/simpleapp-archetype.html[simpleapp archetype] and running the resultant app.
+
+Configuring your local Maven install amounts to updating the `~/.m2/settings.xml` file:
+
+[source,xml]
+----
+<profiles>
+ <profile>
+ <id>verify-isis</id>
+ <repositories>
+ <repository>
+ <id>isis-core-staging</id>
+ <name>Isis Core Staging</name>
+ <releases>
+ <enabled>true</enabled>
+ <updatePolicy>always</updatePolicy>
+ <checksumPolicy>warn</checksumPolicy>
+ </releases>
+ <url>http://repository.apache.org/content/repositories/orgapacheisis-10xx</url>
+ <layout>default</layout>
+ </repository>
+ ...
+ </repositories>
+ </profile>
+ ...
+</profiles>
+<activeProfiles>
+ <activeProfile>verify-isis</activeProfile>
+ ...
+</activeProfiles>
+----
+
+where the repository URL is as provided in the VOTE email. If there is more than one repository (as is sometimes the case if multiple components have been released), then repeat the <repository> section for each.
+
+Once the vote has completed, the staging repositories will be removed and so you should deactive the profile (comment out the `<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.
+
+
+
+
+
+== Using the Creadur Tools
+
+The http://creadur.apache.org[Apache Creadur] project exists to provide a set of tools to ensure compliance with Apache's licensing standards. The main release auditing tool, http://creadur.apache.org/rat[Apache RAT], is used in the preparation of the release (as documented link:release-process.html[here]). Creadur's remaining tools are to support the verification process.
+
+At the time of writing, these additional tools are quite young and haven't been formally released; so to use them will take a little bit of work. See link:verifying-releases-using-creadur-tools.html[here] for more details.
+
+
+
+
+== Casting a Vote
+
+When you have made the above checks (and any other checks you think may be relevant), cast your vote by replying to the email thread on the mailing list. If you are casting `-1`, please provide details of the problem(s) you have found.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
new file mode 100644
index 0000000..b0c0aba
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_contributing.adoc
@@ -0,0 +1,255 @@
+[[_cg_contributing]]
+= Contributing
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+This page explains how you can contribute to Apache Isis. You'll probably also want xref:cg.adoc#_cg_ide[set up your IDE] and learn xref:cg.adoc#_cg_building-isis[how to build Apache Isis].
+
+Thanks for considering to help out, your contributions are appreciated!
+
+
+== Recommended Workflow (github)
+
+Apache Isis' source code is hosted in an Apache git repo (https://git-wip-us.apache.org/repos/asf/isis.git[https], http://git-wip-us.apache.org/repos/asf/isis.git[http]), with a clone on github (https://github.com/apache/isis.git[https], or ssh: `git@github.com:apache/isis.git`.
+
+As you might imagine, only committers are permitted to push changes to the central git repo. As a contributor, we recommend that you fork the https://github.com/apache/isis.git[apache/isis] repo in github, and then use your fork as a way of publishing your patches for the Apache Isis committers to apply.
+
+The diagram below illustrates the process:
+
+image::{_imagesdir}contributing/git-workflow.png[width="600px",link="{_imagesdir}contributing/git-workflow.png"]
+
+
+That is:
+
+. as a one-time activity, you fork the https://github.com/apache/isis.git[github.com/apache/isis] repo into your own fork on github.com
+. as a one-time activity, you clone your fork to your local computer
+. you set the https://github.com/apache/isis.git[github.com/apache/isis] as your upstream branch; this will allow you to keep your local clone up-to-date with new commits
+* note the asymmetry here: the `upstream` repo (the Apache github repo) is *not* the same as the `origin` repo (your fork).
+. you work on your changes locally; when done, you push them to your github fork
+. to contribute back a change, raise a https://issues.apache.org/jira/browse/ISIS[JIRA] ticket, and ensure your commit message is in the form: `ISIS-nnnn: ...` so that changes can be tracked (more discussion on this point below). In any case, before you decide to start hacking with Apache Isis, it's always worth creating a ticket in JIRA and then have a discussion about it on the http://isis.apache.org/support.html[mailing lists].
+. Use github to raise a https://help.github.com/articles/using-pull-requests/[pull request] for your feature
+. An Apache Isis committer will review your change, and apply it if suitable.
+
+
+
+
+== Alternative Workflow (JIRA patches)
+
+As an alternative, you may decide to clone directly from https://github.com/apache/isis.git[github.com/apache/isis] rather than create your own fork:
+
+
+image::{_imagesdir}contributing/git-workflow-2.png[width="600px",link="{_imagesdir}contributing/git-workflow-2.png"]
+
+In this case your `upstream` repo is the same as your `origin` repo, which might seem more straightforward. On the other hand, if you go this route then you'll need create patches locally and attach them to the JIRA ticket.
+
+For the Apache Isis committers it really doesn't matter which route you take, so go with whatever's most comfortable.
+
+
+
+
+== Setting up your fork/clone
+
+If you choose to create your own fork then you'll need an account on https://github.com[github.com]. You then fork simply by pressing the "Fork" button:
+
+
+image::{_imagesdir}contributing/github-forking.png[width="600px",link="{_imagesdir}contributing/github-forking.png"]
+
+
+
+An account isn't needed if you just clone straight from the http://github.com/apache/isis[github.com/apache/isis].
+
+Whether you've forked or not, you then need to clone the repo onto your computer. Github makes this very easy to do:
+
+* for Windows users, we suggest you use github's 'Clone in Windows' feature
+* for Mac/Linux users, create a clone from the command line:
+
+Again, the info is easily found in the github page:
+
+
+
+image::{_imagesdir}contributing/github-cloning.png[width="600px",link="{_imagesdir}contributing/github-cloning.png"]
+
+If you've created your own fork, then you need to add the `upstream` remote to the https://github.com/apache/isis[github.com/apache/isis]. This remote is traditionally called `upstream`. You should then arrange for your `master` branch to track the `upstream/master` remote branch:
+
+If you didn't create your own fork, you can omit the above step. Either way around, you can now fetch new commits using simply:
+
+
+[source,bash]
+----
+git fetch
+----
+
+
+For more info on tracking branches http://git-scm.com/book/en/Git-Branching-Remote-Branches[here] and http://gitready.com/beginner/2009/03/09/remote-tracking-branches.html[here].
+
+
+
+
+
+== Commit messages
+
+Although with git your commits are always performed on your local repo, those commit messages become public when the patch is applied by an Apache Isis committer. You should take time to write a meaningful commit message that helps explain what the patch refers to; if you don't then there's a chance that your patch may be rejected and not applied. No-one likes hard work to go to waste!
+
+We therefore recommend that your commit messages are as follows [1]:
+
+[source,other]
+----
+ISIS-999: Make the example in CONTRIBUTING imperative and concrete
+
+Without this patch applied the example commit message in the CONTRIBUTING
+document is not a concrete example. This is a problem because the
+contributor is left to imagine what the commit message should look like
+based on a description rather than an example. This patch fixes the
+problem by making the example concrete and imperative.
+
+The first line is a real life imperative statement with a ticket number
+from our issue tracker. The body describes the behavior without the patch,
+why this is a problem, and how the patch fixes the problem when applied.
+----
+
+
+
+Once your git repo is setup, the next thing you'll most likely want to do is to setup your development environment. See link:development-environment.html[here] for more details.
+
+
+
+
+
+== Creating the patch file
+
+If you are working without a github fork of Apache Isis, then you can create the patches from your own local git repository.
+
+As per http://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit[this stackoverflow question], create the patch using `git format-patch`:
+
+[source,bash]
+----
+git format-patch -10 HEAD --stdout > 0001-last-10-commits.patch
+----
+
+Here `-10` is the last 10 commits you have done. You need to change that integer according to the commits you need to apply into the patch.
+
+
+
+
+== Sample Contribution Workflow
+
+Assuming you're development environment is all setup, let's walk through how you might make contribute a patch. In this example, suppose that you've decided to work on JIRA ticket #123, an enhancement to support Blob/Clob datatypes.
+
+=== Update your master branch
+
+The first thing to do is to make sure your local clone is up-to-date. We do this by retrieving new commits from upstream repo and then merging them as a fast-forward into your local branch.
+
+Irrespective of whether you are using a github fork, the upstream for your local `master` branch will be tracking the appropriate remote's `master` branch. So n either case, the same commands work:
+
+Alternatively, you can combine the `git fetch` and `git merge` and just use `git pull`:
+<pre>
+git checkout master
+git pull –ff-only
+</pre>
+
+If the `merge` or `pull` fails, it means that you must have made commits and there have been changes meanwhile on the remote `master`'s branch. You can use `gitk --all` to confirm. If this fails, see our link:git-cookbook.html[git cookbook] page for a procedure to retrospectively sort out this situation.
+
+
+
+=== Create a topic branch
+
+We recommend you name topic branches by the JIRA ticket, ie <tt>ISIS-nnn-description</tt>. So let's create a new branch based off `master` and call it "ISIS-123-blobs"
+
+You can confirm the branch is there and is your new `HEAD` using either `gitk --all`. Alternatively, use the command line:
+
+
+[source,bash]
+----
+$ git checkout -b ISIS-123-blobs
+----
+
+
+The command line prompt should also indicate you are on a branch, isolated from any changes that might happen on the `master` branch.
+
+=== Make File Changes and Commit
+
+Next, make changes to your files using the usual commands (see also our xref:cg.adoc#_cg_git-cookbook[git cookbook] section):
+
+* `git add`
+* `git mv`
+* `git rm`
+* `git commit`
+* `git status`
+
+and so on.
+
+Continue this way until happy with the change. Remember to run all your tests on the topic branch (including a full `mvn clean install`).
+
+
+
+
+=== Rebasing with `master`
+
+Before you can share your change, you should rebase (in other words replay) your changes on top of the `master` branch.
+
+The first thing to do is to pull down any changes made in upstream remote's `master` since you started your topic branch:
+
+These are the same commands that you would have run before you created your topic branch. If you use `gitk --all`, there's a good chance that new commits have come in.
+
+Next, we reintegrate our topic branch by rebasing onto `master`:
+<pre>
+git checkout ISIS-123-blobs
+git rebase master
+</pre>
+
+This takes all of the commits in your branch, and applies them on top of the new `master` branch. When your change is eventually integrated back in, it will result in a nice clear linear history on the public repo.
+
+If the rebase fails because of a conflict, then you'll be dumped into REBASE mode. Edit the file that has the conflict, and make the appropriate edits. Once done:
+
+Once the rebase has completed, re-run your tests to confirm that everything is still good.
+
+
+
+=== Raising a pull request
+
+If you have your own fork, you can now simply push the changes you've made locally to your fork:
+
+This will create a corresponding branch in the remote github repo. If you use `gitk --all`, you'll also see a `remotes/origin/ISIS-123-blobs` branch.
+
+Then, use github to raise a https://help.github.com/articles/using-pull-requests/[pull request]. Pull requests sent to the Apache GitHub repositories will forward a pull request e-mail to the link:../support.html[dev mailing list]. You'll probably want to sign up to the dev mailing list first before issuing your first pull request (though that isn't mandatory).
+
+The process to raise the pull request, broadly speaking:
+
+* Open a web browser to your github fork of isis
+* Select your topic branch (pushed in the previous step) so that the pull request references the topic branch.
+* Click the `Pull Request` button.
+* Check that the Apache Isis mailing list email came through.
+
+
+
+== If your pull request is accepted
+
+To double check that your pull request is accepted, update your `master` branch from the `upstream` remote:
+
+You can then use `gitk --all` (or `git log` if you prefer the command line) to check your contribution has been added.
+
+You can now delete your topic branch and remove the branch in your github:
+
+Finally, you might want to push the latest changes in master back up to your github fork. If so, use:
+
+
+
+=== If your pull request is rejected
+
+If your pull request is rejected, then you'll need to update your branch from the main repository and then address the rejection reason.
+
+You'll probably also want to remove the remote branch on github:
+
+[source,bash]
+----
+git push origin –delete ISIS-123-blobs
+----
+
+
+… and continue as before until you are ready to resubmit your change.
+
+[1] inspiration for the recommended commit format comes from the https://github.com/puppetlabs/puppet[puppet] project's https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md[contributing] page.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
new file mode 100644
index 0000000..70b6870
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_git-cookbook.adoc
@@ -0,0 +1,258 @@
+[[_cg_git-cookbook]]
+= Appendix: Git Cookbook
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+This section describes the commands often used while working with git. In addition to these basic commands, please make sure you have read:
+
+* xref:cg.adoc#_cg_building-isis[building Apache Isis]
+* xref:cg.adoc#_cg_git-policy[Git policy]
+* xref:cg.adoc#_cg_contributing[Contributing]
+
+
+
+
+== Modifying existing files
+
+To modify existing files:
+
+[source,bash]
+----
+git add filename
+git commit -m "ISIS-nnn: yada yada"
+----
+
+The `git add` command adds the changes to the file(s) to the git index (aka staging area). If you were to make subsequent changes to the file these would not be committed.
+
+The `git commit` takes all the staged changes and commits them locally. Note that these changes are not shared public with Apache Isis' central git repo.
+
+You can combine these two commands using `-am` flag to git commit:
+
+[source,bash]
+----
+git commit -am "ISIS-nnn: yada yada"
+----
+
+
+
+
+== Adding new files
+
+To add a new file:
+
+[source,bash]
+----
+git add .
+git commit -m "ISIS-nnn: yada yada"
+----
+
+
+Note that this sequence of commands is identical to modifying an existing file. However, it isn't possible to combine the two steps using `git commit -am`; the `git add` is always needed when adding new files to the repo.
+
+
+
+
+== Deleting files
+
+To delete a file:
+
+[source,bash]
+----
+git rm filename
+git commit -m "ISIS-nnn: yada yada"
+----
+
+
+
+== Renaming or moving files
+
+To rename or move a file:
+
+
+[source,bash]
+----
+git mv <i>filename</i> <i>newfilename</i>
+git commit -m "ISIS-nnn: yada yada"
+----
+
+
+
+
+== Common Workflows
+
+The xref:cg.adoc#_cg_contributing[contributing] page describes the workflow for non-committers. The xref:cg.adoc#_cg_git-policy[Git policy] page describes a workflow for Apache Isis **committers**.
+
+
+
+
+
+== Backing up a local branch
+
+If committing to a local branch, the changes are still just that: local, and run risk of a disk failure or other disaster.
+
+To create a new, similarly named branch on the central repo, use:
+
+[source,bash]
+----
+git push -u origin <i>branchname</i>
+----
+
+Using `gitk --all` will show you this new branch, named *origin/branchname*.
+
+Thereafter, you can push subsequent commits using simply:
+
+[source,bash]
+----
+git push
+----
+
+
+Doing this also allows others to collaborate on this branch, just as they would for `master`.
+
+When, eventually, you have reintegrated this branch, you can delete the remote branch using:
+
+[source,bash]
+----
+git push origin --delete <i>branchname</i>
+----
+
+
+For more detail, see these blogs/posts link:http://www.mariopareja.com/blog/archive/2010/01/11/how-to-push-a-new-local-branch-to-a-remote.aspx[here] and link:http://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-both-locally-and-in-github[here].
+
+
+
+== Quick change: stashing changes
+
+If you are working on something but are not ready to commit, then use:
+
+[source,bash]
+----
+git stash
+----
+
+
+If you use `gitk --all` then you'll see new commits are made that hold the current state of your working directory and staging area.
+
+You can then, for example, pull down the latest changes using `git pull --rebase` (see above).
+
+To reapply your stash, then use:
+
+[source,bash]
+----
+git stash pop
+----
+
+Note that stashing works even if switching branches
+
+
+## Ignoring files
+
+Put file patterns into `.gitignore`. There is one at the root of the git repo, but they can additionally appear in subdirectories (the results are cumulative).
+
+See also:
+
+- link:https://help.github.com/articles/ignoring-files[github's help page]
+- link:http://www.kernel.org/pub/software/scm/git/docs/gitignore.html[man page]
+
+
+
+
+== More advanced use cases
+
+=== If accidentally push to remote
+
+Suppose you committed to `master`, and then pushed the change, and then decided that you didn't intend to do that:
+
+[source,bash]
+----
+C1 - C2 - C3 - C4 - C5 - C6 - C7
+ ^
+ master
+ ^
+ origin/master
+----
+
+To go back to an earlier commit, first we wind back the local `master`:
+
+[source,bash]
+----
+git reset --hard C5
+----
+
+where `C5` is the long sha-id for that commit.
+
+This gets us to:
+
+[source,bash]
+----
+C1 - C2 - C3 - C4 - C5 - C6 - C7
+ ^
+ master
+ ^
+ origin/master
+----
+
+Then, do a force push:
+
+[source,bash]
+----
+git push origin master --force
+----
+
+If this doesn't work, it may be that the remote repo has disabled this feature. There are other hacks to get around this, see for example link:http://stackoverflow.com/questions/1377845/git-reset-hard-and-a-remote-repository[here].
+
+
+
+
+== If you've accidentally worked on `master` branch
+
+If at any time the `git pull` from your upstream fails, it most likely means that you must have made commits on the `master` branch. You can use `gitk --all` to confirm; at some point in time both `master` and `origin\master` will have a common ancestor.
+
+You can retrospectively create a topic branch for the work you've accidentally done on `master`.
+
+First, create a branch for your current commit:
+
+[source,bash]
+----
+git branch <i>newbranch</i>
+----
+
+
+Next, make sure you have no outstanding edits. If you do, you should commit them or stash them:
+
+
+[source,bash]
+----
+git stash
+----
+
+
+Finally, locate the shaId of the commit you want to roll back to (easily obtained in `gitk -all`), and wind `master` branch back to that commit:
+
+
+[source,bash]
+----
+git checkout master
+git reset --hard <i>shaId</i> # move master branch shaId of common ancestor
+----
+
+
+
+== If you've forgotten to prefix your commits (but not pushed)
+
+One of our committers, Alexander Krasnukhin, has put together some git scripts to help his workflow. Using one of these, `git prefix`, you can just commit with proper message without bothering about prefix and add prefix only in the end *before* the final push.
+
+For example, to prefix all not yet prefixed commits `master..isis/666` with `ISIS-666` prefix, use:
+
+[source,bash]
+----
+git prefix ISIS-666 master..isis/666
+----
+
+
+You can grab this utility, and others, from link:https://github.com/themalkolm/git-boots[this repo].
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
new file mode 100644
index 0000000..e425dae
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
@@ -0,0 +1,69 @@
+[[_cg_ide-templates]]
+= IDE Templates
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+We provide IDE templates (for IntelliJ and Eclipse) for writing Apache Isis domain objects, and also for unit tests (JUnit and JMock).
+
+== Download
+
+The following table lists the templates to download
+
+[cols="1a,1a,1a,1a", options="header"]
+|===
+
+|Template
+|Prefix
+|IntelliJ
+|Eclipse
+
+
+|Apache Isis Domain Objects
+|is
+|link:./resources/templates/isis-templates-idea.xml[Download]
+|link:./resources/templates/isis-templates.xml[Download]
+
+
+|JUnit tests
+|ju
+|link:./resources/templates/junit4-templates-idea.xml[Download]
+|link:./resources/templates/junit4-templates.xml[Download]
+
+
+|JMock tests
+|jm
+|link:./resources/templates/jmock2-templates-idea.xml[Download]
+|link:./resources/templates/jmock2-templates.xml[Download]
+
+|===
+
+
+The most commonly used Apache Isis domain objects templates are also listed on the link:./cheat-sheet.html[Apache Isis cheat sheet].
+
+
+
+== Installation
+
+=== IntelliJ
+
+To install in IntelliJ, copy to the relevant `config/templates` directory, eg:
+
+* Windows `<User home>\.IntelliJIdea14\config\templates`
+* Linux `~/.IntelliJIdea14/config/templates`
+* Mac OS `~/Library/Preferences/IntelliJIdea14/templates`
+
+
+=== Eclipse
+
+To install in Eclipse, go to `Windows > Preferences > Java > Editor > Templates` and choose `Import`.
+
+
+
+== Usage
+
+Enter the prefix (`is`, `ju`, `jm`) and the IDE will list all available templates in that category.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_ide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide.adoc
new file mode 100644
index 0000000..264060c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide.adoc
@@ -0,0 +1,16 @@
+[[_cg_ide]]
+= Using an IDE
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+
+The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do like wise as you develop your Apache Isis applications using an IDE. Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
+
+This chapter shows how to setup and use two of the most popular IDEs, IntelliJ IDEA and Eclipse.
+
+
+include::_cg_ide_intellij.adoc[leveloffset=+1]
+include::_cg_ide_eclipse.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
new file mode 100644
index 0000000..3efa28d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_eclipse.adoc
@@ -0,0 +1,134 @@
+[[_cg_ide_eclipse]]
+= Developing using Eclipse
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+If you are an http://www.eclipse.org[Eclipse] user, then we recommend you download the "Eclipse JEE package" configuration.
+
+When running an Apache Isis application, it's necessary to setup the development environment so that the Java bytecode can be enhanced by the link:http://www.datanucleus.org[DataNucleus] enhancer. If working in Eclipse, then JDO enhancement is most easily done by installing the http://www.datanucleus.org/products/datanucleus/jdo/guides/eclipse.html[DataNucleus' Eclipse plugin]. This hooks the bytecode enhancement of your domain objects into Eclipse's normal incremental compilation.
+
+This plugin needs to be configured for each of your domain modules (usually just one in any given app). The steps are therefore:
+
+* import the project into Eclipse
+* configure the DataNucleus enhancer
+* run the app from the `.launch` file
+
+
+
+
+== Screencast
+
+The following screencast shows how to import an Apache Isis maven-based application into Eclipse and configure to use with the JDO Objectstore
+
+video::RgcYfjQ8yJA[youtube,width="640px",height="480px"]
+
+
+
+
+== Importing the Project
+
+Use File > 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:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`. Chances are it is already set up from running the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+
+Then, tell DataNucleus to use the project classpath:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"]
+
+When the enhancer runs, it will print out to the console:
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
+
+
+
+=== Workaround for path limits (the DN plugin to use the persistence.xml)
+
+If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
+
+To fix this, we configure the enhancer to read from the `persistence.xml` file.
+
+As a prerequisite, first make sure that your domain object model has a `persistence.xml` file. Then specify the `persistence-unit` in the project properties:
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png"]
+
+
+=== Workaround: If the enhancer fails
+
+On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's `Debug` view:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
+
+
+At any rate, you'll know you've encountered this error if you see the following in the console:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"]
+
+
+
+The best solution is to remove DataNucleus support and then to re-add it:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"]
+
+
+If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.
+
+Not ideal, we know. Please feel free to contribute a better solution :-)
+
+
+
+
+== Running the App
+
+The simpleapp archetype automatically provides a `.launch` configurations in the `webapp` module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".
+
+
+[NOTE]
+====
+The screencast above shows this in action.
+====
+
+
+
+
+
+== Other domain projects.
+
+There is nothing to prevent you having multiple domain projects. You might want to do such that each domain project corresponds to a http://www.methodsandtools.com/archive/archive.php?id=97p2[DDD module], thus guaranteeing that there are no cyclic dependencies between your modules.
+
+If you do this, make sure that each project has its own `persistence.xml` file.
+
+And, remember also to configure Eclipse's DataNucleus plugin for these other domain projects.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_intellij.adoc
new file mode 100644
index 0000000..739e062
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide_intellij.adoc
@@ -0,0 +1,398 @@
+[[_cg_ide_intellij]]
+= Developing using IntelliJ IDEA
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+This section describes how to install and setup IntelliJ, then how to import an application into IntelliJ and run it.
+
+
+[NOTE]
+====
+This document relates to IntelliJ Community Edition 14.1.x, with screenshots taken for Windows.
+====
+
+
+
+== Installing and Setting up
+
+This section covers installation and setup.
+
+=== Download and Install
+
+https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
+
+Start the wizard, click through the welcome page:
+
+.IntelliJ Installation Wizard - Welcome page
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png[width="400px"]
+
+Choose the location to install the IDE:
+
+.IntelliJ Installation Wizard - Choose Location
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/020-choose-location.png[width="400px"]
+
+Adjust any installation options as you prefer:
+
+.IntelliJ Installation Wizard - Installation Options
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/030-installation-options.png[width="400px"]
+
+and the start menu:
+
+.IntelliJ Installation Wizard - Start Menu Folder
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
+
+and finish up the wizard:
+
+.IntelliJ Installation Wizard - Completing the Wizard
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/050-completing.png[width="400px"]
+
+Later on we'll specify the Apache Isis/ASF code style settings, so for now select `I do not want to import settings`:
+
+.IntelliJ Installation Wizard - Import Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
+
+Finally, if you are young and trendy, set the UI theme to Darcula:
+
+.IntelliJ Installation Wizard Set UI Theme
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
+
+
+
+
+=== New Project
+
+In IntelliJ a project can contain multiple modules; these need not be physically located together. (If you are previously an Eclipse user, you can think of it as similar to an Eclipse workspace).
+
+Start off by creating a new project:
+
+.IntelliJ Create New Project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
+
+We want to create a new *Java* project:
+
+.IntelliJ Create New Project - Create a Java project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="600px"]
+
+We therefore need to specify the JDK.
+
+NOTE: at the time of writing Apache Isis supports only Java 7; Java 8 is scheduled for support in Apache Isis v1.9.0
+
+
+.IntelliJ Create New Java Project - Select the JDK
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="300px"]
+
+Specify the directory containing the JDK:
+
+.IntelliJ Create New Project - Select the JDK location
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
+
+Finally allow IntelliJ to create the directory for the new project:
+
+.IntelliJ Create New Project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png[width="200px"]
+
+
+
+=== Import Settings
+
+Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions. These are bundled as the `settings.jar` JAR file link:resources/appendices/dev-env/intellij/isis-settings.jar[download from the Apache Isis website]).
+
+Import using: `File > Import Settings`, and specify the directory that you have downloaded the file to:
+
+.IntelliJ Import Settings - Specify JAR file
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
+
+Select all the (two) categories of settings available in the JAR file:
+
+.IntelliJ Import Settings - Select all categories
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png[width="300px"]
+
+And then restart:
+
+.IntelliJ Import Settings - Restart
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/030-restart.png[width="200px"]
+
+
+
+=== Other Settings
+
+There are also some other miscellaneous settings that we recommend that you adjust (though these are not critical).
+
+First, specify an up-to-date Maven installation, using `File > Settings` (or `IntelliJ > Preferences` if on MacOS):
+
+.IntelliJ Other Settings - Maven Installation
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png[width="600px"]
+
+Still on the Maven settings page, configure as follows:
+
+.IntelliJ Other Settings - Maven Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png[width="600px"]
+
+On the compiler settings page, ensure that `build automatically` is enabled (and optionally `compile independent modules in parallel`):
+
+.IntelliJ Other Settings - Compiler Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png[width="600px"]
+
+On the auto import page, check the `optimize imports on the fly` and `add unambiguous imports on the fly`
+
+.IntelliJ Other Settings - Auto Import
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png[width="600px"]
+
+
+
+=== Plugins
+
+You might also want to set up some additional plugins, using `File > Settings > Plugins` (or equivalently `File > Other Settings > Configure Plugins`).
+
+Recommended are:
+
+* link:https://plugins.jetbrains.com/plugin/7179?pr=idea[Maven Helper] plugin
++
+More on this below.
+
+* link:https://github.com/asciidoctor/asciidoctor-intellij-plugin[AsciiDoctor] plugin
++
+Useful if you are doing any authoring of documents.
+
+Some others you might like to explore are:
+
+.IntelliJ Plugins
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="600px"]
+
+==== Maven Helper Plugin
+
+This plugin provides a couple of great features. One is better visualization of dependency trees (similar to Eclipse).
+
+If you open a `pom.xml` file, you'll see an additional "Dependencies" tab:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"]
+
+Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by `mvn dependency:tree`, but filterable.
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"]
+
+The plugin also provides the ability to easily run a Maven goal on a project:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"]
+
+This menu can also be bound to a keystroke so that it is available as a pop-up:
+
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"]
+
+
+
+== Importing and Managing Maven Modules
+
+Let's load in some actual code! We do this by importing the Maven modules.
+
+First up, open up the Maven tool window (`View > Tool Windows > Maven Projects`). You can then use the 'plus' button to add Maven modules. In the screenshot you can see we've loaded in Apache Isis core; the modules are listed in the _Maven Projects_ window and corresponding (IntelliJ) modules are shown in the _Projects_ window:
+
+.IntelliJ Maven Module Management - Importing Maven modules
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
+
+We can then import another module (from some other directory). For example, here we are importing the Isis Addons' todoapp example:
+
+
+.IntelliJ Maven Module Management - Importing another Module
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
+
+You should then see the new Maven module loaded in the _Projects_ window and also the _Maven Projects_ window:
+
+.IntelliJ Maven Module Management -
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
+
+If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from `.m2/repository` folder). So, for example (assuming that the `<version>` is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.
+
+You can press F4 (or use `File > Project Structure`) to see the resolved classpath for any of the modules loaded into the project.
+
+If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you _could_ remove the module; but better is to ignore those modules. This will remove from the the _Projects_ window but keep them available in the _Maven Projects_ window for when you next want to work on them:
+
+.IntelliJ Maven Module Management - Ignoring Modules
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
+
+Confirm that it's ok to ignore these modules:
+
+.IntelliJ Maven Module Management - Ignoring Modules (ctd)
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
+
+All being well you should see that the _Projects_ window now only contains the code you are working on. Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from `.m2/repository`):
+
+.IntelliJ Maven Module Management - Updated Projects Window
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
+
+
+
+== Running
+
+Let's see how to run both the app and the tests.
+
+=== Running the App
+
+Once you've imported your Isis application, we should run it. We do this by creating a Run configuration, using `Run > Edit Configurations`.
+
+Set up the details as follows:
+
+.IntelliJ Running the App - Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
+
+We specify the `Main class` to be `org.apache.isis.WebServer`; this is a wrapper around Jetty. It's possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.
+
+Also note that `Use classpath of module` is the webapp module for your app, and that the `working directory` is `$MODULE_DIR$`.
+
+Next, and most importantly, configure the DataNucleus enhancer to run for your `dom` goal. This can be done by defining a Maven goal to run before the app:
+
+.IntelliJ Running the App - Datanucleus Enhancer Goal
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
+
+The `-o` flag in the goal means run off-line; this will run faster.
+
+WARNING: if you forget to set up the enhancer goal, or don't run it on the correct (dom) module, then you will get all sorts of errors when you startup. These usually manifest themselves as class cast exception in DataNucleus.
+
+You should now be able to run the app using `Run > Run Configuration`. The same configuration can also be used to debug the app if you so need.
+
+
+=== Running the Unit Tests
+
+The easiest way to run the unit tests is just to right click on the `dom` module in the _Project Window_, and choose run unit tests. Hopefully your tests will pass (!).
+
+.IntelliJ Running the App - Unit Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
+
+As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:
+
+.IntelliJ Running the App - Unit Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
+
+Thereafter, you should run units by selecting this configuration (if you use the right click approach you'll end up with lots of run configurations, all similar).
+
+=== Running the Integration Tests
+
+Integration tests can be run in the same way as unit tests, however the `dom` module must also have been enhanced.
+
+One approach is to initially run the tests use the right click on the `integtests` module; the tests will fail because the code won't have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):
+
+.IntelliJ Running the App - Integration Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
+
+
+
+
+== Hints and Tips
+
+=== Keyboard Shortcuts Cheat Sheets
+
+You can download 1-page PDFs cheat sheets for IntelliJ's keyboard shortcuts:
+* for link:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf[Windows]
+* for MacOS:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]
+
+Probably the most important shortcut on them is for `Find Action`:
+- `ctrl-shift-A` on Windows
+- `cmd-shift-A` on MacOS.
+
+This will let you search for any action just by typing its name.
+
+### Switching between Tool Windows and Editors
+
+The Tool Windows are the views around the editor (to left, bottom and right). It's possible to move these around to your preferred locations.
+
+* Use `alt-1` through `alt-9` (or `cmd-1` through `alt-9`) to select the tool windows
+** Press it twice and the tool window will hide itself; so can use to toggle
+* If in the _Project Window_ (say) and hit enter on a file, then it will be shown in the editor, but (conveniently) the focus remains in the tool window. To switch to the editor, just press `Esc`.
+** If in the _Terminal Window_, you'll need to press `Shift-Esc`.
+* If on the editor and want to locate the file in (say) the _Project Window_, use `alt-F1`.
+* To change the size of any tool window, use `ctrl-shift-arrow`
+
+Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!
+
+=== Navigating Around
+
+For all of the following, you don't need to type every letter, typing "ab" will actually search for ".*a.*b.*".
+
+* to open classes or files or methods that you know the name of:
+** `ctrl-N` to open class
+** `ctrl-shift-N` to open a file
+** (bit fiddly this) `ctrl-shift-alt-N` to search for any symbol.
+* open up dialog of recent files: `ctrl-E`
+* search for any file: `shift-shift`
+
+Navigating around:
+* find callers of a method (the call hierarchy): `ctrl-alt-H`
+* find subclasses or overrides: `ctrl-alt-B`
+* find superclasses/interface/declaration: `ctrl-B`
+
+Viewing the structure (ie outline) of a class
+* `ctrl-F12` will pop-up a dialog showing all members
+** hit `ctrl-F12` again to also see inherited members
+
+
+=== Editing
+
+* Extend selection using `ctrl-W`
+** and contract it down again using `ctrl-shift-W`
+* to duplicate a line, it's `ctrl-D`
+** if you have some text selected (or even some lines), it'll actually duplicate the entire selection
+* to delete a line, it's `ctrl-X`
+* to move a line up or down: `shift-alt-up` and `shift-alt-down`
+** if you have selected several lines, it'll move them all togethe
+* `ctrl-shift-J` can be handy for joining lines together
+** just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")
+
+### Intentions and Code Completion
+
+Massively useful is the "Intentions" popup; IntelliJ tries to guess what you might want to do. You can activate this using`alt-enter`, whenever you see a lightbulb/tooltip in the margin of the current line.
+
+Code completion usually happens whenever you type '.'. You can also use `ctrl-space` to bring these up.
+
+In certain circumstances (eg in methods0) you can also type `ctrl-shift-space` to get a smart list of methods etc that you might want to call. Can be useful.
+
+Last, when invoking a method, use `ctrl-P` to see the parameter types.
+
+
+=== Refactoring
+
+Loads of good stuff on the `Refactor` menu; most used are:
+
+* Rename (`shift-F6`)
+* Extract
+** method: `ctrl-alt-M`
+** variable: `ctrl-alt-V`
+* Inline method/variable: `ctrl-alt-N`
+* Change signature
+
+If you can't remember all those shortcuts, just use `ctrl-shift-alt-T` (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object
+
+
+=== Troubleshooting
+
+When a Maven module is imported, IntelliJ generates its own project files (suffix `.ipr`), and the application is actually built from that.
+
+Occasionally these don't keep in sync (even if auto-import of Maven modules has been enabled).
+
+To fix the issue, try:
+* reimport module
+* rebuild selected modules/entire project
+* remove and then re-add the project
+* restart, invalidating caches
+* hit StackOverflow (!)
+
+One thing worth knowing; IntelliJ actively scans the filesystem all the time. It's therefore (almost always) fine to build the app from the Maven command line; IntelliJ will detect the changes and keep in sync. If you want to force that, use `File > Synchronize`, `ctrl-alt-Y`.
+
+
+
+
+== Advanced
+
+In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
+
+
+=== Setting up Dynamic Reloading
+
+NOTE: TODO - see link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
+
+
+=== Setting up JRebel
+
+NOTE: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
new file mode 100644
index 0000000..327f14a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_isis-maven-plugin.adoc
@@ -0,0 +1,9 @@
+[[_cg_isis-maven-plugin]]
+= Apache Isis Maven Plugin
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+NOTE: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_policies.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_policies.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_policies.adoc
new file mode 100644
index 0000000..df3b302
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_policies.adoc
@@ -0,0 +1,14 @@
+[[_cg_policies]]
+= Policies
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+This chapter pulls together various policy documents relating to the development of Apache Isis'.
+
+include::_cg_policies_versioning-policy.adoc[leveloffset=+1]
+include::_cg_policies_git-policy.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_policies_git-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_policies_git-policy.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_policies_git-policy.adoc
new file mode 100644
index 0000000..3de8b36
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_policies_git-policy.adoc
@@ -0,0 +1,98 @@
+[[_cg_policies_git-policy]]
+= Git Policy
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:
+
+* git commits form an acyclic graph, with each commit pointing to its parent commit (or commit**s**, if a merge)
+
+* a branch is merely a pointer to one of these commits; git calls the main branch `master`
+
+* git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.
+
+For more background reading, see:
+
+* http://git-scm.com/book[Pro Git] book (free in electronic form)
+* https://github.s3.amazonaws.com/media/book.pdf[Git community book]
+* http://git-scm.com/2011/07/11/reset.html[git reset demystified] - differentiating the working directory vs index/staging area
+
+And, of course, there is loads of good advice on http://stackoverflow.com/questions/tagged/git[stackoverflow.com]
+
+
+
+== Workflow
+
+There are many ways of using Git, but the Apache Isis committers have adopted the following workflow:
+
+* create a topic branch for a feature +
++
+[source,bash]
+----
+git checkout -b ISIS-999
+----
+
+* periodically, push the branch to origin (for safekeeping): +
++
+[source,bash]
+----
+git push origin ISIS-999
+----
+
+
+* `rebase` the topic branch periodically on master. +
++
+How often you do this will depend on whether you are collaborating with others on the feature. You need to ensure that your co-worker has no outstanding work before you do this; otherwise it'll create merge conflict hell for them:
++
+[source,bash]
+----
+git checkout master
+git pull
+git checkout ISIS-999
+git rebase master
+git push origin ISIS-999 --force
+----
+
+* when feature is complete, rebase once more (as above), then switch to master and perform a `merge --no-ff`: +
++
+[source,bash]
+----
+git checkout master
+git merge --no-ff ISIS-999
+----
+
+* finally, remove the branch +
++
+[source,bash]
+----
+git branch -d ISIS-999
+git push origin --delete ISIS-999
+----
+
+This way of working gives us the full history on the branch as to what the thought processes were for the feature, but only a single commit on to `master` to see the ultimate impact of the changes (acting a bit like a summary).
+
+
+
+
+
+== Commit message
+
+The minimum we expect in a commit messages is:
+
+[source,bash]
+----
+ISIS-nnn: brief summary here
+
+- optionally, longer details
+- should be written here
+- in bullet points
+----
+
+
+where `ISIS-nnn` is a ticket raised in our https://issues.apache.org/jira/browse/ISIS[JIRA issue tracker].
+
+For non-committers we typically expect more detail again; see the xref:cg.adoc#_cg_contributing[contributing] page for the longer format recommended for contributors to use.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_cg_policies_versioning-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_policies_versioning-policy.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_policies_versioning-policy.adoc
new file mode 100644
index 0000000..c04fb4a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_policies_versioning-policy.adoc
@@ -0,0 +1,35 @@
+[[_cg_committers_versioning-policy]]
+= Versioning Policy
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+
+## Semantic Versioning
+
+Starting from v1.0.0, Apache Isis has adopted link:http://semver.org[semantic versioning] for its versioning policy.
+
+Version numbers are in the form `x.y.z`:
+
+- x is bumped up whenever there a breaking API change
+- y is bumped up whenever there is a new feature that does not break API
+- z is bumped up for minor bug fixes.
+
+This scheme would be adopted for both core and components.
+
+
+
+
+
+
+## Version ranges
+
+Version ranges may not be used. If necessary, end-users can use `<dependencyManagement` elements to have combine components built against different versions of core.
+
+That said, this can introduce instability and so generally we recommend that end-users configure the `maven-enforcer-plugin` and its link:http://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html[DependencyConvergence] rule. This will help avoid "jar hell" (components having conflicting dependencies of core).
+
+If there is a conflict, we would ask that end-users engage with Apache Isis committers to have an updated version of the component(s) pushed out.
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
deleted file mode 100644
index 57754ac..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_dg_cmd-line]]
-= Developing from the Command Line
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-NOTE: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
deleted file mode 100644
index 625f404..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
+++ /dev/null
@@ -1,136 +0,0 @@
-[[_dg_eclipse]]
-= Setting up Eclipse
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-
-We highly recommend that you develop your Isis application using an IDE. Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
-
-If you are an http://www.eclipse.org[Eclipse] user, then we recommend you download the "Eclipse JEE package" configuration.
-
-When running an Isis application, it's necessary to setup the development environment so that the Java bytecode can be enhanced by the link:http://www.datanucleus.org[DataNucleus] enhancer. If working in Eclipse, then JDO enhancement is most easily done by installing the http://www.datanucleus.org/products/datanucleus/jdo/guides/eclipse.html[DataNucleus' Eclipse plugin]. This hooks the bytecode enhancement of your domain objects into Eclipse's normal incremental compilation.
-
-This plugin needs to be configured for each of your domain modules (usually just one in any given app). The steps are therefore:
-
-* import the project into Eclipse
-* configure the DataNucleus enhancer
-* run the app from the `.launch` file
-
-
-
-
-== Screencast
-
-The following screencast shows how to import an Apache Isis maven-based application into Eclipse and configure to use with the JDO Objectstore
-
-video::RgcYfjQ8yJA[youtube,width="640px",height="480px"]
-
-
-
-
-== Importing the Project
-
-Use File > 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:ug.adoc#_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`. Chances are it is already set up from running the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-
-Then, tell DataNucleus to use the project classpath:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"]
-
-When the enhancer runs, it will print out to the console:
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
-
-
-
-=== Workaround for path limits (the DN plugin to use the persistence.xml)
-
-If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
-
-To fix this, we configure the enhancer to read from the `persistence.xml` file.
-
-As a prerequisite, first make sure that your domain object model has a `persistence.xml` file. Then specify the `persistence-unit` in the project properties:
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png"]
-
-
-=== Workaround: If the enhancer fails
-
-On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's `Debug` view:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
-
-
-At any rate, you'll know you've encountered this error if you see the following in the console:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"]
-
-
-
-The best solution is to remove DataNucleus support and then to re-add it:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"]
-
-
-If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.
-
-Not ideal, we know. Please feel free to contribute a better solution :-)
-
-
-
-
-== Running the App
-
-The simpleapp archetype automatically provides a `.launch` configurations in the `webapp` module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".
-
-
-[NOTE]
-====
-The screencast above shows this in action.
-====
-
-
-
-
-
-== Other domain projects.
-
-There is nothing to prevent you having multiple domain projects. You might want to do such that each domain project corresponds to a http://www.methodsandtools.com/archive/archive.php?id=97p2[DDD module], thus guaranteeing that there are no cyclic dependencies between your modules.
-
-If you do this, make sure that each project has its own `persistence.xml` file.
-
-And, remember also to configure Eclipse's DataNucleus plugin for these other domain projects.
-