docs: Provide migration guidance.

2 files changed, 165 insertions, 0 deletions

diff --git a/docs/migrating/nanomsg.md b/docs/migrating/nanomsg.md
new file mode 100644
index 00000000..e4c7b184
--- /dev/null
+++ b/docs/migrating/nanomsg.md
@@ -0,0 +1,115 @@
+# Migrating from libnanomsg
+
+Previous version of NNG offered direct API compatibility with _libnanomsg_,
+but that support is no longer offered in this version.
+
+If your application is still using legacy _libnanomsg_ APIs, you will need to
+update it for this version of NNG.
+
+## Header Files
+
+Most applications can replace all `#include <nn/*.h>` statements with `#include <nng/nng.h>`.
+
+## Link Libraries
+
+Replace `-lnanomsg` with `-lnng`.
+It may be necessary to include additional system libraries, such as `-lpthread`, depending on your system.
+
+## Types
+
+Sockets, dialers, and listeners in _libnanomsg_ are simple integers.
+In NNG, these are `struct` types.
+
+Messages are quite different in NNG, with the absence of the POSIX message control
+headers.
+
+The `struct nn_msghdr` structure has no equivalent. See `nng_msg` for the
+NNG approach to messages. Likewise there is no `struct nn_cmsghdr` equivalent.
+
+## API Conversions
+
+| Nanomsg API         | NNG Equivalent                                                     | Notes                                                                                                 |
+| ------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `nn_strerror`       | `nng_strerror`                                                     |
+| `nn_errno`          | No equivalent. Errors are redirectly rather than through `errno`.  |
+| `nn_socket`         | Use the appropriate protocol constructor, such as `nng_req0_open`. |
+| `nn_close`          | `nng_close`                                                        |
+| `nn_bind`           | `nng_listen`, `nng_listener_create`                                | Allocating a listener with `nng_lister_create` and configuring it offers more capabilities.           |
+| `nn_connect`        | `nng_dial`, `nng_dialer_create`                                    | Allocating a dialer with `nng_dialer_create` and configuring it offers more capabilities.             |
+| `nn_shutdown`       | `nng_lister_close`, `nng_dialer_close`                             |
+| `nn_allocmsg`       | `nng_msg_alloc`                                                    | There are significant semantic differences.                                                           |
+| `nn_freemsg`        | `nng_msg_free`                                                     |
+| `nn_reallocmsg`     | `nng_msg_realloc`                                                  |
+| `nn_send`           | `nng_send`                                                         |
+| `nn_recv`           | `nng_recv`                                                         |
+| `nn_sendmsg`        | `nng_sendmsg`                                                      |
+| `nn_getsockopt`     | `nng_socket_get`                                                   | NNG has typed accessors for options, and also separate functions for dialers and listeners.           |
+| `nn_setsockopt`     | `nng_socket_set`                                                   |
+| `nn_device`         | `nng_device`                                                       |
+| `nn_poll`           | None                                                               | Can be constructed using `nng_aio`. Few if any applications ever used this API.                       |
+| `nn_term`           | None                                                               | The `nng_fini` API can do this, but is not recommended except when debugging memory leaks.            |
+| `nn_get_statistic`  | `nng_stats_get`                                                    | The statistics in NNG are completely different, with different semantics and no stability guarantees. |
+| `NN_POLLIN`         | None                                                               | Used only with `nn_poll`.                                                                             |
+| `NN_POLLOUT`        | None                                                               | Used only with `nn_poll`.                                                                             |
+| `NN_MSG`            | `NNG_FLAG_ALLOC`                                                   | See `nng_send` and `nng_recv` for details.                                                            |
+| `NN_CMSG_ALIGN`     | None                                                               |
+| `NN_CMSG_FIRSTHDR`  | None                                                               |
+| `NN_CMSG_NXTHDR`    | None                                                               |
+| `NN_CMSG_DATA`      | None                                                               |
+| `NN_CMSG_LEN`       | None                                                               |
+| `NN_CMSG_SPACE`     | None                                                               |
+| `struct nn_iovec`   | `nng_iov`                                                          |
+| `struct nn_msghdr`  | `nng_msg`                                                          |
+| `struct nn_cmsghdr` | `nng_msg` and `nng_msg_header`                                     |
+
+## Options
+
+The following options are changed.
+
+| Nanomsg Option         | NNG Eqvaivalent      | Notes                                                   |
+| ---------------------- | -------------------- | ------------------------------------------------------- |
+| `NN_LINGER`            | None                 | NNG does not support tuning this.                       |
+| `NN_SNDBUF`            | `NNG_OPT_SENDBUF`    | NNG value is given in messages, not bytes.              |
+| `NN_RCVBUF`            | `NNG_OPT_RECVBUF`    | NNG value is given in messages, not bytes.              |
+| `NN_SNDTIMEO`          | `NNG_OPT_SENDTIMEO`  |
+| `NN_RCVTIMEO`          | `NNG_OPT_RECVTIMEO`  |
+| `NN_RECONNECT_IVL`     | `NNG_OPT_RECONNMINT` |
+| `NN_RECONNECT_IVL_MAX` | `NNG_OPT_RECONNMAXT` |
+| `NN_SNDPRIO`           | None                 | Not supported in NNG yet.                               |
+| `NN_RCVPRIO`           | None                 | Not supported in NNG yet.                               |
+| `NN_RCVFD`             | `NNG_OPT_RECVFD`     |
+| `NN_SNDFD`             | `NNG_OPT_SENDFD`     |
+| `NN_DOMAIN`            | None                 | NNG options are not divided by domain or protocol.      |
+| `NN_PROTOCOL`          | `NNG_OPT_PROTO`      | See also `NNG_OPT_PROTONAME`.                           |
+| `NN_IPV4ONLY`          | None                 | Use URL such as `tcp4://` to obtain this functionality. |
+| `NN_SOCKET_NAME`       | `NNG_OPT_SOCKNAME`   |
+| `NN_MAXTTL`            | `NNG_OPT_MAXTTL`     |
+
+## Error Codes
+
+Most of the error codes have similar names in NNG, just prefixed with `NNG_`.
+There are some exceptions. Be aware that the numeric values are _not_ the same.
+
+| Nanomsg Error  | NNG Error                                                                      | Notes                                                                              |
+| -------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| `EINTR`        | `NNG_EINTR`                                                                    |                                                                                    |
+| `ENOMEM`       | `NNG_ENOMEM`                                                                   |                                                                                    |
+| `EINVAL`       | `NNG_EINVAL`, `NNG_EADDRINVAL`, `NNG_EBADTYPE`, `NNG_EAMBIGUOUS`               | NNG discrimates between different types of errors.                                 |
+| `EBUSY`        | `NNG_EBUSY`                                                                    |                                                                                    |
+| `ETIMEDOUT`    | `NNG_ETIMEDOUT`                                                                |                                                                                    |
+| `ECONNREFUSED` | `NNG_ECONNREFUSED`                                                             |                                                                                    |
+| `EBADF`        | `NNG_ECLOSED`, `NNG_ECANCELED`                                                 | Canceling an operation returns differently than using an invalid or closed object. |
+| `EAGAIN`       | `NNG_EAGAIN`                                                                   |
+| `ENOTSUP`      | `NNG_ENOTSUP`                                                                  |
+| `EADDRINUSE`   | `NNG_EADDRINUSE`                                                               |
+| `EFSM`         | `NNG_ESTATE`                                                                   | Not a legal POSIX _errno_ value.                                                   |
+| `ENOENT`       | `NNG_ENOENT`                                                                   |
+| `EPROTO`       | `NNG_EPROTO`                                                                   |
+| `EHOSTUNREACH` | `NNG_EUNREACHABLE`                                                             |
+| `EACCCES`      | `NNG_EPERM`, `NNG_EWRITEONLY`, `NNG_EREADONLY`, `NNG_ECRYPTO`, `NNG_EPEERAUTH` | NNG has more fine grained reasons for access failures.                             |
+| `EMSGSIZE`     | `NNG_EMSGSIZE`                                                                 |
+| `ECONNABORTED` | `NNG_ECONNABORTED`                                                             |
+| `ECONNRESET`   | `NNG_ECONNRESET`                                                               |
+| `EEXIST`       | `NNG_EEXIST`                                                                   |
+| `EMFILE`       | `NNG_ENOFILES`                                                                 |
+| `ENOSPC`       | `NNG_ENOSPC`                                                                   |
diff --git a/docs/migrating/nng1.md b/docs/migrating/nng1.md
new file mode 100644
index 00000000..b0afb888
--- /dev/null
+++ b/docs/migrating/nng1.md
@@ -0,0 +1,50 @@
+# Migrating from NNG 1.x
+
+There are some incompatibities from NNG 1.x.
+This guide should help in migrating applications to use NNG 2.0.
+
+## Nanomsg Compatibility
+
+Applications using the legacy `libnanomsg` API will have to be updated to native NNG interfaces.
+See the [Migration Guide for libnanomsg](nanomsg.md) for details.
+
+## Transport Specific Functions
+
+Transports have not needed to be registered for a long time now,
+and the functions for doing so have been removed. These functions
+can be simply removed from your application:
+
+- `nng_inproc_register`
+- `nng_ipc_register`
+- `nng_tls_register`
+- `nng_tcp_register`
+- `nng_ws_register`
+- `nng_wss_register`
+- `nng_zt_register`
+
+Additionally, the header files containing these functions have been removed, such as
+`nng/transport/ipc/ipc.h`. Simply remove `#include` references to those files.
+
+(Special exception: The options for ZeroTier are still located in the
+`nng/transport/zerotier/zerotier.h`.)
+
+The `NNG_OPT_WSS_REQUEST_HEADERS` and `NNG_OPT_WSS_RESPONSE_HEADERS` aliases for
+`NNG_OPT_WS_OPT_WS_REQUEST_HEADERS` and `NNG_OPT_WS_RESPONSE_HEADERS` have been removed.
+Just convert any use of them to `NNG_OPT_WS_REQUST_HEADERS` or
+`NNG_OPT_WS_RESPOSNE_HEADERS` as appropriate.
+
+## Option Functions
+
+The previously deprecated `nng_pipe_getopt_xxx` family of functions is removed.
+Applications should use `nng_pipe_get` and related functions instead.
+
+The socket option function families for `nng_getopt` and `nng_setopt` have been removed as well.
+In this case, use the `nng_socket_get` and `nng_socket_set` functions as appropriate.
+
+## Transport Options
+
+A number of transport options can no longer be set on the socket. Instead these
+options must be set on the endpoint (dialer or listener) using the appropriate
+`nng_dialer_set` or `nng_listener_set` option. This likely means that it is necessary
+to allocate and configure the endpoint before attaching it to the socket. This will
+also afford a much more fine-grained level of control over transport options.