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/17 12:11:53 UTC
[4/8] isis git commit: ISIS-1052: redoing the release notes.
http://git-wip-us.apache.org/repos/asf/isis/blob/119c3fcd/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process.adoc
new file mode 100644
index 0000000..2f5df01
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_release-process.adoc
@@ -0,0 +1,1004 @@
+[[_cg_committers_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
+
+
+Apache Isis 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.
+
+If you've not performed a release before, then note that there are some configuration xref:cg.adoc#_cg_committers_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.
+
+See also:
+
+* the xref:cg.adoc#_cg_committers_release-process-one-pager[one pager] which lists the essential steps
+* the xref:cg.adoc#_cg_committers_release-checklist[release checklist] for keeping track of where you are while releasing Apache Isis component(s).
+
+
+
+== Obtain Consensus
+
+Before releasing `core`, ensure there is consensus on the xref:../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:cg.adoc#_cg_committers_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.
+
+
+== 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 isis-1.9.0
+----
+
+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.
+
+For example, if releasing `core` version `1.9.0`, the POM should read:
+
+[source,xml]
+----
+<groupId>org.apache.isis.core</groupId>
+<artifactId>isis</artifactId>
+<version>1.9.0-SNAPSHOT</version>
+----
+
+Also, check that there are no snapshot dependencies:
+
+[source,bash]
+----
+grep SNAPSHOT `/bin/find . -name pom.xml | grep -v target | 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.
+====
+
+
+
+== Releasing Core
+
+First, we release `core`.
+
+=== Set environment variables
+
+We use environment variables to parameterize as many of the steps as possible.
+
+[source,bash]
+----
+cd core
+export ISISTMP=/c/tmp # <1>
+export ISISART=isis
+export ISISDEV=1.10.0-SNAPSHOT
+export ISISREL=1.9.0
+export ISISRC=RC1
+
+export ISISCOR="Y"
+env | grep ISIS | sort
+----
+<1> adjust by platform
+
+
+
+
+=== 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
+----
+
+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
+----
+
+
+=== 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.
+
+
+[NOTE]
+====
+Ignore any missing license warnings for the TCK modules; this is a result of the TCK modules for the viewers (eg `isis-viewer-bdd-concordion-tck`) depending on the TCK dom, fixtures etc.
+====
+
+
+
+=== Commit changes
+
+Commit any changes from the preceding steps:
+
+[source,bash]
+----
+git commit -am "ISIS-nnnn: updates to pom.xml etc for release"
+----
+
+
+=== 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
+----
+
+
+
+=== 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).
+====
+
+This should generate something like:
+
+[source,bash]
+----
+[INFO] Scanning for projects...
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Build Order:
+[INFO]
+[INFO] Apache Isis Core
+[INFO] Apache Isis Core AppLib
+[INFO] Apache Isis Core Unit Test Support
+[INFO] Apache Isis Core MetaModel
+[INFO] Apache Isis Core Runtime
+[INFO] Apache Isis Core WebServer
+ ...
+[INFO] Apache Isis Core Integration Testing Support
+[INFO]
+[INFO] ------------------------------------------------------------------------
+[INFO] Building Apache Isis Core 1.9.0
+[INFO] ------------------------------------------------------------------------
+[INFO]
+[INFO] --- maven-release-plugin:2.3.2:prepare (default-cli) @ isis ---
+[INFO] Resuming release from phase 'map-release-versions'
+What is the release version for "Apache Isis Core"? (org.apache.isis.core:isis)
+1.9.0: :
+----
+
+
+=== 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.
+====
+
+
+
+
+=== Post-prepare sanity check
+
+You should end up with artifacts in your local repo with the new version (eg `1.9.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
+----
+
+
+=== 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 isis-1.9.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 isis-1.9.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 isis-1.9.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.
+
+
+
+
+
+
+
+== 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.
+
+
+=== Setup environment variables
+
+To recreate the `simpleapp` archetype:
+
+[source,bash]
+----
+cd example/application/simpleapp
+
+export ISISTMP=/c/tmp # 1
+export ISISART=simpleapp-archetype
+export ISISDEV=1.10.0-SNAPSHOT
+export ISISREL=1.9.0
+export ISISPAR=$ISISREL # 2
+export ISISRC=RC1
+
+export ISISCPT=$(echo $ISISART | cut -d- -f2)
+export ISISCPN=$(echo $ISISART | cut -d- -f1)
+
+env | grep ISIS | sort
+----
+<1> adjust by platform
+<2> `$ISISPAR` is the version of the Apache Isis core that will act as the archetype's parent. Usually this is the same as `$ISISREL`.
+
+
+
+=== 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.9.0</isis.version>
+ ...
+</properties>
+----
+
+
+
+Check for and fix any missing license header notices:
+
+[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
+----
+
+
+Finally, double check that the app is running satisfactorily:
+
+* first, as self-hosted webconsole (browse to http://localhost:8080[http://localhost:8080]): +
++
+[source,bash]
+----
+mvn clean install
+mvn antrun:run -P self-host
+----
+
+* then using mvn jetty plugin (browse to http://localhost:8080/simpleapp-webapp/[http://localhost:8080/simpleapp-webapp/]): +
++
+[source,bash]
+----
+cd webapp
+mvn jetty:run
+----
+
+Check the about page and confirm built against non-SNAPSHOT versions of the Apache Isis jars.
+
+
+
+=== 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 ISIS-nnnn
+----
+
+The script automatically commits changes; if you wish use `git log` and
+`git diff` (or a tool such as SourceTree) to review changes made.
+
+
+
+=== 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
+mvn release:perform -P apache-release \
+ -DworkingDirectory=$ISISTMP/checkout
+----
+
+
+
+
+=== Post-prepare sanity check
+
+This is a good point to test the archetype; nothing has yet been uploaded.
+First, build the archetype:
+
+[source,bash]
+----
+cd target/generated-sources/archetype
+mvn clean install
+cd ../../..
+----
+
+Then, _in a different session_, create a new app from the archetype:
+
+Set up environment variables:
+
+To test the *simpleapp* archetype:
+
+[source,bash]
+----
+export ISISTMP=/c/tmp # or as required
+export ISISCPN=simpleapp
+env | grep ISIS | sort
+----
+
+Then recreate:
+
+[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
+mvn antrun:run -P self-host # runs as standalone app using webconsole
+cd webapp
+mvn jetty:run # runs as mvn jetty plugin
+----
+
+
+
+
+=== Release Perform (upload)
+
+Still in the *archetype* directory and execute the `release:perform` to upload the artifacts to the ASF Nexus repository:
+
+[source]
+----
+cd ../../../example/archetype/$ISISCPN
+rm -rf $ISISTMP/checkout
+mvn release:prepare -P apache-release \
+ -DreleaseVersion=$ISISREL \
+ -DdevelopmentVersion=$ISISDEV \
+ -Dtag=$ISISART-$ISISREL
+mvn release:perform -P apache-release \
+ -DworkingDirectory=$ISISTMP/checkout
+----
+
+
+
+
+
+== 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:cg.adoc#_cg_committers_key-generation[Key Generation] for more details.
+====
+
+
+
+
+== Push branches
+
+Push the release branch to origin:
+
+[source,bash]
+----
+git push -u origin $ISISREL
+----
+
+and also push tags for both core and the archetype:
+
+[source]
+----
+git push origin refs/tags/isis-$ISISREL-$ISISRC:refs/tags/isis-$ISISREL-$ISISRC
+git push origin refs/tags/simpleapp-archetype-$ISISREL-$ISISRC: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].
+====
+
+
+
+
+== 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.
+
+
+=== 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.9.0 RC1
+----
+
+And use the following body:
+
+[source,bash]
+----
+I've cut a release for Apache Isis Core and the simpleapp archetype:
+* Core 1.9.0
+* SimpleApp Archetype 1.9.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.9.0/isis-1.9.0-source-release.zip
+* http://repository.apache.org/content/repositories/orgapacheisis-10xx/org/apache/isis/archetype/simpleapp-archetype/1.9.0/simpleapp-archetype-1.9.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.9.0-RC1 and simpleapp-archetype-1.9.0-RC1.
+
+For instructions on how to verify the release (build from binaries and/or use in Maven directly), see xref:cg.adoc#_cg_committers_verifying-releases[here]
+
+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.9.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:cg.adoc#_cg_committers_verifying-releases[verify the release].
+
+
+
+
+== After the vote
+
+Once the vote has completed, post the results to the isis-dev mailing list.
+
+For example, use the following subject for a vote on Apache Isis Core:
+
+[source,bash]
+----
+[RESULT] [VOTE] Apache Isis Core release 1.9.0
+----
+
+using the body (alter last line as appropriate):
+
+[source,bash]
+----
+The vote has completed with the following result :
+
+ +1 (binding): <i>list of names</i>
+ +1 (non binding): <i>list of names</i>
+
+ -1 (binding): <i>list of names</i>
+ -1 (non binding): <i>list of names</i>
+
+The vote is (UN)SUCCESSFUL.
+----
+
+
+
+=== For a successful vote
+
+If the vote has been successful, then replace the `-RCn` tag with another without the qualifier.
+
+You can do this using the `scripts/promoterctag.sh` script; for example:
+
+[source,bash]
+----
+sh scripts/promoterctag isis-1.9.0 RC1
+sh scripts/promoterctag simpleapp-archetype-1.9.0 RC1
+----
+
+
+Then, continue onto the next section for the steps to promote and announce the release.
+
+
+=== For an unsuccessful vote
+
+If the vote has been unsuccessful, then:
+
+* delete the remote branch, for example: +
++
+[source,bash]
+----
+git push origin –delete isis-1.9.0 # $ISISART-$SISREL
+----
+
+
+* delete the remote origin server's tag, for example: +
++
+[source,bash]
+----
+git push origin –delete refs/tags/isis-1.9.0-RC1
+----
+
+
+* delete the tag that was created locally, for example: +
++
+[source,bash]
+----
+git tag -d isis-1.9.0 # $ISISART-$SISREL
+----
+
+
+* drop the staging repository in http://repository.apache.org[Nexus]
+
+* rewind the release branch to prior to the previous release candidate, and continue from there.
+
+
+
+
+
+
+== Release to Maven Central
+
+From the Nexus pages, select the staging repository and select 'release' from the top menu.
+
+
+image::{_imagesdir}release-process/nexus-release-1.png[width="600px",link="{_imagesdir}release-process/nexus-release-1.png"]
+
+This moves the release artifacts into an Apache releases repository; from there they will be automatically moved to the Maven repository.
+
+
+
+
+== Release Source Zip
+
+As described in the http://www.apache.org/dev/release-publishing.html#distribution_dist[Apache documentation], each Apache TLP has a `release/TLP-name` directory in the distribution Subversion repository at https://dist.apache.org/repos/dist[https://dist.apache.org/repos/dist]. Once a release vote passes, the release manager should `svn add` the artifacts (plus signature and hash files) into this location. The release is then automatically pushed to http://www.apache.org/dist/[http://www.apache.org/dist/] by `svnpubsub`. Only the most recent release of each supported release line should be contained here, old versions should be deleted.
+
+Each project is responsible for the structure of its directory. The directory structure of Apache Isis reflects the directory structure in our git source code repo:
+
+[source]
+----
+isis/
+ core/
+ example/
+ archetype/
+ simpleapp/
+----
+
+If necessary, checkout this directory structure:
+
+[source,bash]
+----
+svn co https://dist.apache.org/repos/dist/release/isis isis-dist
+----
+
+Next, add the new release into the appropriate directory, and delete any previous release. You can use link:upd_sh[the upd.sh script] to help; this downloads the artefacts from the Nexus release repository, adds the artefacts to subsversion and deletes the previous version.
+
+At the end, commit the changes:
+
+[source]
+----
+svn commit -m "publishing isis source releases to dist.apache.org"
+----
+
+
+
+== Update JIRA
+
+=== Close All JIRA tickets for the release
+
+Close all JIRA tickets for the release, or moved to future releases if not yet addressed. Any tickets that were partially implemented should be closed, and new tickets created for the functionality on the ticket not yet implemented.
+
+=== Generate Release Notes
+
+[TIP]
+====
+This is now scripted; need to add notes here...
+====
+
+
+
+Use JIRA to http://confluence.atlassian.com/display/JIRA/Creating+Release+Notes[generate release notes]:
+
+image::{_imagesdir}release-process/jira-create-release-notes.png[width="400px",link="{_imagesdir}release-process/jira-create-release-notes.png"]
+<img src="resources/jira-create-release-notes.png" width="400px"></img>
+
+If any of the tickets closed are tasks/subtasks, then please edit the contents of the file to associate them back together again.
+
+
+
+=== Mark the JIRA versions as released
+
+In JIRA, go to the administration section for the Apache Isis project and update the versions as released.
+
+
+
+
+
+== Update website
+
+Update the Apache Isis (asciidoc) website:
+
+* Paste in the JIRA-generated release notes.
+
+* Search for any `-SNAPSHOT` suffices, and remove
+
+* Update the link:../download.html[download page] with a link to the source release zip file (under https://dist.apache.org/repos/dist/release/isis[https://dist.apache.org/repos/dist/release/isis])
+
+* update the link:../doap_isis.rdf[DOAP RDF] file (which provides a machine-parseable description of the project) should also be updated with details of the new release. Validate using the http://www.w3.org/RDF/Validator/[W3C RDF Validator] service. +
++
+For more information on DOAP files, see these http://projects.apache.org/doap.html[Apache policy docs].
+
+* Update the https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=blob_plain;f=STATUS;hb=HEAD[STATUS] file (in root of Apache Isis' source) should be updated with details of the new release.
+
+
+
+
+== Announce the release
+
+Announce the release to link:mailto:users@isis.apache.org[users mailing list].
+
+For example, for a release of Apache Isis Core, use the following subject:
+
+[source,bash]
+----
+[ANN] Apache Isis version 1.9.0 Released
+----
+
+And use the following body (summarizing the main points as required):
+
+[source]
+----
+The Apache Isis team is pleased to announce the release of:
+* Apache Isis Core version 1.9.0
+* SimpleApp Archetype 1.9.0
+
+New features in this release include:
+- ...
+
+Full release notes are available on the Apache Isis website at [1].
+
+Note that:
+* ...
+
+You can access this release directly from the Maven central repo [2],
+or download the release and build it from source [3].
+
+Enjoy!
+
+--The Apache Isis team
+
+[1] http://isis.apache.org/core/release-notes/isis-1.9.0.html
+[2] http://search.maven.org
+[3] http://isis.apache.org/download.html
+----
+
+
+
+
+== Blog post
+
+Finally, https://blogs.apache.org/roller-ui/login.rol[log onto] the http://blogs.apache.org/isis/[Apache blog] and create a new post. Copy-n-paste the above mailing list announcement should suffice.
+
+
+
+
+== Prepare for next release
+
+=== Merge into `master`
+
+Because we release from a branch, the changes made in the branch (changes to `pom.xml` made by the `maven-release-plugin`, or any manual edits) should be merged back from the release branch back into the `master` branch:
+
+[source,bash]
+----
+git checkout master # update master with latest
+git pull
+git merge isis-1.9.0 # merge branch onto master
+git branch -d isis-1.9.0 # branch no longer needed
+git push origin --delete isis-1.9.0 # remote branch no longer needed
+----
+
+
+=== Bump versions
+
+With the release complete, now is a good time to bump versions of dependencies (so that there is a full release cycle to identify any possible issues).
+
+==== Update parent (Apache Isis Core)
+
+Check (via link:http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache%22%20a%3A%22apache%22[search.maven.org]) whether there is a newer version of the Apache parent `org.apache:apache`.
+
+If there is, update the `<version>` in the `<parent>` element in the parent POM to match the newer version:
+
+[source,xml]
+----
+<parent>
+ <groupId>org.apache</groupId>
+ <artifactId>apache</artifactId>
+ <version>NN</version>
+ <relativePath />
+</parent>
+----
+
+where `NN` is the updated version number.
+
+
+
+==== Update plugin versions
+
+The `maven-versions-plugin` should be used to determine if there are newer versions of any of the plugins used to build Apache Isis. Since this goes off to the internet, it may take a minute or two to run:
+
+[source,bash]
+----
+mvn versions:display-plugin-updates > /tmp/foo
+grep "\->" /tmp/foo | /bin/sort -u
+----
+
+Review the generated output and make updates as you see fit. (However, if updating, please check by searching for known issues with newer versions).
+
+
+
+=== Update dependency versions
+
+The `maven-versions-plugin` should be used to determine if there are newer versions of any of Isis' dependencies. Since this goes off to the internet, it may take a minute or two to run:
+
+[source,bash]
+----
+mvn versions:display-dependency-updates > /tmp/foo
+grep "\->" /tmp/foo | /bin/sort -u
+----
+
+Update any of the dependencies that are out-of-date. That said, do note that some dependencies may show up with a new dependency, when in fact the dependency is for an old, badly named version. Also, there may be new dependencies that you do not wish to move to, eg release candidates or milestones.
+
+For example, here is a report showing both of these cases:
+
+[source,bash]
+----
+[INFO] asm:asm ..................................... 3.3.1 -> 20041228.180559
+[INFO] commons-httpclient:commons-httpclient .......... 3.1 -> 3.1-jbossorg-1
+[INFO] commons-logging:commons-logging ......... 1.1.1 -> 99.0-does-not-exist
+[INFO] dom4j:dom4j ................................. 1.6.1 -> 20040902.021138
+[INFO] org.datanucleus:datanucleus-api-jdo ................ 3.1.2 -> 3.2.0-m1
+[INFO] org.datanucleus:datanucleus-core ................... 3.1.2 -> 3.2.0-m1
+[INFO] org.datanucleus:datanucleus-jodatime ............... 3.1.1 -> 3.2.0-m1
+[INFO] org.datanucleus:datanucleus-rdbms .................. 3.1.2 -> 3.2.0-m1
+[INFO] org.easymock:easymock ................................... 2.5.2 -> 3.1
+[INFO] org.jboss.resteasy:resteasy-jaxrs ............. 2.3.1.GA -> 3.0-beta-1
+----
+
+For these artifacts you will need to search http://search.maven.org[Maven central repo] directly yourself to confirm there are no newer dependencies not shown in this list.
+
+
+
+=== Code cleanup / formatting
+
+Make sure that all source code has been cleaned up and formatted according to the Apache Isis and ASF conventions. Use link:resources/Apache-code-style-formatting.xml[this] Eclipse template and link:resources/isis.importorder[this] import order.
+
+
+
+=== Push changes
+
+Finally, push the changes up to origin:
+
+[source,bash]
+----
+git fetch # check no new commits on origin/master
+git push
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/119c3fcd/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc
index 77c01ae..8c93e54 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases-using-a-script.adoc
@@ -1,5 +1,5 @@
[[_cg_committers_verify-releases-using-a-script]]
-= Verify using a script
+= Verifying a Release (scripted)
: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/
@@ -21,7 +21,7 @@ cd ~/verify-isis-release
-== Copy the script to your local machine
+== Copy script to local machine
The script could be enhanced in many ways, feel free to do so! Copy (or link:resources/release-process/verify-isis-release.sh[download]) the `verify-isis-release.sh` script below:
@@ -105,7 +105,7 @@ The actual list of packages to be verified will be provided through the mailing
-== Clean out Apache Isis from your local Maven repo
+== Clean out local Maven repo
[source,bash]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/119c3fcd/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
index 74f5cda..773ce04 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_committers_verifying-releases.adoc
@@ -1,5 +1,5 @@
[[_cg_committers_verifying-releases]]
-= Verifying Releases
+= Verifying a Release
:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
:_basedir: ../
:_imagesdir: images/
@@ -36,7 +36,7 @@ gpg --import /tmp/KEYS
-== Verifying the source release artifacts
+== Verifying source artifacts
[NOTE]
@@ -55,7 +55,7 @@ gpg --verify isis-x.y.z.zip.asc isis-x.y.z.zip
-== Building the source release artifacts
+== Building source artifacts
Assuming the ZIP file verifies, it should be unpacked, and then the artifact built from source.
@@ -89,7 +89,7 @@ Confirm that the versions of the Isis artifacts now cached in your local reposit
-== Verifying the binary release artifacts (using the Maven staging repository)
+== Verifying binary artifacts
If you wish, you can verify the binary releases by configuring your local Maven install to point to the Maven Maven staging repository (or repositories) and then using them, eg to run the link:../intro/getting-started/simpleapp-archetype.html[simpleapp archetype] and running the resultant app.
http://git-wip-us.apache.org/repos/asf/isis/blob/119c3fcd/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
index e36e3df..8f3a75b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
@@ -20,16 +20,16 @@ This contributors' guide has three related audiences:
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_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_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_asciidoc.adoc[leveloffset=+1]
include::_cg_committers.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/119c3fcd/adocs/redirects/content/getting-started/quickstart-archetype.html
----------------------------------------------------------------------
diff --git a/adocs/redirects/content/getting-started/quickstart-archetype.html b/adocs/redirects/content/getting-started/quickstart-archetype.html
new file mode 100644
index 0000000..dac980e
--- /dev/null
+++ b/adocs/redirects/content/getting-started/quickstart-archetype.html
@@ -0,0 +1,11 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+ <head>
+ <meta charset="UTF-8">
+ <meta http-equiv="refresh" content="5;url=http://isis.apache.org/documentation.html">
+ <title>Page Redirection</title>
+ </head>
+ <body>
+ The Apache Isis website has been reorganized and expanded; redirecting to our updated <a href='http://isis.apache.org/documentation.html'>documentation</a> page.
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/isis/blob/119c3fcd/adocs/redirects/content/intro/getting-started/quickstart-archetype.html
----------------------------------------------------------------------
diff --git a/adocs/redirects/content/intro/getting-started/quickstart-archetype.html b/adocs/redirects/content/intro/getting-started/quickstart-archetype.html
new file mode 100644
index 0000000..dac980e
--- /dev/null
+++ b/adocs/redirects/content/intro/getting-started/quickstart-archetype.html
@@ -0,0 +1,11 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+ <head>
+ <meta charset="UTF-8">
+ <meta http-equiv="refresh" content="5;url=http://isis.apache.org/documentation.html">
+ <title>Page Redirection</title>
+ </head>
+ <body>
+ The Apache Isis website has been reorganized and expanded; redirecting to our updated <a href='http://isis.apache.org/documentation.html'>documentation</a> page.
+ </body>
+</html>