release notes for 2.5-alpha

Signed-off-by: Galen Charlton <gmc@esilibrary.com>

diff --git a/doc/RELEASE_NOTES.txt b/doc/RELEASE_NOTES.txt
new file mode 100644 (file)
index 0000000..3c42366
--- /dev/null
+++ b/doc/RELEASE_NOTES.txt
@@ -0,0 +1,136 @@
+Release notes for OpenSRF 2.5.0-alpha
+=====================================
+
+Supported platforms
+-------------------
+The following Linux distributions are supported:
+
+  * Debian 7 (Wheezy) and 8 (Jessie)
+  * Fedora 17, 18
+  * Ubuntu 14.04 (Trusty Tahr) and 16.04 LTS (Xenial Xerus)
+
+New features in 2.5.0-alpha
+---------------------------
+
+Chunking and bundling (LP#1612771)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Message Bundling and Chunking
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+OpenSRF now supports message chunking, i.e., breaking up large OpenSRF
+messages across multiple XMPP envelopes. This is implemented with a
+new OpenSRF message type.
+
+C, Perl, and Javascript libraries are taught how to reconstruct chunked
+messages. The default chunking threshold is 50Kb, just a bit below the
+default ejabberd max stanza size of 64Kb.
+
+What was previously called chunking is now referred to as bundling:
+packing multiple OpenSRF messages together in a single XMPP envelope,
+as long as we believe more messages will be sent in the future and we
+are below some threshold of combined message size.  The default for
+that threshold is 25Kb.
+
+With this change, it is no longer necessary to change the `max_stanza_size`
+setting for ejabberd when installing OpenSRF.
+
+Pass client timezone to server (LP#1485371)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenSRF has long inspected the envelope of incoming requests for information
+about the client's locale and made this information available to business
+logic.  This is used, among other things, to drive transparent translation of
+in-database strings within Evergreen.  In addition to locale, OpenSRF will
+now respect client-supplied adjustment to the effective time zone in which it
+operates, and provide that information to the business logic layer of
+applications built on the framework.
+
+Client
+^^^^^
+
+As most clients that have time zones which differ from that of the server on
+which the OpenSRF processes run are, in fact, web browsers, it is necessary
+to include time zone detection directly within the browser.  This will be
+stored in a cookie to be sent with all subsequent HTTP requests, and used in
+all OpenSRF-over-HTTP calls made using the JavaScript bindings for OpenSRF,
+including those for WebSockets communication.
+
+For non-browser clients, such as support scripts written in Perl or other
+scripting languages, the local system's mechanisms for detecting time zone
+is relied upon.  For instance, Perl scripts can directly read the TZ
+environment variable.
+
+Additionally, the srfsh client now reads its local time zone from the
+environment and passes that to the server. 
+
+Server
+^^^^^^
+
+Within OpenSRF services implemented in Perl, this information is now passed up
+to the business logic layer via the TZ environment variable, and is reverted
+to the server's value at the end of each request.  This allows automatic,
+transparent use of the client's time zone in almost all cases, and provides a
+system-normal access mechanism when direct access is required.
+
+For OpenSRF services implemented in C, the time zone information is provided
+as part of the request context object that is passed to implementation
+functions.  In particular, this allows services that interact with a database
+to set the time zone in which the database interprets timestamps to that of
+the client.
+
+Dispatch mode for method_lookup subrequests (LP#1631522)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is a pattern in the wild of using OpenSRF's `method_lookup()` facility
+to decide between one of several local methods when delegating to pre-existing
+logic.  Often times, we want to simply hand control over to another method,
+but the output of a subrequest's `run()` is an array of results.  The caller has
+to know if, and how, to restructure the result for the client.
+
+Instead, we can now call `dispatch()` instead of `run()` and have OpenSRF session
+control completely passed to the delegate code.  This way, the delegate code
+need not know anything about its caller, and vice versa.
+
+Example proxy server configurations (LP#1638651 and LP#1648188)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenSRF 2.5 comes with example configurations for using HAProxy or
+NGINX as a reverse proxy for HTTP, HTTPS, and WebSockets traffic. This
+can be useful for Evergreen systems that wish to use port 443 for both
+HTTPS and secure WebSockets traffic.
+
+Allow admin to specify where perl modules will be installed (LP#1631520)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add `--with-perlbase` option to the `configure` to specify
+an alternative location for installing the Perl modules. This
+can be useful for setups that want to run the Perl modules
+from a shared filesystem or environments that need to run
+multiple versions of OpenSRF simultaneously.
+
+Users of `--with-perlbase` are responsible for ensuring that
+`PERL5LIB` is set appropriately.
+
+Other changes
+-------------
+
+  * Drop support for Debian Squeeze (LP#1559121)
+  * Drop support for Ubuntu Precise (LP#1603708)
+  * Add support for Ubuntu Xenial (LP#1551090)
+  * Fix a bug with syslog configuration (LP#1473479)
+  * Fix OpenSRF debian_sys_config order for Debian (LP#1585041)
+  * Improvements to the installation documentation (LP#1382038)
+
+Acknowledgements
+----------------
+
+We would like to thank the following people who contributed to OpenSRF 2.5:
+
+  * Ben Shum 
+  * Bill Erickson 
+  * Chris Sharp 
+  * Galen Charlton 
+  * Jason Etheridge 
+  * Jason Stephenson 
+  * Mike Rylander 
+  * Remington Steed