release notes for OpenSRF 2.4.0-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..66b2b33
--- /dev/null
+++ b/doc/RELEASE_NOTES.txt
@@ -0,0 +1,121 @@
+Release notes for OpenSRF 2.4.0-alpha
+=====================================
+
+Supported platforms
+-------------------
+The following Linux distributions are supported:
+
+  * Debian 6 (Squeeze), 7 (Wheezy), and 8 (Jessie)
+  * Fedora 17, 18
+  * Ubuntu 12.04 LTS (Precise Pangolin) and 14.04 (Trusty Tahr)
+
+New features in 2.4.0-alpha
+---------------------------
+
+WebSockets support (LP#1268619)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+WebSockets are a standards-compliant, cross-browser mechanism to support
+streaming, bi-directional communication between the browser and the
+server. For more information, see http://en.wikipedia.org/wiki/WebSocket
+
+OpenSRF now offers a WebSockets gateway via an Apache plugin
+as well as updates to the OpenSRF JavaScript client library to
+support WebSockets as a transport.
+
+To install the WebSockets gateway, follow the instructions
+in `README.websockets`.  By default, the WebSockets gateway
+listens on ports 7680 and 7682 and uses a separate Apache
+instance.
+
+Cross Origin Resource Sharing for OpenSRF (LP#1002028)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Browsers' same-origin policy currently restricts requests to the current
+website's domain to prevent various nefarious scenarios. However,
+because APIs and other web resources need to remain open to cross-site
+use, Cross Origin Resource Sharing (CORS) was created to allow services
+to formally authorize cross-origin requests. CORS makes it simple to use
+OpenSRF's HTTP translator and gateway APIs on websites using separate
+domains.
+
+A couple examples of scenarios where this would be useful:
+
+. A library would like an AJAX-driven "quicksearch" box on their main
+  site, which is hosted on a different domain than their catalog.
+. A developer wants to create new web applications and services that
+  tie into Evergreen, but does not wish to install Evergreen locally or
+  configure a proxy.
+
+Domains that are allowed to send cross-origin requests can now be
+specified in `opensrf_core.xml` as `cross_origin/origin` elements
+in the `gateway` element (full XPath `/config/gateway/cross_origin/origin`).
+
+Note that the OpenSRF Javascript client library (`opensrf.js`) currently
+defaults to the root of the current web host (`/osrf-http-translator`).
+In addition, synchronous requests are presumed in some situations,
+resulting in the oncomplete method never returning (as blocking requests
+are not possible with cross-domain XHR).
+
+Support for log tagging (LP#1343578)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is now possible to specify a log tag, i.e., a string to append
+to the application name in syslog message.  This allows easy filtering
+of log entries when running multiple OpenSRF instances on the same
+server.
+
+Log tags can be set by adding `logtag` elements in `opensrf_core.xml`.
+
+Enhancements in 2.4.0-alpha
+---------------------------
+
+JavaScript library now uses browser-native JSON routines (LP#1316245)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The routines `JSON2js` and `js2JSON` now use native browser JSON
+routines.  In addition, `jsonPretty` is removed in favor of
+`JSON.stringify`.
+
+Users of the OpenSRF JavaScript library should note that as a
+consequence of this change, `JSON2js` will now throw an exception
+if it is given input not is not a valid JSON string.
+
+Listeners now log and drop XMPP error messages (LP#1341687)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The most common form of XMPP error messages are "bounced" messages, i.e.
+those where the recipient is not available.  Instead of passing these
+useless and confusing messages down to a drone for processing, listeners
+now log the error and drop the message.
+
+An example of when this can occur is when a service is starting up and
+attempts to register with a router that is not yet available.
+
+Removes osrf_ctl.sh (LP#1286248)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The control script `osrf_ctl.sh` is removed in favor of `osrf_control`,
+which was introduced in OpenSRF 2.3.0.
+
+Improved docgen output(LP#1292214)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Docgen output now respects formatting present in method description.
+
+Other enhancements
+~~~~~~~~~~~~~~~~~~
+  * Add support for Debian Jessie (LP#1306044)
+  * Add support for Ubuntu Trusty (and removes support for Lucid) (LP#1315525)
+  * Remove deprecated Jabber registration script (LP#1306044)
+  * Improve const-correctness of osrfCachePutString and osrfCachePutObject (LP#1234816)
+  * Document that perl2JSON doesn't order hash keys (LP#1285915)
+  * Reorder changes to ejabberd.cfg in the install instructions
+
+Bugfixes in 2.4.0-alpha
+-----------------------
+
+OpenSRF.pm no longer supplies AUTOLAOD (LP#1179660)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Instead of simply producing an error message in the OpenSRF logs, calls
+to nonexistent subroutines are now fatal errors which will stop code
+execution.
+
+`osrf_control` only affects processed owned by current user LP#1337401
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+As of 2.3.0, OpenSRF can readily support running multiple instances on
+one server. This bugfix ensures that `osrf_control` only affects OpenSRF
+processes owened by the current user.