You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/31 07:11:22 UTC
[46/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/books.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/books.adoc b/adocs/documentation/src/main/asciidoc/books.adoc
deleted file mode 100644
index 1e61678..0000000
--- a/adocs/documentation/src/main/asciidoc/books.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[books]]
-= Books
-: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
-
-
-Although it has evolved since, the _Apache Isis_ framework started out as an open source implementation of the naked objects pattern.
-Indeed, the generic user interfaces provided by Apache Isis link:../../components/viewers/wicket/about.html[Wicket] viewer and the link:../../components/viewers/restfulobjects/about.html[Restful Objects] viewer are both "just" naked objects implementations; the first serves up a default generic representation of domain objects for human interaction, the latter serving up representation intended for machine consumption rather than human beings.
-
-If the idea of naked objects is of interest, then there are a couple of books on the topic that you might want to read.
-
-
-== Naked Objects
-
-Richard Pawson and Robert Matthews, Wiley 2002
-
-
-image::{_imagesdir}/books/nakedobjects-book.jpg[width="159px",link="{_imagesdir}/books/nakedobjects-book.jpg"]
-
-
-This book describes the original ideas of Naked Objects.
-Although based on a very early version of the framework, it's still definitely worth a read (and beautifully produced).
-
-Amazon quotes: (avg 5 stars)
-
-* Brilliant argument and toolkit for information systems
-* Most thoughtful and beautiful technical book I have read
-* Excellent presentation of an innovative practical idea
-
-The book is freely available online http://www.nakedobjects.org/book/[here]. Or, you can get a hardcopy of the book at http://eu.wiley.com/WileyCDA/WileyTitle/productCd-0470844205.html[Wiley (publisher)] and http://www.amazon.com/Naked-Objects-Richard-Pawson/dp/0470844205[Amazon].
-
-
-
-
-== Domain Driven Design using Naked Objects
-
-Dan Haywood, Pragmatic Bookshelf 2009
-
-image::{_imagesdir}/books/dhnako.jpg[width="167px",link="{_imagesdir}/books/dhnako.jpg"]
-
-This more recent book draws the parallel between domain-driven design and Naked Objects (4.0).
-In the spirit of the Pragmatic Bookshelf, it's a practical, hands-on sort of book, building up a case study as it goes and encouraging you to build your own app as you go.
-
-
-Amazon quotes: (avg 4.5 stars)
-
-* Important Contribution to Domain-Driven Design
-* The easy-to-learn Naked Objects Framework .. provide[s] a masterful exposition on DDD
-* Clear and passionate book about a great subject
-* Excellent book and a great framework
-
-You can find the book at http://www.pragprog.com/titles/dhnako/domain-driven-design-using-naked-objects[Pragmatic Bookshelf (publisher)] and http://www.amazon.com/Domain-Driven-Design-Objects-Pragmatic-Programmers/dp/1934356441[Amazon].
-
-
-
-
-== Restful Objects Specification
-
-Dan Haywood
-
-The http://restfulobjects.org[Restful Objects specification] defines a set of RESTful resources, and corresponding JSON representations, for accessing and manipulating a domain object model.
-
-This is a comprehensive specification, running to over 200 pages in length.
-It is implemented by Apache Isis' link:../../components/viewers/restfulobjects/about.html[Restful Objects] viewer, and is also implemented by another (non-Apache) open source project, http://nakedobjects.codeplex.com[Naked Objects MVC].
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/cheat-sheet.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/cheat-sheet.adoc b/adocs/documentation/src/main/asciidoc/cheat-sheet.adoc
deleted file mode 100644
index 2b92080..0000000
--- a/adocs/documentation/src/main/asciidoc/cheat-sheet.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[cheat-sheet]]
-= Cheat Sheet
-: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 "one-pager" cheat sheet summarises the main programming conventions to follow when writing an Apache Isis application.
-
-pass:[<br/>]
-
-
-image::{_imagesdir}cheat-sheets/cover.png[width="800px",link="resources/cheat-sheets/IsisCheatSheet.pdf"]
-
-
-pass:[<br/>]
-
-You can download the cheat sheet as either a link:resources/cheat-sheets/IsisCheatSheet.pdf[Acrobat PDF] or as an link:resources/cheat-sheets/IsisCheatSheet.docx[MS Word .docx] file.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/common-use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/common-use-cases.adoc b/adocs/documentation/src/main/asciidoc/common-use-cases.adoc
deleted file mode 100644
index 7332107..0000000
--- a/adocs/documentation/src/main/asciidoc/common-use-cases.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[common-use-cases]]
-= Common Use Cases
-: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
-
-
-
-== Prototyping
-
-Apache Isis is great for rapid prototyping, because all you need to write in order to get an application up-and-running is the domain model objects.
-
-By focussing just on the domain, you'll also find that you start to develop a ubiquitous language - a set of terms and concepts that the entire team (business and technologists alike) have a shared understanding.
-
-Once you've sketched out your domain model, you can then either start-over using your preferred framework, or you might choose to take the domain model forward into more formal specification and testing.
-
-
-
-
-
-== Deploy as an human-usable webapp
-
-One of the original motivations for Apache Isis itself was to be able automatically generate a user interface for a domain object model.
-
-Apache Isis' has a pluggable architecture allowing different user interface technologies. The principal implementation (as configured by the link:./simple-archetype.html[simple archetype]) is the link:guides/ugvw.html#[Wicket viewer]. This provides an appealing default user interface, with the ability to customize the user interface by writing new http://wicket.apache.org[Apache Wicket] components. Some third-party components can be found in the (non-ASF) link:http://isisaddons.org[Isis Addons] (non-ASF) project, integrating the Wicket viewer with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and a https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.
-
-
-Deploying on Apache Isis means that the framework also manages object persistence. Again this is pluggable, but the principal implementation is the JDO/DataNucleus objectstore. Because JDO supports both SQL and NoSQL databases, you can then deploy on a variety of platforms, including the link:https://developers.google.com/appengine/[Google App Engine (GAE)] and link:http://neo4j.com/[Neo4J].
-
-
-
-
-== Deploy as a RESTful web service
-
-REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.
-
-The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' link:guides/ugvro.html#[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
-
-There are two main use cases for deploying Apache Isis as a RESTful web service are:
-
-* to allow a custom UI to be built against the RESTful API
-
-For example, using Javascript/JQuery, or an RIA technology such as Flex, JavaFX, Silverlight
-
-* to enable integration between systems
-
-REST is designed to be machine-readable, and so is an excellent choice for synchronous data interchange scenarios.
-
-As for the auto-generated webapps, the framework manages object persistence, for example using the JDO/DataNucleus objectstore. It is perfectly possible to deploy the RESTful API alongside an auto-generated webapp; both work from the same domain object model.
-
-
-
-
-== Deploy on your own platform
-
-The programming model defined by Apache Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Apache Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`. The idea is to make it easy to be able to write take a domain object prototyped and/or tested using Apache Isis, but to deploy on some other framework's runtime.
-
-If you are interested in taking this approach, note that there is one important interface that must be implemented by your own framework, namely `DomainObjectContainer`. This interface represents the one-and-only "touchpoint" between the domain objects and the runtime. If you inspect the methods then you'll see it covers such concerns as persistence, and of raising warnings or errors.
-
-Apache Isis' own runtime injects an (implementation of this) interface into each and every domain object. You will likely need to do something similar within your own framework, (or come up with an equivalent mechanism, eg Service Locator pattern).
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index fb9a535..7779676 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -25,24 +25,24 @@ pass:[<br/>]
| *What is Apache Isis?*
-* *link:./isis-in-pictures.html[What is Apache Isis?^] ... in pictures*
-* link:./powered-by.html[Powered by Apache Isis^]
-* link:./how-isis-works.html[How Apache Isis Works^] image:{_imagesdir}tv_show-25.png[width="25px" link="how-isis-works.html"]
-* link:./common-use-cases.html[Common Use Cases^]
+* *link:./pages/isis-in-pictures/isis-in-pictures.html[What is Apache Isis?^] ... in pictures*
+* link:./pages/powered-by/powered-by.html[Powered by Apache Isis^]
+* link:./pages/how-isis-works/how-isis-works.html[How Apache Isis Works^] image:{_imagesdir}tv_show-25.png[width="25px" link="how-isis-works./how-isis-works.html"]
+* link:./pages/common-use-cases/common-use-cases.html[Common Use Cases^]
|*Learning More*
-* link:./screencasts.html[Screencasts^] image:{_imagesdir}tv_show-25.png[width="25px" link="screencasts.html"]
-* link:./guides/tg.html[Tutorials^]
-* link:http://www.javadoc.io/doc/org.apache.isis.core/isis-core-applib/1.11.0[Javadoc (for Applib)^] (not ASF)
+* link:./pages/screencasts/screencasts.html[Screencasts^] image:{_imagesdir}tv_show-25.png[width="25px" link="./pages/screencasts/screencasts.html"]
+* link:./pages/tg/tg.html[Tutorials^]
+//* link:http://www.javadoc.io/doc/org.apache.isis.core/isis-core-applib/1.14.0[Javadoc (for Applib)^] (not ASF)
|*Resources:*
-* *link:./cheat-sheet.html[Cheat Sheet^]*
-* link:./icons.html[Icons^]
+* *link:./pages/cheat-sheet/cheat-sheet.html[Cheat Sheet^]*
+* link:./pages/icons/icons.html[Icons^]
*3rd-party add-ons (not ASF)*
@@ -58,36 +58,36 @@ pass:[<br/>]
|*User Guides:*
-* *link:./guides/ugfun.html[Fundamentals^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugfun.pdf"]
-* link:./guides/ugvw.html[Wicket Viewer^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugvw.pdf"]
-* link:./guides/ugvro.html[Restful Objects Viewer^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugvro.pdf"]
-* link:./guides/ugodn.html[DataNucleus Object Store^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugvro.pdf"]
-* link:./guides/ugsec.html[Security^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugsec.pdf"]
-* *link:./guides/ugtst.html[Testing^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugtst.pdf"]
-* link:./guides/ugbtb.html[Beyond the Basics^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugbtb.pdf"]
+* *link:./guides/ugfun/ugfun.html[Fundamentals^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugfun/ugfun.pdf"]
+* link:./guides/ugvw/ugvw.html[Wicket Viewer^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugvw/ugvw.pdf"]
+* link:./guides/ugvro/ugvro.html[Restful Objects Viewer^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugvro/ugvro.pdf"]
+* link:./guides/ugodn/ugodn.html[DataNucleus Object Store^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugvro/ugvro.pdf"]
+* link:./guides/ugsec/ugsec.html[Security^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugsec/ugsec.pdf"]
+* *link:./guides/ugtst/ugtst.html[Testing^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugtst/ugtst.pdf"]
+* link:./guides/ugbtb/ugbtb.html[Beyond the Basics^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/ugbtb/ugbtb.pdf"]
|*Reference Guides:*
-* *link:./guides/rgant.html[Annotations^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgant.pdf"]
-* *link:./guides/rgsvc.html[Domain Services^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgsvc.pdf"]
-* link:./guides/rgcfg.html[Core Config'n Properties^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgcfg.pdf"]
-* link:./guides/rgcms.html[Classes, Methods and Schema^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgcms.pdf"]
-* link:./guides/rgmvn.html[Apache Isis Maven plugin^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgmvn.pdf"]
-* link:./guides/rgfis.html[Framework Internal Services^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/fwsvc.pdf"]
+* *link:./guides/rgant/rgant.html[Annotations^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgant/rgant.pdf"]
+* *link:./guides/rgsvc/rgsvc.html[Domain Services^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgsvc/rgsvc.pdf"]
+* link:./guides/rgcfg/rgcfg.html[Core Config'n Properties^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgcfg/rgcfg.pdf"]
+* link:./guides/rgcms/rgcms.html[Classes, Methods and Schema^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgcms/rgcms.pdf"]
+* link:./guides/rgmvn/rgmvn.html[Apache Isis Maven plugin^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgmvn/rgmvn.pdf"]
+* link:./guides/rgfis/rgfis.html[Framework Internal Services^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/fwsvc/rgfis.pdf"]
|*"Supporting" Guides:*
-* *link:./guides/dg.html[Developers' Guide^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/dg.pdf"]
-** Setting up link:./guides/dg.html#_dg_ide_intellij[IntelliJ^] or link:./guides/dg.html#_dg_ide_eclipse[Eclipse^]
-** link:./guides/dg.html#_dg_contributing[Contributing patches^] (pull requests)
-** link:./guides/dg.html#_dg_asciidoc-syntax[Asciidoc syntax^]
+* *link:./guides/dg/dg.html[Developers' Guide^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/dg/dg.pdf"]
+** Setting up link:./guides/dg/dg.html#_dg_ide_intellij[IntelliJ^] or link:./guides/dg/dg.html#_dg_ide_eclipse[Eclipse^]
+** link:./guides/dg/dg.html#_dg_contributing[Contributing patches^] (pull requests)
+** link:./guides/dg/dg.html#_dg_asciidoc-syntax[Asciidoc syntax^]
-* link:./guides/cgcom.html[Committers' Guide^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/cgcom.pdf"]
-** link:./guides/cgcom.html#_cgcom_cutting-a-release[Cutting a release^]
-** link:./guides/cgcom.html#_cgcom_verifying-releases[Verifying a release^]
+* link:./guides/cgcom/cgcom.html[Committers' Guide^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/cgcom/cgcom.pdf"]
+** link:./guides/cgcom/cgcom.html#_cgcom_cutting-a-release[Cutting a release^]
+** link:./guides/cgcom/cgcom.html#_cgcom_verifying-releases[Verifying a release^]
@@ -101,8 +101,8 @@ pass:[<br/>]
|*Releases:*
-* link:release-notes.html[Release Notes^]
-* link:migration-notes.html[Migration Notes^]
+* link:./release-notes/release-notes.html[Release Notes^]
+* link:./migration-notes/migration-notes.html[Migration Notes^]
*Get involved!*
@@ -112,10 +112,10 @@ pass:[<br/>]
|*Going Deeper:*
-* link:./articles-and-presentations.html[Articles, Conferences, Podcasts^]
-* link:./books.html[Books^]
-* link:./resources/thesis/Pawson-Naked-Objects-thesis.pdf[Naked Objects PhD thesis^] (Pawson)
-//* link:./downloadable-presentations.html[Downloadable Presentations]
+* link:./pages/articles-and-presentations/articles-and-presentations.html[Articles, Conferences, Podcasts^]
+* link:./pages/books/books.html[Books^]
+* link:./guides/ugfun/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf[Naked Objects PhD thesis^] (Pawson)
+//* link:./downloadable-presentations/downloadable-presentations.html[Downloadable Presentations]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/downloadable-presentations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/downloadable-presentations.adoc b/adocs/documentation/src/main/asciidoc/downloadable-presentations.adoc
deleted file mode 100644
index ac9a00e..0000000
--- a/adocs/documentation/src/main/asciidoc/downloadable-presentations.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[downloadable-presentations]]
-= Downloadable Presentations
-: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 following presentation, available in multiple formats, provides some background on Apache Isis:
-
-* Introduction to Apache Isis (link:resources/downloadable-presentations/IntroducingApacheIsis.pptx[pptx], link:resources/downloadable-presentations/IntroducingApacheIsis.ppt[ppt], link:resources/downloadable-presentations/IntroducingApacheIsis.odp[odp], link:resources/downloadable-presentations/IntroducingApacheIsis-slides.pdf[pdf slides], link:resources/downloadable-presentations/IntroducingApacheIsis-notes.pdf[pdf notes])
-
-
-[WARNING]
-====
-This presentation is somewhat out-of-date...
-====
-
-
-Feel free to use/adapt as you see fit.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_cgcom-applying-patches.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcom-applying-patches.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcom-applying-patches.adoc
deleted file mode 100644
index 71c2e69..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cgcom-applying-patches.adoc
+++ /dev/null
@@ -1,90 +0,0 @@
-[[_cgcom_applying-patches]]
-= Applying Patches
-:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-
-If a patch is received on a JIRA ticket, then it should be reviewed and applied. The commands are slightly different for diff files vs patch files.
-
-
-
-
-== Diff files
-
-If a diff file has been provided, then it can easily be applied using eGit's wizards (Eclipse's Git integration)\u2026
-
-NOTE: TODO - this stuff needs fleshing out ...
-
-
-
-
-== Patch files
-
-If a patch file has been provided, then it can be applied using command line tools.
-
-=== Inspect the patch
-
-First, take a look at what changes are in the patch. You can do this easily with `git apply`
-
-[source,bash]
-----
-git apply --stat ISIS-xxx.patch
-----
-
-Note that this command does not apply the patch, but only shows you the stats about what it�\u20ac\u2122ll do. After peeking into the patch file with your favorite editor, you can see what the actual changes are.
-
-Next, you're interested in how troublesome the patch is going to be. Git allows you to test the patch before you actually apply it.
-
-[source,bash]
-----
-git apply --check ISIS-xxx.patch
-----
-
-If you don't get any errors, the patch has no conflicts. Otherwise you may see what trouble you�\u20ac\u2122ll run into.
-
-
-=== Apply a (clean) patch
-
-To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`:
-
-[source,bash]
-----
-git am --signoff < ISIS-xxx.patch
-----
-
-This preserves the original author's commit message.
-
-However, this can fail if the patch file does not contain the original committers email address. In this case you will need to abort the `am` session:
-
-[source,bash]
-----
-git am abort
-----
-
-and continue on by applying a non-clean patch, as described next.
-
-
-
-=== Apply a (non-clean) patch
-
-If the patch does not apply cleanly, then the original authors commit message cannot be preserved. This sequence in this case is:
-
-[source,bash]
-----
-git apply ISIS-xxx.patch
-----
-
-Fix up any issues. The add and commit as usual
-
-[source,bash]
-----
-git add .
-git commit -am "<original authors' commit message>" --signoff
-----
-
-The `--signoff` simply adds a line to the commit message indicating you have signed off the commit.
-
-Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_cgcom_asciidoc-publish-procedure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcom_asciidoc-publish-procedure.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcom_asciidoc-publish-procedure.adoc
deleted file mode 100644
index f4bca52..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cgcom_asciidoc-publish-procedure.adoc
+++ /dev/null
@@ -1,100 +0,0 @@
-[[_cgcom_publishing-the-docs]]
-= Publishing the Docs
-
-:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-Apache Isis' documentation (meaning the website and the users' guide, the reference guide and this contributors' guide) is written using link:http://www.methods.co.nz/asciidoc/[Asciidoc], specifically the link:asciidoctor.org/[Asciidoctor] implementation.
-
-The website and guides are created by running build tools (documented below) which create the HTML version of the site and guides.
-You can therefore easily check the documentation before raising a pull request (as a contributor) or publishing the site (if a committer).
-
-For details of authoring/updating the documents and website, see the xref:dg.adoc#_dg_asciidoc[developers' guide].
-To help write the Asciidoc text itself, we provide some xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates].
-
-Publishing is performed by copying the generated HTML to a different git repository (link:https://git-wip-us.apache.org/repos/asf?p=isis-site.git[isis-site]).
-This is synced by ASF infrastructure over to link:http://isis.apache.org[isis.apache.org].
-This can only be done by Apache Isis committers, and is discussed below.
-
-
-
-== One-time setup
-
-The generated site is published by copying into the `content/` directory of the https://git-wip-us.apache.org/repos/asf/isis-site.git[isis-site git repo]. You therefore need to check this out this repo.
-
-The procedure assumes that two git repos (for https://git-wip-us.apache.org/repos/asf/isis.git[isis] itself and for isis-site) are checked out into the same parent directory, eg:
-
-[source]
-----
-/APACHE/
- isis/ # checkout of isis.git
- adocs/
- documentation/
- README.adoc # this file you are reading right now
- ...
- isis-site/ # checkout of isis-site.git
- content/ # the published website
-----
-
-If this isn't the case, then it is possible to override the relative directory by passing in a system property to the mvn goal; see below.
-
-You also need to know that ASF's publishing script work from the 'asf-site' branch, NOT from the 'master' branch. Therefore, in the `isis.git` repo site:
-
-[source,bash]
-----
-git checkout asf-site
-----
-
-== Publishing (full build)
-
-Back in the `adocs/documentation` directory of the main `isis-git.repo`, to copy the generated documents to the `isis-site.git` repo, run:
-
-[source,bash]
-----
-mvn clean package
-----
-
-This deletes the entire content of `contents`, and replaces with the content under `target/site`. It also fixes up line endings, standardizing on unix-style LFs.
-
-[TIP]
-====
-If you have checked out the `isis-site.git` repo into some other directory (relative to `isis.site.git), then this can be overridden by specifying `-Disis-site.dir=...` when calling `mvn`.
-====
-
-
-To copy and to also commit the generated documents to the `isis-site.git` repo , run:
-
-[source,bash]
-----
-sh publish.sh "ISIS-nnnn: a custom commit message"
-----
-
-Behind the scenes this just calls `mvn clean install -Dmessage=...`.
-
-It's also possible to omit the message, in which case `publish.sh` will reuse the most recent commit message from the main `isis.git` repo.
-
-Pushing the commits (in the `isis-site.git` directory, of course) will publishing the changes:
-
-[source,bash]
-----
-git push
-----
-
-Double check at http://isis.apache.org[isis.apache.org].
-
-
-
-
-== Publishing (partial build)
-
-If none of the guides have been changed, and if you have run the full rebuild recently, then you can skip the generation of PDFs using:
-
-[source,bash]
-----
-mvn install -Dskip.pdf -D"ISIS-nnnn: a custom commit message"
-----
-
-The `clean` goal *must not* be included though (else all the guides will disappear from the site content).
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_cgcom_cutting-a-release.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcom_cutting-a-release.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcom_cutting-a-release.adoc
deleted file mode 100644
index cae724e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cgcom_cutting-a-release.adoc
+++ /dev/null
@@ -1,723 +0,0 @@
-[[_cgcom_cutting-a-release]]
-= Cutting a Release
-:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-The release process consists of:
-
-* the release manager cutting the release (documented below)
-* Members of the Apache Isis PMC xref:cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
-* the release manager performing post-release tasks, for either a xref:cgcom.adoc#_cgcom_post-release-successful[successful] or an xref:cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote.
-
-Apache Isis itself consists of two separately releasable modules; relative to the link:https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=tree[source code root] there are:
-
-* `core`
-* `component/example/archetypes/simpleapp`
-
-This section details the process for formally releasing Isis modules. It describes the process for both `core` and then the archetype. The subsequent sections describe how other committers can xref:cgcom.adoc#_cgcom_verifying-releases[verify a release] and how the release manager can then perform xref:cgcom.adoc#_cgcom_post-release[post-release] activities and set up for the next development iteration.
-
-If you've not performed a release before, then note that there are some configuration xref:cgcom.adoc#_cgcom_release-process-prereqs[prerequisites] that must be configured first. In particular, you'll need signed public/private keys, and the ASF Nexus staging repo inlocal `~/.m2/settings.xml` file.
-
-These release notes using bash command line tools. They should work on Linux and MacOS; for Windows, use mSysGit.
-
-
-
-
-[[__cgcom_cutting-a-release_obtain-consensus]]
-== Obtain Consensus
-
-Before releasing `core`, ensure there is consensus on the link:../support.html[dev mailing list] that this is the right time for a release. The discussion should include confirming the version number to be used, and to confirm content.
-
-These discussions should also confirm the version number of the module being released. This should be in line with our xref:cgcom.adoc#_cgcom_versioning-policy[semantic versioning policy].
-
-
-Make sure you have a JIRA ticket open against which to perform all commits. In most cases a JIRA ticket will have been created at the beginning of the previous release cycle.
-
-
-
-[[__cgcom_cutting-a-release_set-environment-variables]]
-== Set environment variables
-
-We use environment variables to parameterize as many of the steps as possible. For example:
-
-[source,bash]
-----
-cd core
-export ISISTMP=/c/tmp # <1>
-export ISISDEV=1.16.0-SNAPSHOT
-export ISISREL=1.15.0
-export ISISRC=RC1
-export ISISBRANCH=release-$ISISREL-$ISISRC
-export ISISJIRA=ISIS-9999 # <2>
-export CATALINA_HOME=/c/java/apache-tomcat-8.0.30 # <3>
-
-env | grep ISIS | sort
-----
-<1> adjust by platform
-<2> set to an "umbrella" ticket for all release activities. (One should exist already, xref:cgcom.adoc#__cgcom_post-release-successful_update-jira_create-new-jira[created at] the beginning of the development cycle now completing).
-<3> adjust as required (Tomcat is used to smoke test the simpleapp archetype)
-
-Obviously, alter `$ISISDEV` and `$ISISREL` as required, and bump `$ISISRC` for re-releasing following an xref:cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] releases.
-
-[IMPORTANT]
-====
-Note that the branch name is *not* the same any of the eventual tag names (eg `isis-1.15.0` or `simpleapp-archetype-1.15.0`).
-
-If they did have the same name, then what would happen is that the `maven-release-plugin` would checkout the (HEAD of the) branch and thus upload a SNAPSHOT to the snapshot repository. What it should of course do is checkout the tag and then upload that to the release staging repository.
-====
-
-
-
-[[__cgcom_cutting-a-release_pull-down-code-to-release]]
-== Pull down code to release
-
-Set the HEAD of your local git repo to the commit to be released. This will usually be the tip of the origin's `master` branch. Then, create a release branch for the version number being released; eg:
-
-[source,bash]
-----
-git checkout master
-git pull --ff-only
-git checkout -b $ISISBRANCH
-----
-
-All release preparation is done locally; if we are successful, this branch will be merged back into master.
-
-
-Double check that the version number of the parent pom should reflect the branch name that you are now on (with a `-SNAPSHOT` suffix). his will normally have been done already during earlier development; but confirm that it has been updated. If it has not, make the change.
-
-Double check that the version number of the core POM (`core/pom.xml`) should reflect the branch name that you are now on. For example, if releasing version `1.15.0`, the POM should read:
-
-[source,xml]
-----
-<groupId>org.apache.isis.core</groupId>
-<artifactId>isis</artifactId>
-<version>1.16.0-SNAPSHOT</version>
-----
-
-Also, check that there are no snapshot dependencies:
-
-[source,bash]
-----
-grep SNAPSHOT `/bin/find . -name pom.xml | grep -v target | grep -v mothball | sort`
-----
-
-The only mention of `SNAPSHOT` should be for the Isis modules about to be released.
-
-[TIP]
-====
-Obviously, don't update Apache Isis' `SNAPSHOT` references; these get updated by the `mvn release:prepare` command we run later.
-====
-
-
-
-[[__cgcom_cutting-a-release_releasing-core]]
-== Releasing Core
-
-First, we release `core`. Switch to the appropriate directory:
-
-[source,bash]
-----
-cd core
-----
-
-[[__cgcom_cutting-a-release_releasing-core_set-environment-variables]]
-=== Set environment variables
-
-Set additional environment variables for the core "artifact":
-
-[source,bash]
-----
-export ISISART=isis
-export ISISCOR="Y"
-
-env | grep ISIS | sort
-----
-
-
-
-[[__cgcom_cutting-a-release_releasing-core_license-headers]]
-=== License headers
-
-The Apache Release Audit Tool `RAT` (from the http://creadur.apache.org[Apache Creadur] project) checks for missing license header files. The parent `pom.xml` of each releasable module specifies the RAT Maven plugin, with a number of custom exclusions.
-
-To run the RAT tool, use:
-
-[source,bash]
-----
-mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o && \
-for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done || \
-for a in `/bin/find . -name rat.txt -print`; do grep '!AL' $a; done
-----
-
-where `rat.numUnapprovedLicenses` property is set to a high figure, temporarily overriding the default value of 0. This will allow the command to run over all submodules, rather than failing after the first one. The command writes out a `target\rat.txt` for each submodule. missing license notes are indicated using the key `!???`. The `for` command collates all the errors.
-
-Investigate and fix any reported violations, typically by either:
-
-* adding genuinely missing license headers from Java (or other) source files, or
-* updating the `<excludes>` element for the `apache-rat-plugin` plugin to ignore test files, log files and any other non-source code files
-* also look to remove any stale `<exclude>` entries
-
-To add missing headers, use the groovy script `addmissinglicenses.groovy` (in the `scripts` directory) to automatically insert missing headers for certain file types. The actual files checked are those with extensions specified in the line `def fileEndings = [".java", ".htm"]`:
-
-[source,bash]
-----
-groovy ../scripts/addmissinglicenses.groovy -x
-----
-
-(If the `-x` is omitted then the script is run in "dry run" mode). Once you've fixed all issues, confirm once more that `apache-rat-plugin` no longer reports any license violations, this time leaving the `rat.numUnapprovedLicenses` property to its default, 0:
-
-[source,bash]
-----
-mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=0 -o && \
-for a in `find . -name rat.txt -print`; do grep '!???' $a; done
-----
-
-
-[[__cgcom_cutting-a-release_releasing-core_missing-license-check]]
-=== Missing License Check
-
-Although Apache Isis has no dependencies on artifacts with incompatible licenses, the POMs for some of these dependencies (in the Maven central repo) do not necessarily contain the required license information. Without appropriate additional configuration, this would result in the generated `DEPENDENCIES` file and generated Maven site indicating dependencies as having "unknown" licenses.
-
-Fortunately, Maven allows the missing information to be provided by configuring the `maven-remote-resources-plugin`. This is stored in the `src/main/appended-resources/supplemental-models.xml` file, relative to the root of each releasable module.
-
-To capture the missing license information, use:
-
-[source,bash]
-----
-mvn license:download-licenses && \
-groovy ../scripts/checkmissinglicenses.groovy
-----
-
-The Maven plugin creates a `license.xml` file in the `target/generated-resources` directory of each module. The script then searches for these `licenses.xml` files, and compares them against the contents of the `supplemental-models.xml` file.
-
-For example, the output could be something like:
-
-[source,bash]
-----
-licenses to add to supplemental-models.xml:
-
-[org.slf4j, slf4j-api, 1.5.7]
-[org.codehaus.groovy, groovy-all, 1.7.2]
-
-licenses to remove from supplemental-models.xml (are spurious):
-
-[org.slf4j, slf4j-api, 1.5.2]
-----
-
-If any missing entries are listed or are spurious, then update `supplemental-models.xml` and try again.
-
-
-
-
-[[__cgcom_cutting-a-release_releasing-core_commit-changes]]
-=== Commit changes
-
-Commit any changes from the preceding steps:
-
-[source,bash]
-----
-git commit -am "$ISISJIRA: updates to pom.xml etc for release"
-----
-
-
-[[__cgcom_cutting-a-release_releasing-core_sanity-check]]
-=== Sanity check
-
-Perform one last sanity check on the codebase. Delete all Isis artifacts from your local Maven repo, then build using the `-o` offline flag:
-
-[source,bash]
-----
-rm -rf ~/.m2/repository/org/apache/isis
-mvn clean install -o
-----
-
-
-[[__cgcom_cutting-a-release_releasing-core_release-prepare-dry-run]]
-=== Release prepare "dry run"
-
-Most of the work is done using the `mvn release:prepare` goal. Since this makes a lot of changes, we run it first in "dry run" mode; only if that works do we run the goal for real.
-
-Run the dry-run as follows:
-
-[source,bash]
-----
-mvn release:prepare -P apache-release -D dryRun=true \
- -DreleaseVersion=$ISISREL \
- -Dtag=$ISISART-$ISISREL \
- -DdevelopmentVersion=$ISISDEV
-----
-
-You may be prompted for the gpg passphrase.
-
-[NOTE]
-====
-Experiments in using `--batch-mode -Dgpg.passphrase="..."` to fully automate this didn't work; for more info, see http://maven.apache.org/plugins/maven-gpg-plugin/sign-mojo.html[here] (maven release plugin docs) and http://maven.apache.org/maven-release/maven-release-plugin/examples/non-interactive-release.html[here] (maven gpg plugin docs).
-====
-
-
-
-[[__cgcom_cutting-a-release_releasing-core_release-prepare-proper]]
-=== Release prepare "proper"
-
-Assuming this completes successfully, re-run the command, but without the `dryRun` flag and specifying `resume=false` (to ignore the generated `release.properties` file that gets generated as a side-effect of using `git`). You can also set the `skipTests` flag since they would have been run during the previous dry run:
-
-[source,bash]
-----
-mvn release:prepare -P apache-release -D resume=false -DskipTests=true \
- -DreleaseVersion=$ISISREL \
- -Dtag=$ISISART-$ISISREL \
- -DdevelopmentVersion=$ISISDEV
-----
-
-
-[TIP]
-====
-If there are any snags at this stage, then explicitly delete the generated `release.properties` file first before trying again.
-====
-
-
-
-
-[[__cgcom_cutting-a-release_releasing-core_post-prepare-sanity-check]]
-=== Post-prepare sanity check
-
-You should end up with artifacts in your local repo with the new version (eg `1.15.0`). This is a good time to do some quick sanity checks; nothing has yet been uploaded:
-
-* unzip the source-release ZIP and check it builds.
-* Inspect the `DEPENDENCIES` file, and check it looks correct.
-
-These steps can be performed using the following script:
-
-[source]
-----
-rm -rf $ISISTMP/$ISISART-$ISISREL
-mkdir $ISISTMP/$ISISART-$ISISREL
-
-if [ "$ISISCOR" == "Y" ]; then
- ZIPDIR="$M2_REPO/repository/org/apache/isis/core/$ISISART/$ISISREL"
-else
- ZIPDIR="$M2_REPO/repository/org/apache/isis/$ISISCPT/$ISISART/$ISISREL"
-fi
-echo "cp \"$ZIPDIR/$ISISART-$ISISREL-source-release.zip\" $ISISTMP/$ISISART-$ISISREL/."
-cp "$ZIPDIR/$ISISART-$ISISREL-source-release.zip" $ISISTMP/$ISISART-$ISISREL/.
-
-pushd $ISISTMP/$ISISART-$ISISREL
-unzip $ISISART-$ISISREL-source-release.zip
-
-cd $ISISART-$ISISREL
-mvn clean install
-
-cat DEPENDENCIES
-
-popd
-----
-
-
-[[__cgcom_cutting-a-release_releasing-core_release-perform-upload]]
-=== Release perform (Upload)
-
-Once the release has been built locally, it should be uploaded for voting. This is done by deploying the Maven artifacts to a staging directory (this includes the source release ZIP file which will be voted upon).
-
-The Apache staging repository runs on Nexus server, hosted at https://repository.apache.org[repository.apache.org]. The process of uploading will create a staging repository that is associated with the host (IP address) performing the release. Once the repository is staged, the newly created staging repository is "closed" in order to make it available to others.
-
-Use:
-
-[source,bash]
-----
-mvn release:perform -P apache-release \
- -DworkingDirectory=$ISISTMP/$ISISART-$ISISREL/checkout
-----
-
-The custom `workingDirectory` prevents file path issues if releasing on Windows. The command checks out the codebase from the tag, then builds the artifacts, then uploads them to the Apache staging repository:
-
-[source,bash]
-----
-...
-[INFO] --- maven-release-plugin:2.3.2:perform (default-cli) @ isis ---
-[INFO] Performing a LOCAL checkout from scm:git:file:///C:\APACHE\isis-git-rw\co
-re
-[INFO] Checking out the project to perform the release ...
-[INFO] Executing: cmd.exe /X /C "git clone --branch release-1.15.0 file:///C:\APACHE\isis-git-rw\core C:\APACHE\isis-git-rw\core\target\checkout"
-[INFO] Working directory: C:\APACHE\isis-git-rw\core\target
-[INFO] Performing a LOCAL checkout from scm:git:file:///C:\APACHE\isis-git-rw
-[INFO] Checking out the project to perform the release ...
-[INFO] Executing: cmd.exe /X /C "git clone --branch release-1.15.0 file:///C:\APACHE\isis-git-rw C:\APACHE\isis-git-rw\core\target\checkout"
-[INFO] Working directory: C:\APACHE\isis-git-rw\core\target
-[INFO] Executing: cmd.exe /X /C "git ls-remote file:///C:\APACHE\isis-git-rw"
-[INFO] Working directory: C:\Users\ADMINI~1\AppData\Local\Temp
-[INFO] Executing: cmd.exe /X /C "git fetch file:///C:\APACHE\isis-git-rw"
-[INFO] Working directory: C:\APACHE\isis-git-rw\core\target\checkout
-[INFO] Executing: cmd.exe /X /C "git checkout release-1.15.0"
-[INFO] Working directory: C:\APACHE\isis-git-rw\core\target\checkout
-[INFO] Executing: cmd.exe /X /C "git ls-files"
-[INFO] Working directory: C:\APACHE\isis-git-rw\core\target\checkout
-[INFO] Invoking perform goals in directory C:\APACHE\isis-git-rw\core\target\checkout\core
-[INFO] Executing goals 'deploy'...
-...
-----
-
-You may (again) be prompted for gpg passphrase. All being well this command will complete successfully. Given that it is uploading code artifacts, it could take a while to complete.
-
-
-
-
-
-[[__cgcom_cutting-a-release_releasing-the-archetype]]
-== Releasing the Archetype
-
-Apache Isis archetypes are reverse engineered from example applications.
-Once reverse engineered, the source is checked into git (replacing any earlier version of the archetype) and released.
-
-
-[NOTE]
-====
-If releasing using Windows and Maven >= 3.3.3, then there is an issue that requires a small workaround.
-
-In Maven 3.3.3 the `mvn.bat` file was removed, replaced instead with `mvn.cmd`.
-However, `maven-archetype-plugin:2.4` only uses `mvn.bat`; this causes the `archetype:create-from-project` goal to fail.
-The fix is to simple: just copy `mvn.cmd` to `mvn.bat`.
-====
-
-
-Switch to the directory containing the `simpleapp` example:
-
-[source,bash]
-----
-cd ../example/application/simpleapp
-----
-
-[[__cgcom_cutting-a-release_releasing-the-archetype_setup-environment-variables]]
-=== Setup environment variables
-
-Set additional environment variables for the `simpleapp-archetype` artifact:
-
-[source,bash]
-----
-export ISISART=simpleapp-archetype
-export ISISPAR=$ISISREL # <1>
-
-export ISISCPT=$(echo $ISISART | cut -d- -f2)
-export ISISCPN=$(echo $ISISART | cut -d- -f1)
-
-env | grep ISIS | sort
-----
-<1> `$ISISPAR` is the version of the Apache Isis core that will act as the archetype's parent. Usually this is the same as `$ISISREL`.
-
-
-[[__cgcom_cutting-a-release_releasing-the-archetype_check-the-example-app]]
-=== Check the example app
-
-Update the parent `pom.xml` to reference the _released_ version of Apache Isis core, eg:
-
-[source,xml]
-----
-<properties>
- <isis.version>1.15.0</isis.version>
- ...
-</properties>
-----
-
-
-[NOTE]
-====
-Previously at this point we used to check for and fix any missing license header notices; however it doesn't make sense for the archetype to include the Apache rat-plugin, so this has been removed.
-====
-
-
-
-Finally, double check that the app
-
-* builds:
-+
-[source,bash]
-----
-mvn clean install
-----
-
-* can be run from an IDE
-** mainClass=`org.apache.isis.WebServer`
-** args=`-m domainapp.application.manifest.DomainAppAppManifestWithFixtures`
-** run before: `mvn -f pom-jdo-enhance-all.xml datanucleus:enhance -o` in the root module
-
-* can be run using the mvn jetty plugin:
-+
-[source,bash]
-----
-mvn -pl webapp jetty:run
-----
-
-* can be packaged and run using the mvn jetty-console plugin:
-+
-[source,bash]
-----
-mvn install -Dmavenmixin-jettyconsole
-mvn antrun:run -Dmavenmixin-jettyconsole
-----
-
-* can be deployed as a WAR
-+
-[source,bash]
-----
-cp webapp/target/simpleapp.war $CATALINA_HOME/webapps/ROOT.war
-pushd $CATALINA_HOME/bin
-sh startup.sh
-tail -f ../logs/catalina.out
-----
-+
-quit using:
-+
-[source,bash]
-----
-sh shutdown.sh
-popd
-----
-
-* can be packaged and run using Docker:
-+
-[source,bash]
-----
-mvn install -Dmavenmixin-docker -D docker-plugin.imageName=test/simpleapp
-docker container run -p 8080:8080 -d test/simpleapp
-----
-
-This too should be accessed at link:http://localhost:8080[localhost:8080].
-
-[TIP]
-====
-The Kitematic UI tool is handy for viewing and interacting with running containers.
-====
-
-
-In each case, check the about page and confirm has been built against non-SNAPSHOT versions of the Apache Isis jars.
-
-
-[[__cgcom_cutting-a-release_releasing-the-archetype_create-the-archetype]]
-=== Create the archetype
-
-Make sure you are in the correct directory and environment variables are correct.
-
-To recreate the *simpleapp* archetype:
-
-[source,bash]
-----
-cd example/application/simpleapp
-env | grep ISIS | sort
-----
-
-Then, run the script:
-
-[source,bash]
-----
-sh ../../../scripts/recreate-archetype.sh $ISISJIRA
-----
-
-The script automatically commits changes; if you wish use `git log` and
-`git diff` (or a tool such as SourceTree) to review changes made.
-
-
-[[__cgcom_cutting-a-release_releasing-the-archetype_release-prepare]]
-=== Release prepare
-
-Switch to the *archetype* directory and execute the `release:prepare`:
-
-[source]
-----
-cd ../../../example/archetype/$ISISCPN
-rm -rf $ISISTMP/checkout
-mvn release:prepare -P apache-release \
- -DreleaseVersion=$ISISREL \
- -DdevelopmentVersion=$ISISDEV \
- -Dtag=$ISISART-$ISISREL
-----
-
-
-
-[[__cgcom_cutting-a-release_releasing-the-archetype_post-prepare-sanity-check]]
-=== Post-prepare sanity check
-
-This is a good point to test the archetype; nothing has yet been uploaded.
-
-_In a different session_, create a new app from the archetype. First set up environment variables:
-
-[source,bash]
-----
-export ISISTMP=/c/tmp # or as required
-export ISISCPN=simpleapp
-env | grep ISIS | sort
-----
-
-Then generate a new app from the archetype:
-
-[source,bash]
-----
-rm -rf $ISISTMP/test-$ISISCPN
-
-mkdir $ISISTMP/test-$ISISCPN
-cd $ISISTMP/test-$ISISCPN
-mvn archetype:generate \
- -D archetypeCatalog=local \
- -D groupId=com.mycompany \
- -D artifactId=myapp \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=$ISISCPN-archetype
-----
-
-Build the newly generated app and test:
-
-[source,bash]
-----
-cd myapp
-mvn clean install -o
-mvn -pl webapp jetty:run # runs as mvn jetty plugin
-----
-
-
-
-[[__cgcom_cutting-a-release_releasing-the-archetype_release-perform-upload]]
-=== Release Perform (upload)
-
-Back in the original session (in the *archetype* directory, `example/archetype/$ISISCPN`), execute `release:perform`:
-
-[source]
-----
-mvn release:perform -P apache-release \
- -DworkingDirectory=$ISISTMP/checkout
-----
-
-This will upload the artifacts to the ASF Nexus repository.
-
-
-[[__cgcom_cutting-a-release_check-close-staging-repo]]
-== Check/Close Staging Repo
-
-The `mvn release:perform` commands will have put release artifacts for both `core` and the `simpleapp` archetype into a newly created staging repository on the ASF Nexus repository server.
-
-Log onto http://repository.apache.org[repository.apache.org] (using your ASF LDAP account):
-
-image::{_imagesdir}release-process/nexus-staging-0.png[width="600px",link="{_imagesdir}release-process/nexus-staging-0.png"]
-
-And then check that the release has been staged (select `staging repositories` from left-hand side):
-
-image::{_imagesdir}release-process/nexus-staging-1.png[width="600px",link="{_imagesdir}release-process/nexus-staging-1.png"]
-
-If nothing appears in a staging repo you should stop here and work out why.
-
-Assuming that the repo has been populated, make a note of its repo id; this is needed for the voting thread. In the screenshot above the id is `org.apache.isis-008`.
-
-
-After checking that the staging repository contains the artifacts that you expect you should close the staging repository. This will make it available so that people can check the release.
-
-Press the Close button and complete the dialog:
-
-image::{_imagesdir}release-process/nexus-staging-2.png[width="600px",link="{_imagesdir}release-process/nexus-staging-2.png"]
-
-Nexus should start the process of closing the repository.
-
-image::{_imagesdir}release-process/nexus-staging-2a.png[width="600px",link="{_imagesdir}release-process/nexus-staging-2a.png"]
-
-All being well, the close should (eventually) complete successfully (keep hitting refresh):
-
-image::{_imagesdir}release-process/nexus-staging-3.png[width="600px",link="{_imagesdir}release-process/nexus-staging-3.png"]
-
-The Nexus repository manager will also email you with confirmation of a successful close.
-
-If Nexus has problems with the key signature, however, then the close will be aborted:
-
-image::{_imagesdir}release-process/nexus-staging-4.png[width="600px",link="{_imagesdir}release-process/nexus-staging-4.png"]
-
-Use `gpg --keyserver hkp://pgp.mit.edu --recv-keys nnnnnnnn` to confirm that the key is available.
-
-
-[NOTE]
-====
-Unfortunately, Nexus does not seem to allow subkeys to be used for signing. See xref:cgcom.adoc#_cgcom_key-generation[Key Generation] for more details.
-====
-
-
-
-[[__cgcom_cutting-a-release_push-branches]]
-== Push branches
-
-Push the release branch to origin:
-
-[source,bash]
-----
-git push -u origin $ISISBRANCH
-----
-
-and also push tags for both core and the archetype:
-
-[source]
-----
-git push origin refs/tags/isis-$ISISREL:refs/tags/isis-$ISISREL-$ISISRC
-git push origin refs/tags/simpleapp-archetype-$ISISREL:refs/tags/simpleapp-archetype-$ISISREL-$ISISRC
-git fetch
-----
-
-[NOTE]
-====
-The remote tag isn't visible locally but can be seen https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=summary[online].
-====
-
-
-
-[[__cgcom_cutting-a-release_voting]]
-== Voting
-
-Once the artifacts have been uploaded, you can call a vote.
-
-In all cases, votes last for 72 hours and require a +3 (binding) vote from members.
-
-[[__cgcom_cutting-a-release_voting-start-voting-thread]]
-=== Start voting thread on link:mailto:dev@isis.apache.org[dev@isis.apache.org]
-
-The following boilerplate is for a release of the Apache Isis Core. Adapt as required:
-
-Use the following subject, eg:
-
-[source,bash]
-----
-[VOTE] Apache Isis Core release 1.15.0 RC1
-----
-
-And use the following body:
-
-[source,bash]
-----
-I've cut a release for Apache Isis Core and the simpleapp archetype:
-
-* Core 1.15.0
-* SimpleApp Archetype 1.15.0
-
-The source code artifacts have been uploaded to staging repositories on repository.apache.org:
-
-* http://repository.apache.org/content/repositories/orgapacheisis-10xx/org/apache/isis/core/isis/1.15.0/isis-1.15.0-source-release.zip
-* http://repository.apache.org/content/repositories/orgapacheisis-10xx/org/apache/isis/archetype/simpleapp-archetype/1.15.0/simpleapp-archetype-1.15.0-source-release.zip
-
-For each zip there is a corresponding signature file (append .asc to the zip's url).
-
-In the source code repo the code has been tagged as isis-1.15.0-RC1 and simpleapp-archetype-1.15.0-RC1; see https://git-wip-us.apache.org/repos/asf?p=isis.git
-
-For instructions on how to verify the release (build from binaries and/or use in Maven directly), see http://isis.apache.org/guides/cgcom.html#_cgcom_verifying-releases
-
-Please verify the release and cast your vote. The vote will be open for a minimum of 72 hours.
-
-[ ] +1
-[ ] 0
-[ ] -1
-----
-
-Remember to update:
-
-* the version number (1.15.0 or whatever)
-* the release candidate number (`RC1` or whatever)
-* the repository id, as provided by Nexus earlier (`orgapacheisis-10xx` or whatever)
-
-Note that the email also references the procedure for other committers to xref:cgcom.adoc#_cgcom_verifying-releases[verify the release].
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_cgcom_key-generation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcom_key-generation.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcom_key-generation.adoc
deleted file mode 100644
index d730ce1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cgcom_key-generation.adoc
+++ /dev/null
@@ -1,571 +0,0 @@
-[[_cgcom_key-generation]]
-= Key Generation
-:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
-:_basedir: ../
-:_imagesdir: images/
-:toc: right
-
-
-
-In order that a contributor can make a release it is necessary for them to have generated a key and had that key recognized by other members of the Apache Software Foundation.
-
-For further background information on this topic, see the http://www.apache.org/dev/release-signing.html[release signing page] and the http://www.apache.org/dev/openpgp.html#generate-key[openpgp page] on the Apache wiki.
-
-
-
-== Install and Configure gpg
-
-Download and install GnuPG (gpg), version 1.4.10 or higher.
-
-Then, edit `~/.gnupg/gpg.conf` (on Windows, the file to edit is `C:\Users\xxx\AppData\Roaming\gnupg\gpg.conf`) so that the default is to generate a strong key:
-
-[source,bash]
-----
-personal-digest-preferences SHA512
-cert-digest-algo SHA512
-default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
-----
-
-
-
-
-== Key Generation
-
-The Apache Software Foundation requires that keys are signed with a key (or subkey) based on RSA 4096 bits. To do this:
-
-[source]
-----
-$ gpg --gen-key
-gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Please select what kind of key you want:
- (1) RSA and RSA (default)
- (2) DSA and Elgamal
- (3) DSA (sign only)
- (4) RSA (sign only)
-Your selection?
-----
-
-Specify RSA key:
-
-[source]
-----
-Your selection? 1
-
-RSA keys may be between 1024 and 4096 bits long.
-What keysize do you want? (2048)
-----
-
-Specify key length as 4096 bits:
-
-[source]
-----
-What keysize do you want? (2048) 4096
-Requested keysize is 4096 bits
-
-Please specify how long the key should be valid.
- 0 = key does not expire
- <n> = key expires in n days
- <n>w = key expires in n weeks
- <n>m = key expires in n months
- <n>y = key expires in n years
-Key is valid for? (0)
-----
-
-Specify key as non-expiring:
-
-[source]
-----
-Key is valid for? (0) 0
-Key does not expire at all
-Is this correct? (y/N) y
-
-You need a user ID to identify your key; the software constructs the user ID
-from the Real Name, Comment and Email Address in this form:
- "Heinrich Heine (Der Dichter) <he...@duesseldorf.de>"
-
-Real name:
-----
-
-Enter your name, email and comment:
-
-* use your apache.org email
-* the comment should be "CODE SIGNING KEY"
-
-Real name: Xxx Xxxxxxxxx
-Email address: link:mailto:xxx@apache.org[xxx@apache.org]
-Comment: CODE SIGNING KEY
-You selected this USER-ID:
- "Xxx Xxxxxxxxx (CODE SIGNING KEY) link:mailto:xxx@apache.org[xxx@apache.org]"
-
-Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
-
-You need a Passphrase to protect your secret key.
-Enter passphrase:
-
-Provide a passphrase to secure your key.
-
-[source]
-----
-Enter passphrase:
-Repeat passphrase:
-----
-
-GPG will goes on to generate your key:
-
-[source]
-----
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-...+++++
-.........................+++++
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-....+++++
-...+++++
-gpg: key nnnnnnnn marked as ultimately trusted
-public and secret key created and signed.
-
-gpg: checking the trustdb
-gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
-gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
-pub 4096R/nnnnnnnn yyyy-mm-dd
- Key fingerprint = xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx
-uid Xxx Xxxxxx <xx...@apache.org>
-sub 4096R/kkkkkkkk yyyy-mm-dd
-----
-
-The public key with id nnnnnnnn should now be stored in `~/.gnupg/pubring.pgp` (on Windows 7, this is in `c:/Users/xxx/AppData/Roaming/gnupg/pubring.pgp`).
-
-To confirm the key has been generated, use:
-
-[source]
-----
-$ gpg --list-keys --fingerprint
-----
-
-The key Id is the one true way to identify the key, and is also the last 8 digits of the fingerprint. The corresponding secret key for id `nnnnnnnn` is stored in `~/.gnupg/secring.pgp` (on Windows 7, this is in `c:/Users/xxx/AppData/Roaming/gnupg/secring.pgp`).
-
-It's also worth confirming the key has the correct preference of algorithms (reflecting the initial configuration we did earlier). For this, enter the gpg shell for your new key:
-
-[source]
-----
-$ gpg --edit-key nnnnnnnnn
->gpg
-----
-
-where `nnnnnnnn` is your key id. Now, use the 'showpref' subcommand to list details:
-
-[source]
-----
-gpg> showpref
-[ultimate] (1). Xxx Xxxxxxxx (CODE SIGNING KEY) <xx...@apache.org>
- Cipher: AES256, AES192, AES, CAST5, 3DES
- Digest: SHA512, SHA384, SHA256, SHA224, SHA1
- Compression: ZLIB, BZIP2, ZIP, Uncompressed
- Features: MDC, Keyserver no-modify
-
-gpg>
-----
-
-The Digest line should list SHA-512 first and SHA-1 last. If it doesn't, use the "setpref" command:
-
-[source]
-----
-setpref SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
-----
-
-Finally, remember to take a backup of your key and the keyring (ie, backup the `.gnupg` directory and its contents).
-
-== Subkey Generation
-
-It's recommended to use a subkey with an expiry date to sign releases, rather than your main, non-expiring key. If a subkey is present, then gpg will use it for signing in preference to the main key.
-
-[NOTE]
-====
-After (binary) release artifacts are created, they are deployed to the ASF's Nexus staging repository. However, Nexus seems unable to retrieve a subkey from the public key server. Until we find a fix/workaround for this, all releases should be signed just with a regular non-expiring main key.
-====
-
-
-
-To create a subkey Enter the gpg shell using (the identifier of) your main key:
-
-[source]
-----
-gpg --edit-key xxxxxxxx
-gpg>
-----
-
-Type 'addkey' to create a subkey, and enter your passphrase for the main key:
-
-[source]
-----
-gpg> addkey
-Key is protected.
-[enter your secret passphrase]
-
-You need a passphrase to unlock the secret key for
-user: "Dan Haywood (CODE SIGNING KEY) <da...@apache.org>"
-4096-bit RSA key, ID xxxxxxxx, created 2011-02-01
-
-Please select what kind of key you want:
- (3) DSA (sign only)
- (4) RSA (sign only)
- (5) Elgamal (encrypt only)
- (6) RSA (encrypt only)
-Your selection?
-----
-
-Select (6) to choose an RSA key for encryption:
-
-[NOTE]
-====
-It would seem that Nexus repository manager does not recognize RSA subkeys with an 'S'ign usage; see this discussion on a mailing list and this issue on Sonatype's JIRA
-====
-
-
-[source]
-----
-Your selection? 6
-
-RSA keys may be between 1024 and 4096 bits long.
-What keysize do you want? (2048) 4096
-
-Requested keysize is 4096 bits
-
-Please specify how long the key should be valid.
- 0 = key does not expire
- <n> = key expires in n days
- <n>w = key expires in n weeks
- <n>m = key expires in n months
- <n>y = key expires in n years
-Key is valid for?
-----
-
-Specify that the key is valid for 1 year:
-
-[source]
-----
-Key is valid for? (0) 1y
-
-Key expires at yy/MM/dd hh:mm:ss
-Is this correct? (y/N) y
-Really create? (y/N) y
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
-...+++++
-.+++++
-
-pub 4096R/xxxxxxxx created: yyyy-mm-dd expires: never usage: SC
- trust: ultimate validity: ultimate
-sub 4096R/xxxxxxxx created: yyyy-mm-dd expires: yyYY-mm-dd usage: E
-[ultimate] (1). Dan Haywood (CODE SIGNING KEY) <da...@apache.org>
-
-gpg>
-----
-
-Quit the gpg shell; you now have a subkey.
-
-== Generate a Revocation Certificate
-
-It's good practice to generate a number of revocation certificates so that the key can be revoked if it happens to be compromised. See the http://www.apache.org/dev/openpgp.html#revocation-certs[gpg page] on the Apache wiki for more background on this topic.
-
-First, generate a "no reason specified" key:
-
-[source]
-----
-$ gpg --output revoke-nnnnnnnn-0.asc --armor --gen-revoke nnnnnnnn
-
-sec 4096R/nnnnnnnn yyyy-mm-dd Xxx Xxxxxxx (CODE SIGNING KEY) <xx...@apache.org>
-Create a revocation certificate for this key? (y/N) Y
-
-Please select the reason for the revocation:
- 0 = No reason specified
- 1 = Key has been compromised
- 2 = Key is superseded
- 3 = Key is no longer used
- Q = Cancel
-(Probably you want to select 1 here)
-Your decision?
-----
-
-Select 0.
-
-[source]
-----
-Your decision? 0
-
-Enter an optional description; end it with an empty line:
-----
-
-Provide a description:
-
-[source]
-----
-> Generic certificate to revoke key, generated at time of key creation.
->
-Reason for revocation: No reason specified
-Generic certificate to revoke key, generated at time of key creation.
-Is this okay? (y/N)
-----
-
-Confirm this is ok.
-
-[source]
-----
-Is this okay? y
-
-You need a passphrase to unlock the secret key for
-user: "Xxx Xxxxxxx (CODE SIGNING KEY) <xx...@apache.org>"
-4096-bit RSA key, ID nnnnnnnn, created yyyy-mm-dd
-
-Enter passphrase:
-</pre>
-
-Enter a passphrase:
-
-<pre>
-Enter passphrase:
-Revocation certificate created.
-
-Please move it to a medium which you can hide away; if Mallory gets
-access to this certificate he can use it to make your key unusable.
-It is smart to print this certificate and store it away, just in case
-your media become unreadable. But have some caution: The print system of
-your machine might store the data and make it available to others!
-----
-
-The file `revoke-nnnnnnnn-0.asc` should be created: Then, backup this file.
-
-Now repeat the process to create two further revocation certificates:
-
-[source,bash]
-----
-gpg --output revoke-nnnnnnnn-1.asc --armor --gen-revoke nnnnnnnn
-----
-
-Specify reason as "1 = Key has been compromised"
-
-and:
-
-[source,bash]
-----
-gpg --output revoke-nnnnnnnn-3.asc --armor --gen-revoke nnnnnnnn
-----
-
-Specify reason as "3 = Key is no longer used"
-
-Backup these files also.
-
-
-
-
-
-== Publish Key
-
-It is also necessary to publish your key. There are several places where this should be done. In most cases, you'll need the "armored" " (ie ASCII) representation of your key. This can be generated using:
-
-[source]
-----
-$ gpg --armor --export nnnnnnnn > nnnnnnnn.asc
-----
-
-where `nnnnnnnn` is the id of your public key.
-
-You'll also need the fingerprint of your key. This can be generated using:
-
-[source]
-----
-$ gpg --fingerprint nnnnnnnn
-----
-
-The output from this command includes a line beginning "Key fingerprint", followed by a (space delimited) 40 character hexadecimal fingerprint. The last 8 characters should be the same as the key id (`nnnnnnnn`).
-
-=== Publish to a public key server
-
-To a publish your key to a public key server (eg the MIT key server hosted at http://pgp.mit.edu[http://pgp.mit.edu]), use the procedure below. Public key servers synchronize with each other, so publishing to one key server should be sufficient. For background reading on this, see the http://www.apache.org/dev/release-signing.html#keyserver-upload[release signing page] on the Apache wiki, and the http://maven.apache.org/developers/release/pmc-gpg-keys.html[gpg key page] on the Maven wiki.
-
-To send the key up to the key server:
-
-[source]
-----
-$ gpg --send-keys --keyserver pgp.mit.edu nnnnnnnn
-----
-
-where `nnnnnnnn` is the key Id.
-
-Alternatively, you can browse to the http://pgp.mit.edu/[MIT key server] and paste in the armored representation of your key.
-
-Confirm the key has been added by browsing to submitting the following URL:
-
-`http://pgp.mit.edu:11371/pks/lookup?search=0xnnnnnnnnn&op=vindex`
-
-again, where `nnnnnnnn` is the key Id.
-
-=== Publish to your Apache home directory
-
-The armored representation of your public key should be uploaded to your home directory on `people.apache.org`, and renamed as `.pgpkey`. Make sure this is readable by all.
-
-=== Publish to your Apache HTML home directory
-
-The armored representation of your public key should be uploaded to your `public_html` home directory on `people.apache.org`, named `nnnnnnnn.asc`. Make sure this is readable by all.
-
-Check the file is accessible by browsing to:
-
-`http://people.apache.org/~xxxxxxxx/nnnnnnnn.asc`
-
-where
-
-* `xxxxxxxx` is your apache LDAP user name
-* `nnnnnnnn` is your public key id.
-
-=== FOAF
-
-First, check out the committers/info directory:
-
-Go to Apache http://people.apache.org/foaf/foafamatic.html[FOAF-a-matic] web page to generate the FOAF file text (we copy this text out in a minute):
-
-* enter ASF LDAP user name
-* enter First name, Last name
-* for PGP key fingerprints, add Key
-* paste in the key id
-* paste in the fingerprint
-* press "Create"
-
-In the box below, you should have a FOAF file, something like:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<rdf:RDF
- xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
- xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
- xmlns:foaf="http://xmlns.com/foaf/0.1/"
- xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
- xmlns:pm="http://www.web-semantics.org/ns/pm#"
- xmlns:wot="http://xmlns.com/wot/0.1/"
- xmlns:rss="http://purl.org/rss/1.0/"
- xmlns:dc="http://purl.org/dc/elements/1.1/"
- xmlns:ical="http://www.w3.org/2002/12/cal/ical#"
- xmlns:doap="http://usefulinc.com/ns/doap#">
- <foaf:Person rdf:ID="danhaywood">
- <foaf:name>Xxx Xxxxxxxx</foaf:name>
- <foaf:givenname>Xxx</foaf:givenname>
- <foaf:family_name>Xxxxxxxx</foaf:family_name>
- <wot:hasKey>
- <wot:PubKey>
- <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
- <wot:hex_id>nnnnnnnn</wot:hex_id>
- </wot:PubKey>
- </wot:hasKey>
- </foaf:Person>
-</rdf:RDF>
-----
-
-(If you are creating the FOAF file for the first time, you may want to add additional details).
-
-From this, copy out the `wot:key`, and paste into your FDF file in `committers/info`:
-
-[source,xml]
-----
-<wot:hasKey>
- <wot:PubKey>
- <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
- <wot:hex_id>nnnnnnnn</wot:hex_id>
- </wot:PubKey>
-</wot:hasKey>
-----
-
-Then, manually add in a `<wot:pubkeyAddress>` element within `<wot:PubKey>`:
-
-[source,xml]
-----
-<wot:hasKey>
- <wot:PubKey>
- <wot:fingerprint>nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn nnnn</wot:fingerprint>
- <wot:hex_id>nnnnnnnn</wot:hex_id>
- <wot:pubkeyAddress rdf:resource="http://people.apache.org/~username/nnnnnnnn.asc/">
- </wot:PubKey>
-</wot:hasKey>
-----
-
-ie, referencing your publically exported public key
-
-Finally, commit your changes.
-
-=== Save to `KEYS`
-
-The armored representation of the public key should be saved to Apache Isis' `KEYS` file, http://www.apache.org/dist/isis/KEYS[http://www.apache.org/dist/isis/KEYS] (that is, in the ASF distribution directory for Apache Isis).
-
-First, in a new directory, checkout this file:
-
-[source]
-----
-svn -N co https://svn.apache.org/repos/asf/isis/ .
-----
-
-This should bring down the `KEYS` file.
-
-Then, export your signature and armored representation.
-
-[source]
-----
-gpg --list-sigs nnnnnnnn >>KEYS
-gpg --armor --export nnnnnnnn >>KEYS
-----
-
-Then commit.
-
-=== id.apache.org
-
-Log onto `id.apache.org` and ensure that the finger print of your public key is correct.
-
-== Attend Key Signing Party (Apache web of trust)
-
-It is strongly advised that the contributor attend a key signing party at an Apache event, in order that other Apache committers/members can in person verify their identity against the key. The process for this is described http://www.apache.org/dev/release-signing.html#key-signing-party[here] and http://wiki.apache.org/apachecon/PgpKeySigning[here].
-
-== Update Maven Settings file (`~/.m2/settings.xml`)
-
-The Maven release plugin will automatically sign the release, however it is necessary to update the `~/.m2/settings.xml` file with your GPG acronym passphrase in order that it can use your secret key. This is defined under a profile so that it is activated only when we perform a release (as defined by `[org,apache:apache]` parent POM.
-
-Therefore, make the following edits:
-
-[source,xml]
-----
-<settings>
- ...
- <profiles>
- <profile>
- <id>apache-release</id>
- <properties>
- <gpg.passphrase>xxx xxx xxx xxx xxx xxx xxx</gpg.passphrase>
- </properties>
- </profile>
- </profiles>
-</settings>
-----
-
-In addition, to allow the release plugin to tag SVN changes, you must either add in your LDAP username/password or configure `.ssh`:
-
-[source,xml]
-----
-<settings>
- ...
- <servers>
- ...
- <server>
- <id>apache.releases.https</id>
- <username>xxxx</username>
- <password>xxxx</password>
- </server>
- </servers>
-</settings>
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc
deleted file mode 100644
index 8871a7f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc
+++ /dev/null
@@ -1,137 +0,0 @@
-[[_cgcom_merging-a-pull-request]]
-= Merging a Pull Request
-: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 process for merging in github pull requests (so that they can be tested locally before committing) has been scripted in the `github-pr.sh` script.
-
-The script will merge the fork into a temporary branch, and then run a build. Once you are happy, you can commit.
-
-
-
-
-
-== Process and Usage
-
-The overall process is as follows:
-
-* locate/raise corresponding JIRA ticket, eg ISIS-1162
-* checkout branch from which PR was forked (usually just 'master')
-* merge PR into temporary branch using the `github-pr.sh` script
-* test the change locally (run the app, rebuild, manual regression tests etc)
-* if required, tidy up/refactor code as required
-* merge temporary branch into mainline, and commit
-
-This link:https://youtu.be/CKSLZBBHjME[screencast] also shows the process.
-
-
-== Prerequisites
-
-The script uses 'jq' to parse JSON. To install:
-
-* on Linux: +
-+
-[source,bash]
-----
-aptitude install jq
-----
-
-* on MacOS: +
-+
-[source,bash]
-----
-brew install jq
-----
-
-* on Windows: +
-+
-Download exe from http://stedolan.github.io/jq/download/[website]
-
-
-
-== Syntax
-
-The syntax is:
-
-[source,bash]
-----
-github-pr.sh -j 1162 -g 31 [-s] [-p ISIS]
-----
-
-where:
-
-* `-j 1162` +
-+
-is the JIRA ticket number
-
-* `-g 31` +
-+
-is the github PR issue number
-
-* `-s` +
-+
-will optionally skip the build and auto-merge
-
-* `-p ISIS` +
-+
-optionally overrids the JIRA project (defaults to 'ISIS')
-
-
-
-== Example transcript
-
-The listing below shows the steps taken by the script:
-
-[source,bash]
-----
-$ sh github-pr.sh isis 1162 31
-
-Found JIRA ticket
-Found github PR
-branch_name_local: master
-username : sebadiaz
-repo_full_name : sebadiaz/isis
-repo_clone_url : https://github.com/sebadiaz/isis.git
-branch_name_fork : master
-
-merging into: ISIS-1162_pr-31
-
-Deleting branch 'ISIS-1162_pr-31'
-Deleted branch ISIS-1162_pr-31 (was bd2e3c2).
-Creating the branch ISIS-1162_pr-31
-Switched to a new branch 'ISIS-1162_pr-31'
-Pulling the changes from https://github.com/sebadiaz/isis.git master
-From https://github.com/sebadiaz/isis
- * branch master -> FETCH_HEAD
-Auto-merging core/pom.xml
-Merge made by the 'recursive' strategy.
- core/pom.xml | 3 +-
- .../apache/isis/security/shiro/IsisLdapRealm.java | 198 +++++++++++++++++++--
- 2 files changed, 186 insertions(+), 15 deletions(-)
-
-Merged the PR; hit enter to build
-----
-
-The build now commences. Once done, the script continues:
-
-[source,bash]
-----
-If build successful and happy to merge, execute:
-
-git checkout master && git merge --no-ff ISIS-1162_pr-31 && git branch -d ISIS-1162_pr-31
-----
-
-The screenshot belows shows the history we end up with:
-
-image::{_imagesdir}committers/github-pr-history.png[link="{_imagesdir}committers/github-pr-history.png"]
-
-This shows the fork being merged into the temporary branch ("ISIS-1162_pr-31"), then some further tidy-up, and finally the merging of the temporary branch into mainline.
-
-Note that there is no rebasing in this model. This is intentional: when the merged branch is pushed, github will automatically close the original pull request.
-
-
-
-