Add migration to WebAssembly information to PNaCl / NaCl docs.

native_client_sdk/src/doc/migration/index.rst

Index: native_client_sdk/src/doc/migration/index.rst
diff --git a/native_client_sdk/src/doc/migration/index.rst b/native_client_sdk/src/doc/migration/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0685ceb5088ba7e88d1d91f88e291400b509a341
--- /dev/null
+++ b/native_client_sdk/src/doc/migration/index.rst
@@ -0,0 +1,78 @@
+.. _migration:
+
+WebAssembly Migration Guide
+===========================
+
+(P)NaCl Deprecation Announcements
+---------------------------------
+
+We recently announced the deprecation of Portable NativeClient
+as well as the deprecation of
+`Chrome Apps
+<https://blog.chromium.org/2016/08/from-chrome-apps-to-web.html>`_
+outside of ChromeOS.
+As a result, in the near future, PNaCl will no longer be supported in Chrome.

[seththompson, 2017/05/17 22:08:16]

I think we should be sure to mention this is an "upcoming deprecation" and
mention the specific date that we announce in the post (Q1 2018).

[bradn, 2017/05/18 05:39:25]

Done by way of using the one below and reordering.

+And NaCl will be supported only in the context of ChromeOS and Extensions.
+
+We appreciate the investment you've made bringing native code to the Web

[seththompson, 2017/05/17 22:08:16]

I think this sentence is a bit jarring: it starts out with "we appreciate the
investment *you've* made"... and then ends with an implicit "[we] have now
refocused..."

Perhaps we can just reuse the paragraph from the blog post?

"Given the momentum of cross-browser WebAssembly support, we plan to focus our
native code efforts on WebAssembly going forward and plan to remove support for
PNaCl in Q1 2018 (except for Chrome Apps). We believe that the vibrant ecosystem
around WebAssembly makes it a better fit for new and existing high-performance
web apps and that usage of PNaCl is sufficiently low to warrant deprecation."
"

[bradn, 2017/05/18 05:39:25]

Done.

+with these pioneering solutions, but have now refocused our efforts
+on the cross browser `WebAssembly <http://webassembly.org>`_ standard
+in order to bring similar functionality to the Web in general.
+While WebAssembly currently cannot match all of (P)NaCl's capabilities,
+we are working to expand its capabilities in tandem with other
+browsers, and believe most use cases will soon be covered.
+
+
+Toolchain Migration
+-------------------
+
+For the majority of (P)NaCl uses cases we recommend transitioning
+from the NaCl SDK to `Emscripten
+<http://webassembly.org/getting-started/developers-guide/>`_.
+While direct support for NaCl / Pepper APIs in not available,
+we've attempted to list equivalents.
+Migration is likely to be reasonably straightforward
+if your application is portable to Linux, uses
+`SDL <https://www.libsdl.org/>`_, or POSIX APIs.
+For more challenging porting cases, please reach out on
+native-client-discuss@googlegroups.com
+
+
+API Migration
+-------------
+
+We've outlined here the status of Web Platform substitutes for each
+of the APIs exposed to (P)NaCl.
+Additionally, the table lists the library or option in Emscripten
+that offers the closest substitute.
+
+We expect to add shared memory threads support to WebAssembly in 2017,
+as threads are crucial to matching (P)NaCl's most interesting use
+cases. Migration items which assume forthcoming threads support
+are marked below. If your application's flow control relies heavily on blocking
+APIs, you may also find threads support is required for convenient porting.
+
+While we've tried to be accurate in this table,
+there are no doubt errors or omissions.
+If you encounter one, please reach out to us on
+native-client-discuss@googlegroups.com
+
+.. contents::
+  :local:
+  :backlinks: none
+  :depth: 2
+
+PPAPI
+-----
+.. raw:: html
+  :file: public.html
+
+IRT
+---
+.. raw:: html
+  :file: public.html
+
+PPAPI (Apps)
+------------
+.. raw:: html
+  :file: apps.html