From 61d0a41103fc58bfab49552d680b59f39608d038 Mon Sep 17 00:00:00 2001
From: Damien Arrachequesne <damien.arrachequesne@gmail.com>
Date: Sat, 10 Jul 2021 11:24:29 +0200
Subject: [PATCH] docs: add compatibility table

---
 README.md                   |  2 +-
 Usage Docs/15to16.md        | 19 ++++++++++++
 Usage Docs/Compatibility.md | 61 +++++++++++++++++++++++++++++++++++++
 3 files changed, 81 insertions(+), 1 deletion(-)
 create mode 100644 Usage Docs/Compatibility.md

diff --git a/README.md b/README.md
index ab883f9..8e1273e 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ socket.connect()
 ```
 
 ## Features
-- Supports socket.io 2.0+/3.0+.
+- Supports Socket.IO server 2.0+/3.0+/4.0+ (see the [compatibility table](https://nuclearace.github.io/Socket.IO-Client-Swift/Compatibility.html))
 - Supports Binary
 - Supports Polling and WebSockets
 - Supports TLS/SSL
diff --git a/Usage Docs/15to16.md b/Usage Docs/15to16.md
index c238926..d50fd8d 100644
--- a/Usage Docs/15to16.md	
+++ b/Usage Docs/15to16.md	
@@ -13,4 +13,23 @@ is socket.io 2, you must send `.version(.two)` as an option to the manager.
 SocketManager(socketURL: URL(string:"http://localhost:8087/")!, config: [.version(.two)])
 ```
 
+## How to upgrade
 
+- first, upgrade the Socket.IO server to v4 with the compatibility mode enabled (`allowEIO3: true`)
+- then, upgrade the clients to v16
+- finally, once all clients have upgraded, disable the compatibility mode
+
+You can check the version of the connection on the server side with:
+
+```js
+io.on("connection", (socket) => {
+  // either 3 for the 3rd revision of the protocol (Socket.IO v2) or 4 for the 4th revision (Socket.IO v3/v4)
+  const version = socket.conn.protocol;
+});
+```
+
+See also:
+
+- [Compatibility table](https://nuclearace.github.io/Socket.IO-Client-Swift/Compatibility.html)
+- Migrating from 2.x to 3.0: https://socket.io/docs/v4/migrating-from-2-x-to-3-0/
+- Migrating from 3.x to 4.0: https://socket.io/docs/v4/migrating-from-3-x-to-4-0/
diff --git a/Usage Docs/Compatibility.md b/Usage Docs/Compatibility.md
new file mode 100644
index 0000000..9841073
--- /dev/null
+++ b/Usage Docs/Compatibility.md	
@@ -0,0 +1,61 @@
+Here is the compatibility table with the Node.js server:
+
+<table>
+    <tr>
+        <th rowspan="2">Swift Client version</th>
+        <th colspan="3">Socket.IO server version</th>
+    </tr>
+    <tr>
+        <td align="center">2.x</td>
+        <td align="center">3.x</td>
+        <td align="center">4.x</td>
+    </tr>
+    <tr>
+        <td align="center">v15.x</td>
+        <td align="center"><b>YES</b></td>
+        <td align="center"><b>YES</b><sup>1</sup></td>
+        <td align="center"><b>YES</b><sup>2</sup></td>
+    </tr>
+    <tr>
+        <td align="center">v16.x</td>
+        <td align="center"><b>YES</b><sup>3</sup></td>
+        <td align="center"><b>YES</b></td>
+        <td align="center"><b>YES</b></td>
+    </tr>
+</table>
+
+[1] Yes, with <code><a href="https://socket.io/docs/v4/server-initialization/#allowEIO3">allowEIO3: true</a></code> (server) and `.connectParams(["EIO": "3"])` (client):
+
+*Server*
+
+```js
+const { createServer } = require("http");
+const { Server } = require("socket.io");
+
+const httpServer = createServer();
+const io = new Server(httpServer, {
+  allowEIO3: true
+});
+
+httpServer.listen(8080);
+```
+
+*Client*
+
+```swift
+SocketManager(socketURL: URL(string:"http://localhost:8080/")!, config: [.connectParams(["EIO": "3"])])
+```
+
+[2] Yes, <code><a href="https://socket.io/docs/v4/server-initialization/#allowEIO3">allowEIO3: true</a></code> (server)
+
+[3] Yes, with `.version(.two)` (client):
+
+```swift
+SocketManager(socketURL: URL(string:"http://localhost:8080/")!, config: [.version(.two)])
+```
+
+See also:
+
+- Migrating from 2.x to 3.0: https://socket.io/docs/v4/migrating-from-2-x-to-3-0/
+- Migrating from 3.x to 4.0: https://socket.io/docs/v4/migrating-from-3-x-to-4-0/
+- Socket.IO protocol: https://github.com/socketio/socket.io-protocol