Add code tours

Summary:
[Code Tour](https://github.com/microsoft/codetour) is an extension which allows you to annotate an ordered list of code pointers with descriptions, as a way of touring you through a codebase.

This diff adds a couple of tour files which are loadable by anyone who has the extension and loads this folder.

Reviewed By: zzl0

Differential Revision: D43016241

fbshipit-source-id: a484a69cad9e9d04646df29295fda25ab4393deb

addons/.tours/server--client-communication.tour

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "Server & Client communication",
+  "steps": [
+    {
+      "file": "isl-server/src/index.ts",
+      "description": "Once the server has been spawned, the ISL server code starts here. At this point, we have a websocket connection to a client that we've validated as trustworthy.",
+      "line": 50
+    },
+    {
+      "file": "isl-server/src/index.ts",
+      "description": "Now we set up `ServerToClientAPI`, which is the main server-side API which handles messages from the client, and sends new messages back.",
+      "line": 64
+    },
+    {
+      "file": "isl-server/src/ServerToClientAPI.ts",
+      "description": "ServerToClientAPI knows how to handle messages from the client, and then interact with the Repository and send messages back to the client (`postMessage`)",
+      "line": 302
+    },
+    {
+      "file": "isl-server/src/index.ts",
+      "description": "We allow sharing/re-using repositories across clients, but each client connection has at most one repository it references at a time. Two clients could share the same Repository with different cwds.",
+      "line": 66
+    },
+    {
+      "file": "isl/src/MessageBus.ts",
+      "description": "On the client, we create a MessageBus abstraciton to setup the websocket and send messages back and forth with the server. It also has `postMessage` / `onMessage`",
+      "line": 193
+    },
+    {
+      "file": "isl/src/serverAPIState.ts",
+      "description": "Typical usage of messages from the client is to send request messages via postMessage when a user action occurs (or when the client connects for the first time). Then, whenever we get messages back of the right type, we save that data into our Recoil atom state, which then triggers the client to re-render any component using that data.",
+      "line": 21
+    },
+    {
+      "file": "isl/src/types.ts",
+      "description": "This types.ts file defines all the messages that are sent between the client & server. Since messages are typed, you know all possible messages in the type system and can exhasutively `switch` and get payload type information. Client -> Server and Server -> Client have completely different message types.",
+      "line": 308
+    },
+    {
+      "file": "isl/src/serialize.ts",
+      "description": "When sending data across the websocket, we must serialize it to a string and deserialize it on the other end. Thus, message payloads must be JSON-like objects so we can serialize them. Our serialization is slightly fancy and allows you to serialize Map, Set, Date, undefined, in addition to normal JSON. ",
+      "line": 48
+    }
+  ]
+}

addons/.tours/spawning-isl.tour

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "Spawning ISL",
+  "steps": [
+    {
+      "title": "Introduction",
+      "description": "This tour is about how the ISL server is spawned and how the client connects to it. This is mainly for the `sl web` embedding. VS Code behaves slightly differently."
+    },
+    {
+      "file": "isl-server/proxy/startServer.ts",
+      "description": "sl web / hg isl CLI starts here, where the python wrapper spawns this node process",
+      "line": 297
+    },
+    {
+      "file": "isl-server/proxy/startServer.ts",
+      "description": "We try to spawn a server, and if we fail due to `addressInUse`, we might be able to re-use this server. We can only re-use it if it's a real ISL server.",
+      "line": 409
+    },
+    {
+      "file": "isl-server/proxy/startServer.ts",
+      "description": "\"re-using\" a server just means printing the URL for the existing running one",
+      "line": 484
+    },
+    {
+      "file": "isl-server/proxy/startServer.ts",
+      "description": "If we spawned a new server, we need to remember its information for future re-use.",
+      "line": 508
+    },
+    {
+      "file": "isl-server/proxy/startServer.ts",
+      "description": "Either directly import the server code to run in the foreground, or spawn a detached subprocess with the server code. Either way, the server is loaded dynamically.",
+      "line": 254
+    },
+    {
+      "file": "isl-server/proxy/server.ts",
+      "description": "Once we've spawned the server process, it spins up an HTTP server and waits for someone to use the ISL url we printed in runProxy.",
+      "line": 103
+    },
+    {
+      "file": "isl-server/proxy/server.ts",
+      "description": "Set up a websocket conneciton listener. The HTTP server serves the HTML and JS files to the client. Once those are rendered by the browser, it immediately starts a websocket connection which comes back here.",
+      "line": 153
+    },
+    {
+      "file": "isl-server/proxy/server.ts",
+      "description": "It's important for security that we only allow websocket connections from authentic URLs that know the generated token, otherwise a malicious page could access localhost and access the repository! So this token is part of the websocket connection process.",
+      "line": 173
+    },
+    {
+      "file": "isl-server/proxy/server.ts",
+      "description": "Finally, in the websocket connection, we invoke the API exposed by isl-server: `onClientConnection`, which describes basic info and how to send/receive messages with the now validated client.",
+      "line": 190
+    }
+  ]
+}

addons/.tours/vs-code.tour

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "VS Code",
+  "steps": [
+    {
+      "title": "Introduction",
+      "description": "This tour is about how the Sapling VS Code extension works.\nUnlike `sl web` / run-proxy, the vscode extension is spawned by VS Code, so we don't have to manage our own server process.\nThe \"ISL Server\" runs in the VS Code extension host (which has nodeJS-like access to the filesystem and spawning processes),\nand the \"ISL Client\" runs in a vscode webview context (which is browser-like and can only send messages but not access FS / processes directly.)"
+    },
+    {
+      "file": "vscode/extension/extension.ts",
+      "description": "The extension activation function is the entry point for the extension. This is where we register various handlers for the VS Code API",
+      "line": 18
+    },
+    {
+      "file": "vscode/extension/extension.ts",
+      "description": "you can access all vscode APIs via the `vscode` import. This is only available in the extension host but not the webview.",
+      "line": 16
+    },
+    {
+      "file": "vscode/extension/islWebviewPanel.ts",
+      "description": "We register a VS Code Command to open the ISL webview. This command may be triggered in different ways.",
+      "line": 59
+    },
+    {
+      "file": "vscode/extension/islWebviewPanel.ts",
+      "description": "After we create a webview, we fill in its HTML, roughly analagous to the `sl web` client making an HTTP request to get HTML.",
+      "line": 89
+    },
+    {
+      "file": "vscode/extension/islWebviewPanel.ts",
+      "description": "Now the extension host can set up a client connection. In `sl web`, this happens in the websocket connection. But here, we have no websocket, and instead communicate over vscode's message passing API. This is very similar to a websocket, though not technically a websocket.\nWe set up onClientConnection in the same way, which defines how to use this `panel.webview.postMessage` API.",
+      "line": 97
+    },
+    {
+      "file": "vscode/extension/VSCodeRepo.ts",
+      "description": "We wrap around the Repository class that ISL uses, so that we can add on extra VS Code functionality. This is part of the reason that Repositories are re-usable. The VS Code API part has a ref count, and the ISL webview handler has a ref count.",
+      "line": 26
+    },
+    {
+      "file": "vscode/extension/VSCodeRepo.ts",
+      "description": "We auto-create/delete repositories as you update your open folders in your editor",
+      "line": 67
+    },
+    {
+      "file": "vscode/extension/VSCodeRepo.ts",
+      "description": "Each `VSCodeRepository` references a `Repository`, then also uses the VS Code source control API. This lets it show uncommitted changes in the SCM sidebar.",
+      "line": 90
+    },
+    {
+      "file": "vscode/extension/VSCodeRepo.ts",
+      "description": "We also use the quickDiffProvider API to show changed line gutters in files. See `DiffContentProvider`.",
+      "line": 95
+    },
+    {
+      "file": "vscode/extension/vscodePlatform.ts",
+      "description": "Different platforms like VS Code or Android Studio can define a platform, both server-side and client side that describes an API of platform-specific actions, such as opening files. VS Code wants to open all files in VS Code, but Android Studio wants to use Android Studio, etc.\nThe \"ServerPlatform\" is usually responding to messages from the client so it can interact with various platform APIs.",
+      "line": 20
+    },
+    {
+      "file": "vscode/webview/vscodeWebviewPlatform.ts",
+      "description": "The Client Platform is often the more-used API, including things like copying to the clipboard and opening files. These don't necessarily need to send messages to the server, sometimes they can be handled directly (like clipboardCopy for VS Code)",
+      "line": 11
+    }
+  ]
+}