anchor.diff:  These release notes using bash command line tools.
   They should work on Linux and MacOS; for Windows, use mSysGit.
   
  -== Obtain Consensus
  +
  +== Preparation
  +
  +=== Obtain Consensus
   
   Before releasing the framework, ensure there is consensus on the xref:docs:support:mailing-list.adoc[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.
  
positive.code: 
  NOTE: After release, there is a xref:comguide:ROOT:cutting-a-release.adoc#reset-revision[similar step at the end] to reset back to `2.0.0-SNAPSHOT`.
  
  === 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,subs="attributes+"]
  .find unapproved/missing licenses
  ----
  mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=100
  
  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
  
  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]
  .verify no unapproved/missing licenses
  ----
  mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=0
  
  for a in `/bin/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.
  
  It's first necessary to have built the framework locally at least once:
  
  [source,bash,subs="attributes+"]
  ----
  mvn clean install -o
  ----
  
  Once this is done, capture the missing license information using:
  
  [source,bash,subs="attributes+"]
  ----
  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,subs="attributes+"]
  ----
  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.
  
  === Commit changes
  
  Commit any changes from the preceding steps:
  
  [source,bash,subs="attributes+"]
  ----
  git commit -am "$ISISJIRA: updates to pom.xml etc for release"
  ----
  
  === Sanity check
  
  
negative.code: 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:
  
  [source,bash,subs="attributes+"]
  ----
  git checkout master
  git pull --ff-only
  ----
  
  Check that there are no snapshot dependencies:
  
  [source,bash,subs="attributes+"]
  ----
  grep SNAPSHOT $(/bin/find . -name pom.xml | grep -v target  sort)
  ----
  
  The only mention of `SNAPSHOT` should be in the `revision` property of the root `core-prent/pom.xml` file.
  
  Finally, switch to the `core-parent` directory:
  
  [source,bash,subs="attributes+"]
  ----
  cd core-parent
  ----
  
  === 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,subs="attributes+"]
  .find unapproved/missing licenses
  ----
  mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=100
  
  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
  
  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]
  .verify no unapproved/missing licenses
  ----
  mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=0
  
  for a in `/bin/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.
  
  It's first necessary to have built the framework locally at least once:
  
  [source,bash,subs="attributes+"]
  ----
  mvn clean install -o
  ----
  
  Once this is done, capture the missing license information using:
  
  [source,bash,subs="attributes+"]
  ----
  mvn license:download-licenses
  groovy ../scripts/checkmissinglicenses.groovy
  ----
  
  WARNING: this groovy script assumes it is being run from the `core-parent` directory.
  
  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,subs="attributes+"]
  ----
  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.
  
  === Commit changes
  
  Commit any changes from the preceding steps:
  
  [source,bash,subs="attributes+"]
  ----
  git commit -am "$ISISJIRA: updates to pom.xml etc for release"
  ----
  
  
  == Releasing the Framework
  
  === Set environment variables
  
  We use environment variables to parameterize as many of the steps as possible.
  For example:
  