Add basic migration guide for WebSocket changes between 9.4 and 10.

Signed-off-by: Lachlan Roberts <lachlan@webtide.com>

documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc

@@ -24,3 +24,4 @@ include::server/server.adoc[]
 include::maven/maven.adoc[]
 include::arch.adoc[]
 include::troubleshooting.adoc[]
+include::migration/migration.adoc[]

documentation/jetty-documentation/src/main/asciidoc/programming-guide/migration/migration.adoc

@@ -0,0 +1,82 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[appendix]
+[[_migration]]
+== Migration Guides
+
+[[_migration_94_to_10]]
+=== Migrating from Jetty 9.4.x to Jetty 10.0.x
+
+==== Required Java Version Changes
+
+[cols="1,1", options="header"]
+|===
+| Jetty 9.4.x | Jetty 10.0.x
+| Java 8 | Java 11
+|===
+
+=== WebSocket Migration Guide
+
+Migrating from Jetty 9.4.x to Jetty 10.0.x requires changes in the coordinates of the Maven artifact dependencies for WebSocket. Some of these classes have also changed name and package. This is not a comprehensive list of changes but should cover the most common changes encountered during migration.
+
+==== Maven Artifacts Changes
+
+[cols="1a,1a", options="header"]
+|===
+| Jetty 9.4.x | Jetty 10.0.x
+
+| `org.eclipse.jetty.websocket:**websocket-api**`
+| `org.eclipse.jetty.websocket:**websocket-jetty-api**`
+
+| `org.eclipse.jetty.websocket:**websocket-server**`
+| `org.eclipse.jetty.websocket:**websocket-jetty-server**`
+
+| `org.eclipse.jetty.websocket:**websocket-client**`
+| `org.eclipse.jetty.websocket:**websocket-jetty-client**`
+
+| `org.eclipse.jetty.websocket:**javax-websocket-server-impl**`
+| `org.eclipse.jetty.websocket:**websocket-javax-server**`
+
+| `org.eclipse.jetty.websocket:**javax-websocket-client-impl**`
+| `org.eclipse.jetty.websocket:**websocket-javax-client**`
+
+|===
+
+==== Class Names Changes
+
+[cols="1a,1a", options="header"]
+|===
+| Jetty 9.4.x | Jetty 10.0.x
+
+| `org.eclipse.jetty.websocket.**server.NativeWebSocketServletContainerInitializer**`
+| `org.eclipse.jetty.websocket.**server.config.JettyWebSocketServletContainerInitializer**`
+
+| `org.eclipse.jetty.websocket.**jsr356.server.deploy.WebSocketServerContainerInitializer**`
+| `org.eclipse.jetty.websocket.**javax.server.config.JavaxWebSocketServletContainerInitializer**`
+
+| `org.eclipse.jetty.websocket.**servlet.WebSocketCreator**`
+| `org.eclipse.jetty.websocket.**server.JettyWebSocketCreator**`
+
+| `org.eclipse.jetty.websocket.**servlet.ServletUpgradeRequest**`
+| `org.eclipse.jetty.websocket.**server.JettyServerUpgradeRequest**`
+
+| `org.eclipse.jetty.websocket.**servlet.ServletUpgradeResponse**`
+| `org.eclipse.jetty.websocket.**server.JettyServerUpgradeResponse**`
+
+| `org.eclipse.jetty.websocket.**servlet.WebSocketServlet**`
+| `org.eclipse.jetty.websocket.**server.JettyWebSocketServlet**`
+
+| `org.eclipse.jetty.websocket.**servlet.WebSocketServletFactory**`
+| `org.eclipse.jetty.websocket.**server.JettyWebSocketServletFactory**`
+|===