Merge lp:~nwilliams/akiban-persistit/release-notes-3.1.4 into lp:akiban-persistit

[Nathan Williams]

Update release notes, add simple README, and add md5 generation to release script.

Release notes are as Peter and Tim previously put together, with slight elaboration, summaries and formatting.

Simple md5 generation on all the resulting artifacts from the release script so the Jenkins job doesn't have to do it.

Also add a simple README file that was cobbled together from the introduction to the ReleaseNotes and the first chunk of the GettingStarted docs. It's a simple start, that doesn't have the extra stuff in the release notes, and also makes the project look nice on GitHub (see https://github.com/nathanlws/persistit#readme).

LBJ: NO_BUILD

[Peter Beaman (pbeaman)]

Excellent. Thanks for the cleanup and the README file.

review: Approve

=== added file 'README.rst'
--- README.rst	1970-01-01 00:00:00 +0000
+++ README.rst	2012-08-02 21:28:43 +0000
@@ -0,0 +1,64 @@
+************************************
+Akiban Persistit
+************************************
+
+Overview
+========
+We have worked hard to make Akiban Persistit™ exceptionally fast, reliable, simple and lightweight. We hope you will enjoy learning more about it and using it.
+
+Akiban Persistit is a key/value data storage library written in Java™. Key features include:
+
+- Support for highly concurrent transaction processing with multi-version concurrency control
+- Optimized serialization and deserialization mechanism for Java primitives and objects
+- Multi-segment (compound) keys to enable a natural logical key hierarchy
+- Support for long records (megabytes)
+- Implementation of a persistent SortedMap
+- Extensive management capability including command-line and GUI tools
+
+See http://www.akiban.com/akiban-persistit for a more detailed summary of features and benefits, licensing information and how to get support.
+
+Documentation
+=============
+Users Guide: http://www.akiban.com/ak-docs/admin/persistit
+
+JavaDoc: http://www.akiban.com/sites/all/libraries/persistit-api/index.html
+
+Building Akiban Persistit From Source
+=====================================
+Use Maven (http://maven.apache.org) to build Persistit.
+
+To build::
+
+  mvn install
+
+The resulting jar files are in the ``target`` directory. To build the Javadoc::
+
+  mvn javadoc:javadoc
+
+The resulting Javadoc HTML files are in ``target/site/apidocs``.
+
+Building and Running the Examples
+---------------------------------
+
+Small examples are located in the ``examples`` directory. Each has a short README file describing the example, and an Ant build script (http://ant.apache.org). After building the main akiban-persisit jar file using Maven, you may run::
+
+  ant run
+
+in each of the examples subdirectories to build and run the examples.
+
+
+Download and Install Akiban Persistit From Binaries
+---------------------------------------------------
+
+Pre-built jars can be downloaded directlry from http://akiban.com/akiban-persistit.
+
+Unpack the distribution kit into a convenient directory using the appropriate utility (e.g. unzip or tar).
+
+Review the ``LICENSE.txt`` file located in the root of the installation directory. Persistit is licensed under the Eclipse Public License or a free-use community license, see our `licensing options <http://www.akiban.com/akiban-licensing-options>`_ for more details. By installing, copying or otherwise using the Software contained in the distribution kit, you agree to be bound by the terms of the license agreement. If you do not agree to these terms, remove and destroy all copies of the software in your possession immediately.
+
+Working With Persistit
+----------------------
+
+Add the ``akiban-persistit-3.1.4.jar`` file, found in the root directory of the distribution kit, to your project's classpath. For example, copy it to ``jre/lib/ext`` in your Java Runtime Environment, or add it to your classpath environment variable. 
+
+That's it. You are ready to work with Persistit.

=== modified file 'build_release.sh'
--- build_release.sh	2012-08-02 14:45:58 +0000
+++ build_release.sh	2012-08-02 21:28:43 +0000
@@ -46,6 +46,36 @@
     mvn $2 -DBZR_REVISION="$1" -DskipTests=true clean compile test-compile package >/dev/null
 }
 
+MD5_TYPE=""
+function md5_type {
+    if [ "$(which md5sum)" != "" ]; then
+        MD5_TYPE="md5sum"
+    else
+        if [ "$(which md5)" != "" ]; then
+            MD5_TYPE="md5"
+        else
+            echo "    No supported md5 program found in PATH" 1>&2
+            exit 1
+        fi
+    fi
+}
+
+function do_md5 {
+    OUTFILE="${1}.md5"
+    case "${MD5_TYPE}" in
+        md5)
+            $(md5 -r "$1" |sed 's/ /  /' > "${OUTFILE}")
+        ;;
+        md5sum)
+            $(md5sum "$1" > "${OUTFILE}")
+        ;;
+        *)
+            echo "Unknown md5 type: ${MD5_TYPE}"
+            exit 1
+        ;;
+    esac
+}
+
 
 REQUIRED_PROGS="bzr mvn javac sphinx-build curl awk sed tr basename zip tar gpg"
 BRANCH_DEFAULT="lp:~akiban-technologies/akiban-persistit"
@@ -58,7 +88,7 @@
 while getopts "hb:v:w:" FLAG; do
     case "${FLAG}" in
         h) ;;
-        b) BRANCH="${OPTARG}" ;;
+        b) BRANCH_URL="${OPTARG}" ;;
         v) VERSION="${OPTARG}" ;;
         w) WORKSPACE="${OPTARG}" ;;
         *) echo "Unhandled option" 1>&2 ; exit 1 ;;
@@ -70,7 +100,7 @@
     exit 1
 fi
 
-if [ "${BRANCH}" = "" ]; then
+if [ "${BRANCH_URL}" = "" ]; then
     BRANCH_URL="${BRANCH_DEFAULT}/${VERSION}"
 fi
 
@@ -88,6 +118,9 @@
     fi
 done
 
+echo "Checking for md5 program"
+md5_type
+
 
 NAME="akiban-persistit"
 BRANCH_DIR="${WORKSPACE}/${VERSION}"
@@ -191,6 +224,7 @@
     echo "Signing files for Launchpad upload"
     for FILE in `ls *.zip *.tar.gz`; do
         gpg --armor --sign --detach-sig "${FILE}" 1>/dev/null
+        do_md5 "${FILE}"
     done
 fi
 

=== modified file 'doc/ReleaseNotes.rst'
--- doc/ReleaseNotes.rst	2012-07-13 13:33:22 +0000
+++ doc/ReleaseNotes.rst	2012-08-02 21:28:43 +0000
@@ -45,6 +45,86 @@
 |
 
 ************************************
+3.1.4
+************************************
+
+Release Date
+============
+August 3, 2012
+
+Overview
+========
+This version of Persistit changes the licensing to Eclipse Public License (EPL) and includes minor enhancements and bug fixes.
+
+New Features
+============
+
+Detection and Ignoring of Missing Volumes
+-----------------------------------------
+
+Warnings are now issues when a previously existing volume is missing, and an option to allow a system to continue by ignoring pages and transactions in the journal from missing volumes.
+
+Every time Persistit writes a modified page to disk, it does so first to the journal.  During recovery processing, the page images from the journal are analyzed and reinserted into volumes in such a way that all B+Trees are restored to a consistent state. The issue addressed in this change is how Persistit behaves during recovery if it discovers that a volume referred to by a page in the journal no longer exists.
+
+Recognizing that under some circumstances an administrator may indeed wish to remove a volume from an existing Database, this change provides a configurable switch to optionally allow pages from missing volumes to be skipped (with logged warning messages) during recovery processing.  The switch can be enabled by setting the configuration parameter ignoreMissingVolumes to true, see com.persistit.Configuration#setIgnoreMissingViolumes.
+
+
+Reduce KeyCoder Serialized Object Size
+--------------------------------------
+
+.. note::
+   Any Database containing objects serialized by a custom KeyCoder from a previous version of Persistit is incompatible with this change
+
+Minimize the per-instance overhead for application objects written into Persistit Keys by reducing the size of the internal identifier.
+
+Persistit has rich support for serializing standard Java primitive and object types into a Key. Additionally, the KeyCoder class allows for any application level object to also be appended to a Key right next to any other type. This is tagged internally with per-class handles. This change lowers the initial offset to, in many cases, halve the serialized size. 
+
+Maven POM Changes For Eclipse Juno
+----------------------------------
+
+The latest version of Eclipse, code named Juno, features a wide array of changes, including a new release of the m2eclipse plugin. In an effort to make getting started with Persistit as easy as possible, we have included the required m2e configuration sections in our pom.
+
+Please contact Akiban if you have encounter any issues getting up and running with Persistit.   
+
+Fixed Issues
+============
+
+Old Journal Files Not Being Deleted
+-----------------------------------
+
+https://launchpad.net/akiban-persistit/+bug/1028016
+
+If a volume was removed from the configuration and Persistit was restarted the associated journal files would not be removed due to internal safety checks. In the event that the missing volume is intended behavior, a new configuration option was added. See the ``Detection and Ignoring of Missing Volumes`` feature description for more details.
+
+Class Index Updates Causing Write-Write Dependencies
+----------------------------------------------------
+
+https://launchpad.net/akiban-persistit/+bug/1024857
+
+https://launchpad.net/akiban-persistit/+bug/1026207
+
+Custom classes that are serialized into keys or values, through a custom KeyCoder or ValueCoder, are given a unique identifier. The identifier is determined transactionally the first time a class is written and stored in an internal tree. This would cause seemingly spurious aborts if more than one application threads simultaneously attempt to store the first instance of a given class.
+
+Accumulator Memory Usage and Transaction Step Policy
+----------------------------------------------------
+
+https://launchpad.net/akiban-persistit/+bug/1028050
+
+https://launchpad.net/akiban-persistit/+bug/1028134
+
+Changes to Accumulators are stored were previously stored as individual Delta objects. For long running transactions that heavily utilized Accumulators, this would cause excessive memory usage. These unique instances are no eliminated in most scenarios, resulting in no memory growth in all but pathological cases.
+
+Additionally, the Accumulator handling of the Transaction step value was inconsistent with how it was treated through an Exchange. Now, both classes allow a given step x to see any change that occurred at a step less than or equal to itself.
+
+
+Known Issues
+============
+As described in the *3.1.1 Known Issues*.
+
+|
+|
+
+************************************
 3.1.2
 ************************************