Update release notes for forthcoming 1.6.0 release

RELEASE_NOTES.adoc

@@ -1,67 +1,71 @@
-= NNG Release Notes
+ifdef::env-github[]
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+endif::[]
 
-== Release 1.3.0 (since 1.2.6)
+= RELEASE NOTES FOR NNG v1.6.0
 
-=== Features
+After a very long time indeed (over 2 years!), we are happy to announce v1.6.0 of NNG!
 
-* Support for TLS 1.3 and external TLS providers.
-  There is now an API whereby external "`engines`" can be developed
-  for different TLS implementations.  The first of these, for wolfSSL,
-  is available.  Set this with the `NNG_TLS_ENGINE` cmake option.
-  The default is still to use Mbed TLS.  The wolfSSL plugin is
-  available under a different license (GPLv3 or commercial), and also
-  provides support for TLS 1.3 and FIPS 140-2 capable solutions.
+This document has the following sections:
 
-* Message cloning and related performance improvements.  This is not
-  a feature, so much as a rather large improvement in terms of performance.
-  All workloads will see some benefit -- some will see substantial benefits.
+* Notable Changes
+* End of Feature Announcements
 
-* Numerous other performance improvements.  Much effort was made to
-  reducing allocations, improving cache effectiveness, and eliminating
-  extra context switches.  This work is not yet done, but this is a big
-  step in the right direction.
+== Notable Changes (since 1.5.2)
 
-* HTTP Server support for "non-exclusive" registration -- a given handler
-  may be registered as a fallback handler (e.g. for a directory), even if
-  more specific handlers are registered.
+Numerous critical bugs were fixed; some of these led to seg faults, crashes, and
+memory leaks.  See bugs #1523, #1713, #1702, #1657, #1347, #1518, #1526, #1541, #1638, #1543, #1657, #1658
 
-* Performance test programs grew more options to select different
-  protocols and to change the URL to test across different transports.
+Significant performance optimizations have been made, especially to the BUS protocol, the
+`nng_sendmsg()` and `nng_recvmsg()` functions, when connecting and disconnecting lots of pipes,
+and when using very different expiration times with vast numbers of requests.
 
-=== Notable Bug Fixes
+New APIs were added for `nng_aio_busy()`, `nng_ctx_sendmsg()`, `nng_ctx_recvmsg()`, `nng_device_aio()`.
 
-* Thread count is limited.
-  Previously we would spawn potentially vast numbers of threads based on the
-  number of available cores.  By default we set an upper limit on this that
-  is about 20 threads.  Tune this with the `NNG_MAX_TASKQ_WORKERS` cmake option.
+A CMake tunable for limiting the number of threads use for request expiration is provided
+via the `NNG_MAX_EXPIRE_THREADS` option.
 
-* Raw mode fixes for XREQ and XRESPONDENT.  These protocols used the raw mode
-  inconsistently, leaving the header in the message body.  This is corrected
-  and the protocol headers are kept in the message headers.  There is some small
-  risk that some applications broken, but we are not aware of any that used
-  RAW mode to parse message headers.
+Additionally various fixes for compilation problems, documentation errata, test case, and so forth
+have been applied.
 
-* HTTP Server root URL handling had a few issues which are resolved.
+== End of Feature Announcements
 
-* Some platforms had difficult building due to inconsistencies in the
-  handling of atomics.
+=== Windows Legacy Support
 
-* Numerous test suites uncovered small (rare) races, etc.  The tests
-  themselves were often racy.  Fixes to both NNG and the tests have been
-  made, while increasing overall test coverage.
+NNG no longer officially claims support for Windows Vista, Windows 7, Windows 8, or Windows 8.1.
+We have no ability to build or test these versions, and Microsoft no longer supports them.
+Continued use of these systems may be possible, but future changes may break
+compatibity with these systems wihout further notice.
 
-* REP protocol with SENDFD was inconsistent (#1088).
+=== Windows Named Pipe Support Changes
 
-=== Other Changes
+A future release of NNG may make the ipc:// URL format operate over UNIX domain sockets by default.
+We plan to do this for the other projects we control, such as mangos, as well.
 
-* Polyamorous Pair v1 mode is changed, such that a new API call is needed
-  to use it.  Further, this mode will likely be removed in a future release.
-  Note that this mode also does not work with other implementations, nor
-  does it support operation with `nng_device()`.
+Should this occur, it will be breaking for Windows versions older than Windows 10 17063.
 
-* Maximum hop count across `nng_device()` proxies is now limited to 15.
-  This limit should be sufficient for all reasonable configurations,
-  and forcing this allowed us to to inline the header for performance
-  reasons.
+=== macOS Legacy Support
 
-* The nng_msg_options support was removed.  It was not used for anything.
+NNG no longer officially supports macOS versions older than 10.12.
+Future versions of NNG may depend on features not available on versions of macOS older than 10.12.
+
+=== Documentation Restructuring
+
+A future release of NNG may restructure the documentation to make it more
+approachable for more users.  This would break the organization as UNIX manual
+pages, and would also drop the ability to format them as UNIX nroff source.
+The best way to view this documentation is on the NNG website, or with the PDF or printed manual.
+
+=== ZeroTier Incompatible Changes
+
+A future release of NNG may break compatibility for applications built using earlier versions
+of NNG when using the ZeroTier transport.  ZeroTier support is an experimental feature.
+
+=== Pair1 Polyamorous Mode
+
+A future release of NNG may remove Pair 1 Polyamorous support, but *only* if a suitable
+replacement is provided.  Pair1 Polyamorous mode is an experimental feature.
+
+Alternatively we may change the Pair1 wire protocol in a way that breaks compatibility with
+earlier versions of Pair1 Polyamorous mode.