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:34 UTC
[05/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/_ug_tutorials_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc
deleted file mode 100644
index 262285c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc
+++ /dev/null
@@ -1,683 +0,0 @@
-[[_ug_tutorials_stop-scaffolding-start-coding]]
-= Stop scaffolding, start coding
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This is a half-day tutorial on developing domain-driven apps using Apache Isis. Actually, you could probably spend a full day working through this tutorial if you wanted to, so pick and choose the bits that look interesting.
-
-There's a bit of overlap with the xref:ug.adoc#_ug_tutorials_pet-clinic[Pet Clinic] tutorial initially, but it then sets off on its own.
-
-
-
-== Prerequisites
-
-You'll need:
-
-* Java 7 JDK
-* http://maven.apache.org/[Maven] 3.2.x
-* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
-
-
-
-== Run the archetype
-
-Run the simpleapp archetype to build an empty Isis application:
-
-[source,bash]
-----
-mvn archetype:generate \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=simpleapp-archetype \
- -D archetypeVersion=1.8.0 \
- -D groupId=com.mycompany \
- -D artifactId=myapp \
- -D version=1.0-SNAPSHOT \
- -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
- -B
-----
-
-
-
-
-== Build and run
-
-Start off by building the app from the command line:
-
-[source,bash]
-----
-cd myapp
-mvn clean install
-----
-
-Once that's built then run using:
-
-[source,bash]
-----
-mvn antrun:run -P self-host
-----
-
-A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
-
-Alternatively, you can run using the mvn-jetty-plugin:
-
-[source,bash]
-----
-mvn jetty:run
-----
-
-This will accomplish the same thing, though the webapp is mounted at a slightly different URL
-
-
-
-
-== Using the app
-
-Navigate to the Wicket UI (eg link:http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
-
-Once at the home page:
-
-* install fixtures
-* list all objects
-* create a new object
-* list all objects
-
-Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
-
-
-
-
-== Dev environment
-
-Set up link:dg.adoc[an IDE] and import the project to be able to run and debug the app.
-
-Then set up a launch configuration and check that you can:
-
-* Run the app from within the IDE
-* Run the app in debug mode
-* Run with different deploymentTypes; note whether prototype actions (those annotated xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action(restrictTo=PROTOTYPING`]) are available or not:
-* `--type SERVER_PROTOTYPE`
-* `--type SERVER`
-
-
-
-
-== Explore codebase
-
-Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
-
-* `myapp` : parent module
-* `myapp-dom`: domain objects module
-* entity: `dom.simple.SimpleObject`
-* repository: `dom.simple.SimpleObjects`
-* `myapp-fixture`: fixtures module
-* fixture script:`fixture.simple.SimpleObjectsFixture`
-* `myapp-integtests`: integration tests module
-* `myapp-webapp`: webapp module
-* (builds the WAR file)
-
-
-
-
-== Testing
-
-Testing is of course massively important, and Apache Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
-
-* `myapp-dom` unit tests
-* run
-* inspect, eg
- - `SimpleObjectTest`
-* `myapp-integtests` integration tests
-* run
-* inspect, eg:
-** `integration.tests.smoke.SimpleObjectsTest`
-** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
-* generated report, eg
- - `myapp/integtests/target/cucumber-html-report/index.html`
-** change test in IDE, re-run (in Maven)
-
-If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
-
-
-
-
-== Prototyping
-
-Although testing is important, in this tutorial we want to concentrate on how to write features and to iterate quickly. So for now, exclude the `integtests` module. Later on in the tutorial we'll add the tests back in so you can learn how to write automated tests for the features of your app.
-
-In the parent `pom.xml`:
-
-[source,xml]
-----
-<modules>
- <module>dom</module>
- <module>fixture</module>
- <module>integtests</module>
- <module>webapp</module>
-</modules>
-----
-
-change to:
-
-[source,xml]
-----
-<modules>
- <module>dom</module>
- <module>fixture</module>
- <!--
- <module>integtests</module>
- -->
- <module>webapp</module>
-</modules>
-----
-
-
-
-
-== Build a domain app
-
-The remainder of the tutorial provides guidance on building a domain application. We don't mandate any particular design, but we suggest one with no more than 3 to 6 domain entities in the first instance. If you're stuck for ideas, then how about:
-
-* a todo app (``ToDoItem``s)
-* a pet clinic (`Pet`, `Owner`, `PetSpecies`, `Visit`)
-* a library (`Book`, `Title`, `LibraryMember`, `Loan`, `Reservation`)
-* a holiday cottage rental system
-* a scrum/kanban system (inspired by Trello)
-* a meeting planner (inspired by Doodle)
-* (the domain model for) a CI server (inspired by Travis/Jenkins)
-* a shipping system (inspired by the example in the DDD "blue" book)
-* a system for ordering coffee (inspired by Restbucks, the example in "Rest in Practice" book)
-
-Hopefully one of those ideas appeals or sparks an idea for something of your own.
-
-
-
-
-== Domain entity
-
-Most domain objects in Apache Isis applications are persistent entities. In the simpleapp archetype the `SimpleObject` is an example. We can start developing our app by refactoring that class:
-
-* rename the `SimpleObject` class
-** eg rename to `Pet`
-* if required, rename the `SimpleObject` class' `name` property
-** for `Pet`, can leave `name` property as is
-* specify a xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[title]
-* specify an xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[icon]
-* make the entity bookmarkable by adding the xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`] attribute.
-* confirm is available from bookmark panel (top-left of Wicket UI)
-
-
-
-
-== Domain service
-
-Domain services often act as factories or repositories to entities; more generally can be used to "bridge across" to other domains/bounded contexts. Most are application-scoped, but they can also be request-scoped if required.
-
-In the simpleapp archetype the `SimpleObjects` service is a factory/repository for the original `SimpleObject` entity. For our app it therefore makes sense to refactor that class into our own first service:
-
-* rename the `SimpleObjects` class
-** eg rename to `Pets`
-* review `create` action (acting as a factory)
-** as per the docs describing xref:ug.adoc#_ug_how-tos_crud[how to create or delete objects]
-* rename if you wish
-** eg `newPet(...)` or `addPet(...)`
-* review `listAll` action (acting as a repository)
-* as per the docs describing xref:ug.adoc#_ug_how-tos_crud[how to write a custom repository]
-* note the annotations on the corresponding domain class (originally called `SimpleObject`, though renamed by now, eg to `Pet`)
-* rename if you wish
-** eg `listPets()`
-* note the xref:rg.adoc#_rg_annotations_manpage-DomainService[`@DomainService`] annotation
-* optional: add an action to a return subset of objects
-** use the JDO `@Query` annotation
-** see for example the Isisaddons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF), see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L93[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItems.java#L63[here]
-
-
-
-
-== Fixture scripts
-
-Fixture scripts are used to setup the app into a known state. They are great for demo's and as a time-saver when implementing a feature, and they can also be reused in automated integration tests. We usually also have a fixture script to zap all the (non-reference) data (or some logical subset of the data)
-
-* rename the `SimpleObjectsTearDownFixture` class
-* and update to delete from the appropriate underlying database table(s)
-* use the injected xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] domain service.
-* refactor/rename the fixture script classes that create instances your entity:
-* `RecreateSimpleObjects`, which sets up a set of objects for a given scenario
-* `SimpleObjectCreate` which creates a single object
-* note that domain services can be injected into these fixture scripts
-
-
-
-
-== Actions
-
-Most business functionality is implemented using actions� basically a `public` method accepting domain classes and primitives as its parameter types. The action can return a domain entity, or a collection of entities, or a primitive/String/value, or void. If a domain entity is returned then that object is rendered immediately; if a collection is returned then the Wicket viewer renders a table. Such collections are sometimes called "standalone" collections.
-
-* write an action to update the domain property (originally called `SimpleObject#name`, though renamed by now)
-* use the xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`@ParameterLayout(named=...)`] annotation to specify the name of action parameters
-* use the xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action(semanticsOf=...)`] annotation to indicate the semantics of the action (safe/query-only, idempotent or non-idempotent)
-* annotate safe action as bookmarkable using xref:rg.adoc#_rg_annotations_manpage-ActionLayout_bookmarking[`@ActionLayout(bookmarking=...)`]
-* confirm is available from bookmark panel (top-left of Wicket UI)
-* optional: add an action to clone an object
-
-
-
-
-== REST API
-
-As well as exposing the Wicket viewer, Isis also exposes a REST API (an implementation of the http://restfulobjects.org[Restful Objects spec]). All of the functionality of the domain object model is available through this REST API.
-
-* add Chrome extensions
-* install https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Postman]
-* install https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en[JSON-View]
-* browse to Wicket viewer, install fixtures
-* browse to the http://localhost:8080/restful[http://localhost:8080/restful] API
-* invoke the service to list all objects
-* services
-* actions
-* invoke (invoking 0-arg actions is easy; the Restful Objects spec defines how to invoke N-arg actions)
-
-
-
-
-== Specify Action semantics
-
-The semantics of an action (whether it is safe/query only, whether it is idempotent, whether it is neither) can be specified for each action; if not specified then Isis assumes non-idempotent. In the Wicket viewer this matters in that only query-only actions can be bookmarked or used as contributed properties/collections. In the RESTful viewer this matters in that it determines the HTTP verb (GET, PUT or POST) that is used to invoke the action.
-
-* experiment changing xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action(semantics=...)`] on actions
-* note the HTTP methods exposed in the REST API change
-* note whether the non-safe actions are bookmarkable (assuming that it has been annotated with `@ActionLayout(bookmarking=...)`, that is).
-
-
-
-
-== Value properties
-
-Domain entities have state: either values (primitives, strings) or references to other entities. In this section we explore adding some value properties
-
-* add some xref:ug.adoc#_ug_how-tos_class-structure_properties[value properties]; also:
-* for string properties
-** use the xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_multiLine[`@Property(multiLine=...)`] annotation to render a text area instead of a text box
-** use the xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
-** use joda date/time properties, bigdecimals and blob/clob properties
-* use the xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Column(allowsNull=...)`] annotation specify whether a property is optional or mandatory
-* use enums for properties (eg as used in the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp], see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L207[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L266[here])
-* update the corresponding domain service for creating new instances
-* for all non-optional properties will either need to prompt for a value, or calculate some suitable default
-* change the implementation of title, if need be
-* revisit the title, consider whether to use the xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`] annotation
-** rather than the xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] `title()` method
-* order the properties using the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
-** see also the docs on xref:rg.adoc#_rg_object-layout_static[static layouts]
-* use the xref:rg.adoc#_rg_annotations_manpage-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
-** do the same for parameters using xref:rg.adoc#_rg_annotations_manpage-ParameterLayout[`@ParameterLayout`]
-
-
-
-
-== Reference properties
-
-Domain entities can also reference other domain entities. These references may be either scalar (single-valued) or vector (multi-valued). In this section we focus on scalar reference properties.
-
-* add some xref:ug.adoc#_ug_how-tos_class-structure_properties[reference properties]
-* update the corresponding domain service (for creation actoin)
-* use different techniques to obtain references (shown in drop-down list box)
-** use the xref:rg.adoc#_rg_annotations_manpage-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
-** use a xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`] supporting method
-*** on a property
-*** on an action parameter
-** use a xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method
-*** on a property
-*** on an action parameter
-
-
-
-
-== Usability: Defaults
-
-Quick detour: often we want to set up defaults to go with choices. Sensible defaults for action parameters can really improve the usability of the app.
-
-* Add xref:ug.adoc#_ug_how-tos_drop-downs-and-defaults[defaults] for action parameters
-
-
-
-
-== Collections
-
-Returning back to references, Isis also supports vector (multi-valued) references to another object instances� in other words collections. We sometimes called these "parented" collections (to distinguish from a "standalone" collection as returned from an action)
-
-* Ensure that all domain classes implement `java.lang.Comparable`
-** use the xref:rg.adoc#_rg_classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
-*** you can also `equals()`, `hashCode()`, `toString()`
-* Add a xref:ug.adoc#_ug_how-tos_class-structure_collections[collection] to one of the entities
-** Use `SortedSet` as the class
-** Use the xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
-* optional: use the xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
-
-
-
-
-
-== Actions and Collections
-
-The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
-
-* Add domain actions to add/remove from the collection
-* to create objects, xref:ug.adoc#_ug_how-tos_class-structure_inject-services[inject] associated domain service
-** generally we recommend using the xref:rg.adoc#_rg_annotations_manpage-Inject[`@Inject`] annotation with either private or default visibility
-* the service itself should use xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
-* use the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
-
-
-
-
-== CSS UI Hints
-
-CSS classes can be associated with any class member (property, collection, action). But for actions in particular:
-
-* the bootstrap "btn" CSS classes can be used using the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout(cssClass=...)`] annotation
-
-* the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
-
-It's also possible to use Font Awesome icons for the xref:ug.adoc#_ug_how-tos_ui-hints_object-titles-and-icons[domain object icon].
-
-So:
-- for some of the actions of your domain services or entities, annotate using `@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`
-
-
-
-
-== Dynamic Layout
-
-Up to this point we've been using annotations (`@MemberOrder`, `@MemberGroupLayout`, `@Named`, `@PropertyLayout`, `@ParameterLayout`, `@ActionLayout` and so on) for UI hints. However, the feedback loop is not good: it requires us stopping the app, editing the code, recompiling and running again. So instead, all these UI hints (and more) can be specified dynamically, using a corresponding `.layout.json` file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run>Reload Changed Classes):
-
-* Delete the various hint annotations and instead specify layout hints using a xref:rg.adoc#_rg_object-layout_dynamic[.layout.json] file.
-
-
-
-
-== Business rules
-
-Apache Isis excels for domains where there are complex business rules to enforce. The UI tries not to constrain the user from navigating around freely, however the domain objects nevertheless ensure that they cannot change into an invalid state. Such rules can be enforced either declaratively (using annotations) or imperatively (using code). The objects can do this in one of three ways:
-
-* visibility: preventing the user from even seeing a property/collection/action
-* usability: allowing the user to view a property/collection/action but not allowing the user to change it
-* validity: allowing the user to modify the property/invoke the action, but validating that the new value/action arguments are correct before hand.
-
-Or, more pithily: "see it, use it, do it"
-
-
-=== See it!
-
-* Use the xref:rg.adoc#_rg_annotations_manpage-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
-** likewise xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[`@Collection(hidden=...)`] for collections
-** the xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] annotation can also be used and in many cases is to be preferred; the difference is that the latter means the member is not part of the Apache Isis metamodel.
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
-
-
-=== Use it!
-
-* Use the xref:rg.adoc#_rg_annotations_manpage-Property_editing[`Property(editing=...)`] annotation to make property read-only
-** likewise xref:rg.adoc#_rg_annotations_manpage-Collection_editing[`@Collection(editing=...)`] for collections
-** alternatively, use xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`@DomainObject(editing=...)`] to disable editing for all properties/collections
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
-
-
-=== Do it!
-
-* use the xref:rg.adoc#_rg_annotations_manpage-Property_regexPattern[`@Property(regexPattern=...)`] annotation to specify a regex pattern for properties, and use xref:rg.adoc#_rg_annotations_manpage-Parameter_regexPattern[`@Parameter(regexPattern=...)`] for parameters
-* use the xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a maxmum number of characters, and xref:rg.adoc#_rg_annotations_manpage-Parameter_maxLength[`@Parameter(maxLength=...)`] for parameters
-* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] supporting method on properties or action parameter
-* optional: for any data type:
-** use the xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
-
-
-
-
-== Home page
-
-The Wicket UI will automatically invoke the "home page" action, if available. This is a no-arg action of one of the domain services, that can return either an object (eg representing the current user) or a standalone action.
-
-* Add the xref:rg.adoc#_rg_annotations_manpage-HomePage[`@HomePage`] annotation to one (no more) of the domain services' no-arg actions
-
-
-
-
-== Clock Service
-
-To ensure testability, there should be no dependencies on system time, for example usage of `LocalDate.now()`. Instead the domain objects should delegate to the provided `ClockService`.
-
-* remove any dependencies on system time (eg defaults for date/time action parameters)
-* inject xref:rg.adoc#_rg_services-api_manpage-ClockService[`ClockService`]
-* call `ClockService.now()` etc where required.
-
-
-
-
-== Using Contributions
-
-One of Apache Isis' most powerful features is the ability for the UI to combine functionality from domain services into the representation of an entity. The effect is similar to traits or mix-ins in other languages, however the "mixing in" is done at runtime, within the Apache Isis metamodel. In Apache Isis' terminology, we say that the domain service action is contributed to the entity.
-
-Any action of a domain service that has a domain entity type as one of its parameter types will (by default) be contributed. If the service action takes more than one argument, or does not have safe semantics, then it will be contributed as an entity action. If the service action has precisely one parameter type (that of the entity) and has safe semantics then it will be contributed either as a collection or as a property (dependent on whether it returns a collection of a scalar).
-
-Why are contributions so useful? Because the service action will match not on the entity type, but also on any of the entity's supertypes (all the way up to `java.lang.Object`). That means that you can apply the http://en.wikipedia.org/wiki/Dependency_inversion_principle[dependency inversion principle] to ensure that the modules of your application have acyclic dependencies; but in the UI it can still appear as if there are bidirectional dependencies between those modules. The lack of bidirectional dependencies can help save your app degrading into a http://en.wikipedia.org/wiki/Big_ball_of_mud[big ball of mud].
-
-Finally, note that the layout of contributed actions/collections/properties can be specified using the `.layout.json` file (and it is highly recommended that you do so).
-
-=== Contributed Actions
-
-* Write a new domain service
-** by convention, called "XxxContributions"
-** annotate with xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)`]
-*** indicates that all of the service's actions should _not_ be included in the main application menu bar
-*** should be rendered "as if" an action of the entity
-* Write an action accepting >1 args:
-** one being a domain entity
-** other being a primitive or String
-
-=== Contributed Collections
-
-* Write a new domain service (or update the one previously)
-* Write a query-only action accepting exactly 1 arg (a domain entity)
-* returning a collection, list or set
-* For this action:
-** add the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
-** should be rendered in the UI "as if" a collection of the entity
-* use `.layout.json` to position as required
-
-
-=== Contributed Properties
-
-* As for contributed collections, write a new domain service with a query-only action accepting exactly 1 arg (a domain entity); except:
-** returning a scalar value rather than a collection
-* For this action:
-** add the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
-* should be rendered in the UI "as if" a property of the entity
-* use `.layout.json` to position as required
-
-
-
-== Using the Event Bus
-
-Another way in which Apache Isis helps you keep your application nicely modularized is through its event bus. Each action invocation, or property modification, can be used to generate a succession of events that allows subscribers to veto the interaction (the see it/use it/do it rules) or, if the action is allowed, to perform work prior to the execution of the action or after the execution of the action.
-
-Under the covers Apache Isis uses the https://code.google.com/p/guava-libraries/wiki/EventBusExplained[Guava event bus] and subscribers (always domain services) subscribe by writing methods annotated with `@com.google.common.eventbus.Subscribe` annotation.
-
-By default the events generated are `ActionDomainEvent.Default` (for actions) and `PropertyDomainEvent.Default` (for properties). Subclasses of these can be specified using the xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action(domainEvent=...)`] or xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`Property(domainEvent=...)`] for properties.
-
-
-Using the guidance in the docs for the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]:
-
-* write a domain service subscriber to subscribe to events
-* use the domain service to perform log events
-* use the domain service to veto actions (hide/disable or validate)
-
-
-
-== Bulk actions
-
-Bulk actions are actions that can be invoked on a collection of actions, that is on collections returned by invoking an action. Actions are specified as being bulk actions using the xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@action(invokeOn=OBJECT_AND_COLLECTION)`] annotation.
-
-[NOTE]
-====
-Note that currently (1.8.0) only no-arg actions can be specified as bulk actions.
-====
-
-Thus:
-* Write a no-arg action for your domain entity, annotate with `@Action(invokeOn=...)`
-* Inject the xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`ActionInteractionContext`] (request-scoped) service
-* Use the `ActionInteractionContext` service to determine whether the action was invoked in bulk or as a regular action.
-* return null if invoked on a collection; the Wicket viewer will go back to the original collection
-** (if return non-null, then Wicket viewer will navigate to the object of the last invocation� generally not what is required)
-
-The similar xref:rg.adoc#_rg_services-api_manpage-Scratchpad[`Scratchpad`] (request-scoped) domain service is a good way to share information between bulk action invocations:
-
-* Inject the `Scratchpad` domain service
-* for each action, store state (eg a running total)
-* in the last invoked bulk action, perform some aggregate processing (eg calculate the average) and return
-
-
-
-
-== Performance tuning
-
-The xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`QueryResultsCache`] (request-scoped) domain service allows arbitrary objects to be cached for the duration of a request.
-
-This can be helpful for "naive" code which would normally make the same query within a loop.
-
-* optional: inject the `QueryResultsCache` service, invoke queries "through" the cache API
-* remember that the service is request-scoped, so it only really makes sense to use this service for code that invokes queries within a loop
-
-
-
-
-== Extending the Wicket UI
-
-Each element in the Wicket viewer (entity form, properties, collections, action button etc) is a component, each created by a internal API (`ComponentFactory`, described xref:ug.adoc#_ug_extending_wicket-viewer[here]). For collections there can be multiple views, and the Wicket viewer provides a view selector drop down (top right of each collection panel).
-
-Moreover, we can add additional views. In this section we'll explore some of these, already provided through http://www.isisaddons.org/[Isis addons] (not ASF).
-
-=== Excel download
-
-The https://github.com/isisaddons/isis-wicket-excel[Excel download add-on] allows the collection to be downloaded as an Excel spreadsheet (`.xlsx`).
-
-* Use the instructions on the add-on module's README to add in the excel download module (ie: update the POM).
-
-=== Fullcalendar2
-
-The https://github.com/isisaddons/isis-wicket-fullcalendar2[Fullcalendar2 download add-on] allows entities to be rendered in a full-page calendar.
-
-* Use the instructions on the add-on module's README to add in the fullcalendar2 module (ie: update the POM).
-* on one of your entities, implement either the `CalendarEventable` interface or the (more complex) `Calendarable` interface.
-* update fixture scripts to populate any new properties
-* when the app is run, a collection of the entities should be shown within a calendar view
-
-=== gmap3
-
-The https://github.com/isisaddons/isis-wicket-gmap3[Gmap3 download add-on] allows entities that implement certain APIs to be rendered in a full-page gmap3.
-
-* Use the instructions on the add-on module's README to add in the gmap3 module (ie: update the POM).
-* on one of your entities, implement the `Locatable` interface
-* update fixture scripts to populate any new properties
-* when the app is run, a collection of the entities should be shown within a map view
-
-
-
-
-== Add-on modules (optional)
-
-In addition to providing Wicket viewer extensions, http://www.isisaddons.org/[Isis addons] also has a large number of modules. These address such cross-cutting concerns as security, command (profiling), auditing and publishing.
-
-* (optional): follow the https://github.com/isisaddons/isis-module-security[security module] README or http://youtu.be/bj8735nBRR4[screencast]
-* (optional): follow the https://github.com/isisaddons/isis-module-command[command module] README or http://youtu.be/g01tK58MxJ8[screencast]
-* (optional): follow the https://github.com/isisaddons/isis-module-audit[auditing module] README or (the same) http://youtu.be/g01tK58MxJ8[screencast]
-
-
-
-
-== View models
-
-In most cases users can accomplish the business operations they need by invoking actions directly on domain entities. For some high-volume or specialized uses cases, though, there may be a requirement to bring together data or functionality that spans several entities.
-
-Also, if using Apache Isis' REST API then the REST client may be a native application (on a smartphone or tablet, say) that is deployed by a third party. In these cases exposing the entities directly would be inadvisable because a refactoring of the domain entity would change the REST API and probably break that REST client.
-
-To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
-
-* build a view model summarizing the state of the app (a "dashboard")
-* write a new `@HomePage` domain service action returning this dashboard viewmodel (and remove the `@HomePage` annotation from any other domain service if present)
-
-
-
-
-== Testing
-
-Up to this point we've been introducing the features of Isis and building out our domain application, but with little regard to testing. Time to fix that.
-
-
-=== Unit testing
-
-Unit testing domain entities and domain services is easy; just use JUnit and mocking libraries to mock out interactions with domain services.
-
-https://code.google.com/p/mockito/[Mockito] seems to be the current favourite among Java developers for mocking libraries, but if you use JMock then you'll find we provide a `JUnitRuleMockery2` class and a number of other utility classes, documented xref:ug.adoc#_ug_testing_unit-test-support[here].
-
-* write some unit tests (adapt from the unit tests in the `myapp-dom` Maven module).
-
-
-
-=== Integration testing
-
-Although unit tests are easy to write and fast to execute, integration tests are more valuable: they test interactions of the system from the outside-in, simulating the way in which the end-users use the application.
-
-Earlier on in the tutorial we commented out the `myapp-integtests` module. Let's commented it back in. In the parent `pom.xml`:
-
-[source,xml]
-----
-<modules>
- <module>dom</module>
- <module>fixture</module>
- <!--
- <module>integtests</module>
- -->
- <module>webapp</module>
-</modules>
-----
-
-change back to:
-
-[source,xml]
-----
-<modules>
- <module>dom</module>
- <module>fixture</module>
- <module>integtests</module>
- <module>webapp</module>
-</modules>
-----
-
-There will probably be some compile issues to fix up once you've done this; comment out all code that doesn't compile.
-
-Isis has great support for writing xref:ug.adoc#_ug_testing_integ-test-support[integration tests]; well-written integration tests should leverage fixture scripts and use the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`@WrapperFactory`] domain service.
-
-* use the tests from the original archetype and the documentation on the website to develop integration tests for your app's functionality.
-
-
-
-
-== Customising the REST API
-
-The REST API generated by Apache Isis conforms to the Restful Objects specification. Apache Isis 1.8.0 provides experimental support to allow the representations to be customized.
-
-* as per xref:ug.adoc#_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
-+
-[source,ini]
-----
-isis.viewer.restfulobjects.objectPropertyValuesOnly=true
-----
-
-
-
-
-== Configuring to use an external database
-
-If you have an external database available, then update the `pom.xml` for the classpath and update the JDBC properties in `WEB-INF\persistor.properties` to point to your database.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
deleted file mode 100644
index cfbb258..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
+++ /dev/null
@@ -1 +0,0 @@
-[[_ug_xxx]]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/cg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cg.adoc b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
new file mode 100644
index 0000000..e36e3df
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
@@ -0,0 +1,36 @@
+[[cg]]
+= Contributors Guide
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+:numbered:
+
+
+[[_cg]]
+== Contributors' Guide
+
+This contributors' guide has three related audiences:
+
+* programmers who want to just use Apache Isis to build applications, and want help setting up their development environment or to build their code from the command line (eg to execute within a continuous integration server such as Jenkins)
+
+* programmers who want to contribute back patches (bug fixes, new features) either to the codebase or the framework's documentation
+
+* committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.
+
+The developer' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. This guide also does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.
+
+
+include::_cg_ide.adoc[leveloffset=+1]
+include::_cg_ide-templates.adoc[leveloffset=+1]
+include::_cg_cmd-line.adoc[leveloffset=+1]
+include::_cg_isis-maven-plugin.adoc[leveloffset=+1]
+
+include::_cg_building-isis.adoc[leveloffset=+1]
+include::_cg_contributing.adoc[leveloffset=+1]
+include::_cg_policies.adoc[leveloffset=+1]
+
+include::_cg_asciidoc.adoc[leveloffset=+1]
+
+include::_cg_committers.adoc[leveloffset=+1]
+
+include::_cg_git-cookbook.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg.adoc b/adocs/documentation/src/main/asciidoc/guides/dg.adoc
deleted file mode 100644
index 07f4a4f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[dg]]
-= Development Environment Guide
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-== Developers' Guide
-
-This developers' guide describes how to set up your development environment to develop your Apache Isis applications either within the xref:dg.adoc#_dg_intellij[IntelliJ] IDE, or within the xref:dg.adoc#_dg_eclipse[Eclipse] IDE, or from the xref:dg.adoc#_dg_cmd-line[command line].
-
-The developer' guide is _not_ intended as a reference manual; for that see the link:rg.html#[Reference Guide]. This guide also does _not_ describe how to actually build an Apache Isis application; for that see the link:ug.html#[Users' Guide].
-
-
-include::_dg_intellij.adoc[leveloffset=+1]
-include::_dg_eclipse.adoc[leveloffset=+1]
-include::_dg_cmd-line.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/building-isis/setting-up-git.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/building-isis/setting-up-git.png b/adocs/documentation/src/main/asciidoc/guides/images/building-isis/setting-up-git.png
new file mode 100644
index 0000000..5ed2a79
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/building-isis/setting-up-git.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow-2.png b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow-2.png
new file mode 100644
index 0000000..28cc822
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow-2.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.png b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.png
new file mode 100644
index 0000000..dde5573
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.pptx b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.pptx
new file mode 100644
index 0000000..e83367b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/git-workflow.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-cloning.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-cloning.png b/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-cloning.png
new file mode 100644
index 0000000..19c222d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-cloning.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-forking.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-forking.png b/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-forking.png
new file mode 100644
index 0000000..3f8ff75
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/contributing/github-forking.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/reference-classes/issue-in-more-detail.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-classes/issue-in-more-detail.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-classes/issue-in-more-detail.png
new file mode 100644
index 0000000..2297838
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-classes/issue-in-more-detail.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/jira-create-release-notes.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/jira-create-release-notes.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/jira-create-release-notes.png
new file mode 100644
index 0000000..2777532
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/jira-create-release-notes.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-release-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-release-1.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-release-1.png
new file mode 100644
index 0000000..a00a1ba
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-release-1.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-0.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-0.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-0.png
new file mode 100644
index 0000000..127d485
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-0.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-1.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-1.png
new file mode 100644
index 0000000..7266ea9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-1.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2.png
new file mode 100644
index 0000000..d4a985a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2a.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2a.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2a.png
new file mode 100644
index 0000000..894c168
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-2a.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-3.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-3.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-3.png
new file mode 100644
index 0000000..8bc439c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-3.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-4.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-4.png b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-4.png
new file mode 100644
index 0000000..c3610b5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/release-process/nexus-staging-4.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
index e53e216..60eb898 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -6,6 +6,7 @@
:numbered:
+[[_rg]]
== Reference Guide
This reference guide describes in detail the various elements of the Apache Isis Programming Model. Most notably these are the xref:rg.adoc#_rg_annotations[annotations] (such as `@DomainObject`), and the reserved and prefix xref:rg.adoc#_rg_methods[methods] (such as `title()` and `validate...()`); it also includes various utility and supporting xref:rg.adoc#_rg_classes[classes].
@@ -14,7 +15,8 @@ This guide also documents the domain services, both those that act as an xref:rg
Also part of the reference manual are the details of how to influence the xref:rg.adoc#_rg_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it catalogues all the various xref:rg.adoc#_rg_runtime[configuration properties] available that influence the behaviour of the framework and the API domain services.
-This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the link:ug.html#[Users' Guide]. The reference guide also does _not_ explain how to setup your development environment; for that see the link:dg.html#[Developers' Guide].
+This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*. The reference guide also does _not_ explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
+
@@ -25,3 +27,4 @@ include::_rg_services-spi.adoc[leveloffset=+1]
include::_rg_classes.adoc[leveloffset=+1]
include::_rg_object-layout.adoc[leveloffset=+1]
include::_rg_runtime.adoc[leveloffset=+1]
+include::_rg_web-xml.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
new file mode 100644
index 0000000..de41bcd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
@@ -0,0 +1,207 @@
+[[simpleapp-archetype]]
+= SimpleApp Archetype
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+
+The quickest way to get started with Apache Isis is to run the simple archetype. This will generate a very simple one-class domain model, called `SimpleObject`, with a single property `name`. There is also a corresponding `SimpleObjectRepository` domain service. From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.
+
+
+
+
+
+== Generating the App
+
+Create a new directory, and `cd` into that directory.
+
+Then run the following command:
+
+[source,bash]
+----
+mvn archetype:generate \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=simpleapp-archetype \
+ -D archetypeVersion=1.8.0 \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp \
+ -D version=1.0-SNAPSHOT \
+ -B
+----
+
+where:
+
+- `groupId` represents your own organization, and
+- `artifactId` is a unique identifier for this app within your organization.
+- `version` is the initial (snapshot) version of your app
+
+The archetype generation process will then run; it only takes a few seconds.
+
+
+
+
+=== Snapshot release
+
+We also maintain the archetype for the most current `-SNAPSHOT`; an app generated with this archetype will contain the latest features of Apache Isis, but the usual caveats apply: some features still in development may be unstable.
+
+The process is almost identical to that for stable releases, however the `archetype:generate` goal is called with slightly different arguments:
+
+[source,bash]
+----
+mvn archetype:generate \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=simpleapp-archetype \
+ -D archetypeVersion=1.9.0-SNAPSHOT \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp \
+ -D version=1.0-SNAPSHOT \
+ -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+ -B
+----
+
+where as before:
+
+- `groupId` represents your own organization, and
+- `artifactId` is a unique identifier for this app within your organization.
+- `version` is the initial (snapshot) version of your app
+
+but also:
+
+- `archetypeVersion` is the SNAPSHOT version of Apache Isis.
+- `archetypeRepository` specifies the location of our snapshot repo (hosted on [CloudBees](http://www.cloudbees.com)), and
+
+The archetype generation process will then run; it only takes a few seconds.
+
+
+
+
+== Building the App
+
+Switch into the root directory of your newly generated app, and build your app:
+
+[source,bash]
+----
+cd myapp
+mvn clean install
+----
+
+where `myapp` is the `artifactId` entered above.
+
+
+
+
+== Running the App
+
+The `simpleapp` archetype generates a single WAR file, configured to run both the link:./guides/ug.html#_ug_wicket-viewer[Wicket viewer] and the link:./guides/ug.html#_ug_restfulobjects-viewer[Restful Objects viewer]. The archetype also configures the JDO/DataNucleus objectstore to use an in-memory HSQLDB connection.
+
+Once you've built the app, you can run the WAR in a variety of ways.
+
+The recommended approach when getting started is to run the self-hosting version of the WAR, allowing Apache Isis to run as a standalone app; for example:
+
+[source,bash]
+----
+java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar
+----
+
+
+
+This can also be accomplished using an embedded Ant target provided in the build script:
+
+
+[source,bash]
+----
+mvn -P self-host antrun:run
+----
+
+
+
+The first is to simply deploying the generated WAR (`webapp/target/myapp-webapp-1.0-SNAPSHOT.war`) to a servlet container.
+
+
+Alternatively, you could run the WAR in a Maven-hosted Jetty instance, though you need to `cd` into the `webapp` module:
+
+[source,bash]
+----
+cd webapp
+mvn jetty:run -D jetty.port=9090
+----
+
+
+In the above, we've passed in a property to indicate a different port from the default port (8080).
+
+Note that if you use `mvn jetty:run`, then the context path changes; check the console output (eg [http://localhost:9090/myapp-webapp](http://localhost:9090/myapp-webapp)).
+
+Finally, you can also run the app by deploying to a standalone servlet container such as [Tomcat](http://tomcat.apache.org).
+
+
+
+
+=== With Fixtures
+
+It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory
+testing. This is done by specifying a _fixture script_ on the command line:
+
+
+[source,bash]
+----
+java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar \
+ --initParam isis.persistor.datanucleus.install-fixtures=true \
+ --initParam isis.fixtures=fixture.simple.SimpleObjectsFixture
+----
+
+
+where (in the above example) `fixture.simple.SimpleObjectsFixture` is the fully qualified class name of the fixture
+script to be run.
+
+
+
+
+== Using the App
+
+The archetype provides a welcome page that explains the classes and files generated, and provides detailed guidance and what to do next.
+
+The app itself is configured to run using shiro security, as configured in the `WEB-INF/shiro.ini` config file. To log in, use `sven/pass`.
+
+
+
+== Modifying the App
+
+Once you are familiar with the generated app, you'll want to start modifying it. Check out our the link:.guides/ug.html[Users' Guide], which has how-tos and a complete reference guide (as well as some background concepts and discussion of more advanced techniques).
+
+If you use IntelliJ or Eclipse, you'll also want to set up your IDE; this is also described in the link:cg.adoc#_cg_ide[Contributors' Guide].
+
+
+== App Structure
+
+As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename `SimpleObject` to `Customer`) without having to waste time deleting lots of generated code.
+
+
+.Table caption
+[cols="1,1a", options="header"]
+|===
+| Module
+| Description
+
+
+|myapp
+|The parent (aggregator) module
+
+|myapp-dom
+|The domain object model, consisting of <tt>SimpleObject</tt> and <tt>SimpleObjects</tt> (repository) domain service.
+
+|myapp-fixture
+|Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
+
+|myapp-integtests
+|End-to-end integration tests, that exercise from the UI through to the database
+
+|myapp-webapp
+|Run as a webapp (from `web.xml`) using either the Wicket viewer or the RestfulObjects viewer
+
+|===
+
+
+If you run into issues, please don't hesitate to ask for help on the link:../../support.html[users mailing list].
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/tg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/tg.adoc b/adocs/documentation/src/main/asciidoc/guides/tg.adoc
new file mode 100644
index 0000000..20b6517
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/tg.adoc
@@ -0,0 +1,22 @@
+[[tg]]
+= Tutorials
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+[[_tg]]
+== Tutorials
+
+This page contains a couple of tutorials for you to follow.
+
+* the "petclinic" tutorial takes you step-by-step through building a simple application of just three classes. There are example solutions in the github repo in case you get lost.
+
+* the "stop scaffolding, start coding" tutorial is taken from a conference workshop. It has less hand-holding, but lists out the steps for you to follow. It's a good cookbook to follow when you're readng to take things further.
+
+Have fun!
+
+
+
+include::_tg_pet-clinic.adoc[leveloffset=+1]
+include::_tg_stop-scaffolding-start-coding.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index 7a55ccb..497339e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -6,6 +6,7 @@
:numbered:
+[[_ug]]
== Users' Guide
This users' guide introduces the xref:ug.adoc#_ug_core-concepts[core concepts] and ideas behind Apache Isis, tells you how to xref:ug.adoc#_ug_getting-started[get started] with a Maven archetype, and provides xref:ug.adoc#_ug_how-tos[how-to]s and xref:ug.adoc#_ug_more-advanced[more advanced] guidance on writing maintainable larger applications.
@@ -14,13 +15,13 @@ It goes on to discuss the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], both fr
Later chapters discuss essential topics such as xref:ug.adoc#_ug_testing[testing] and how to xref:ug.adoc#_ug_deployment[deploy] your app, and discuss other ways in which you can xref:ug.adoc#_ug_extending[extend] or adapt the framework itself to your particular needs.
-The users' guide is _not_ intended as a reference manual; for that see the link:rg.html#[Reference Guide]. The users' guide also does _not_ explain how to setup your development environment; for that see the link:dg.html#[Developers' Guide].
+The users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. The users' guide also does _not_ explain how to setup your development environment; for that see the *link:cg.adoc#_cg[Contributors' Guide]*.
+
include::_ug_core-concepts.adoc[leveloffset=+1]
include::_ug_getting-started.adoc[leveloffset=+1]
-include::_ug_tutorials.adoc[leveloffset=+1]
include::_ug_how-tos.adoc[leveloffset=+1]
include::_ug_more-advanced.adoc[leveloffset=+1]
@@ -29,9 +30,8 @@ include::_ug_wicket-viewer.adoc[leveloffset=+1]
include::_ug_restfulobjects-viewer.adoc[leveloffset=+1]
include::_ug_security.adoc[leveloffset=+1]
-include::_ug_isis-maven-plugin.adoc[leveloffset=+1]
-include::_ug_deployment.adoc[leveloffset=+1]
include::_ug_testing.adoc[leveloffset=+1]
+include::_ug_deployment.adoc[leveloffset=+1]
include::_ug_headless-access.adoc[leveloffset=+1]
include::_ug_extending.adoc[leveloffset=+1]
include::_ug_troubleshooting.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/help.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/help.adoc b/adocs/documentation/src/main/asciidoc/help.adoc
index 280cc08..10d1367 100644
--- a/adocs/documentation/src/main/asciidoc/help.adoc
+++ b/adocs/documentation/src/main/asciidoc/help.adoc
@@ -16,7 +16,7 @@ pass:[<br/><br/><br/>]
* link:https://issues.apache.org/jira/browse/ISIS[JIRA]
* link:http://github.com/apache/isis[Github mirror]
* link:http://stackoverflow.com/questions/tagged/isis[Stack Overflow] (tagged=isis)
-* link:contributing.html[How to contribute]
+* link:guides/cg.html#_cg_contributing[How to contribute]
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/building-isis/setting-up-git.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/building-isis/setting-up-git.png b/adocs/documentation/src/main/asciidoc/images/building-isis/setting-up-git.png
deleted file mode 100644
index 5ed2a79..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/building-isis/setting-up-git.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow-2.png b/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow-2.png
deleted file mode 100644
index 28cc822..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow-2.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.png b/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.png
deleted file mode 100644
index dde5573..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.pptx b/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.pptx
deleted file mode 100644
index e83367b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/git-workflow.pptx and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/github-cloning.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/github-cloning.png b/adocs/documentation/src/main/asciidoc/images/contributing/github-cloning.png
deleted file mode 100644
index 19c222d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/github-cloning.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/contributing/github-forking.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/contributing/github-forking.png b/adocs/documentation/src/main/asciidoc/images/contributing/github-forking.png
deleted file mode 100644
index 3f8ff75..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/contributing/github-forking.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/jira-create-release-notes.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/jira-create-release-notes.png b/adocs/documentation/src/main/asciidoc/images/release-process/jira-create-release-notes.png
deleted file mode 100644
index 2777532..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/jira-create-release-notes.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-release-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-release-1.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-release-1.png
deleted file mode 100644
index a00a1ba..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-release-1.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-0.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-0.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-0.png
deleted file mode 100644
index 127d485..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-0.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-1.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-1.png
deleted file mode 100644
index 7266ea9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-1.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2.png
deleted file mode 100644
index d4a985a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2a.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2a.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2a.png
deleted file mode 100644
index 894c168..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-2a.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-3.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-3.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-3.png
deleted file mode 100644
index 8bc439c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-3.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/8ad6101a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-4.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-4.png b/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-4.png
deleted file mode 100644
index c3610b5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/images/release-process/nexus-staging-4.png and /dev/null differ