From ba3f0bb5127fe369c1edc90854d80fe694ef2eef Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 7 Dec 2020 06:38:17 -0800 Subject: [PATCH 1/9] add initial codetour --- .tours/contributing.tour | 42 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 .tours/contributing.tour diff --git a/.tours/contributing.tour b/.tours/contributing.tour new file mode 100644 index 000000000..48b40bcff --- /dev/null +++ b/.tours/contributing.tour @@ -0,0 +1,42 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Contributing", + "steps": [ + { + "file": "src/node/app.ts", + "line": 11, + "description": "code-server's HTTP server is managed here." + }, + { + "file": "src/node/routes/apps.ts", + "line": 8, + "description": "Apps can be created to extend code-server. Here is the Express route that handles that.", + "selection": { + "start": { + "line": 4, + "character": 1 + }, + "end": { + "line": 8, + "character": 4 + } + } + }, + { + "file": "src/node/routes/vscode.ts", + "line": 21, + "description": "This is the Express route for VS Code." + }, + { + "file": "src/node/cli.ts", + "line": 28, + "description": "The `$ code-server` CLI is defined here. " + }, + { + "file": "ci/dev/vscode.patch", + "line": 1, + "description": "In v1 of code-server, we had a patch of VS Code that split the codebase into a front-end and a server. The front-end consisted of all UI code, while the server ran the extensions and exposed an API to the front-end for file access and all UI needs.\n\nOver time, Microsoft added support to VS Code to run it on the web. They have made the front-end open source, but not the server. As such, code-server v2 (and later) uses the VS Code front-end and implements the server. You can find this here." + } + ], + "ref": "master" +} \ No newline at end of file From c0c39af50959807841cd6b73f093d4ee5dd150e0 Mon Sep 17 00:00:00 2001 From: Asher Date: Tue, 8 Dec 2020 16:57:48 -0600 Subject: [PATCH 2/9] Add tour points --- .tours/contributing.tour | 158 +++++++++++++++++++++++++++++++++------ 1 file changed, 134 insertions(+), 24 deletions(-) diff --git a/.tours/contributing.tour b/.tours/contributing.tour index 48b40bcff..25ca6ad1e 100644 --- a/.tours/contributing.tour +++ b/.tours/contributing.tour @@ -3,40 +3,150 @@ "title": "Contributing", "steps": [ { - "file": "src/node/app.ts", - "line": 11, - "description": "code-server's HTTP server is managed here." + "file": "src", + "line": 1, + "description": "Hello world! code-server's source code lives here. It's broadly arranged into browser code, Node code, and code shared between both." }, { - "file": "src/node/routes/apps.ts", - "line": 8, - "description": "Apps can be created to extend code-server. Here is the Express route that handles that.", - "selection": { - "start": { - "line": 4, - "character": 1 - }, - "end": { - "line": 8, - "character": 4 - } - } - }, - { - "file": "src/node/routes/vscode.ts", - "line": 21, - "description": "This is the Express route for VS Code." + "file": "src/node/entry.ts", + "line": 157, + "description": "code-server begins execution here. CLI arguments are parsed, special flags like --help are handled, then the HTTP server is started." }, { "file": "src/node/cli.ts", "line": 28, - "description": "The `$ code-server` CLI is defined here. " + "description": "This describes all of the code-server CLI options and how they will be parsed." + }, + { + "file": "src/node/cli.ts", + "line": 233, + "description": "Here's the actual CLI parser." + }, + { + "file": "src/node/settings.ts", + "line": 1, + "description": "code-server maintains a settings file that is read and written here." + }, + { + "file": "src/node/app.ts", + "line": 11, + "description": "The core of code-server are HTTP and web socket servers which are created here. They provide authentication, file access, an API, and serve web-based applications like VS Code." + }, + { + "file": "src/node/wsRouter.ts", + "line": 38, + "description": "This is an analog to Express's Router that handles web socket routes." + }, + { + "file": "src/node/http.ts", + "line": 1, + "description": "This file provides various HTTP utility functions." + }, + { + "file": "src/node/coder_cloud.ts", + "line": 9, + "description": "The cloud agent spawned here provides the --link functionality." + }, + { + "file": "src/node/heart.ts", + "line": 7, + "description": "code-server's heart beats to indicate recent activity." + }, + { + "file": "src/node/socket.ts", + "line": 13, + "description": "We pass sockets to child processes, however we can't pass TLS sockets so when code-server is handling TLS (via --cert) we use this to create a proxy that can be passed to the child." + }, + { + "file": "src/node/routes", + "line": 1, + "description": "code-server's routes live here." + }, + { + "file": "src/node/routes/index.ts", + "line": 123, + "description": "The architecture of code-server allows it to be extended with applications via plugins. Each application is registered at its own route and handles requests at and below that route. Currently we have only VS Code (although it is not yet actually split out into a plugin)." + }, + { + "file": "src/node/plugin.ts", + "line": 103, + "description": "The previously mentioned plugins are loaded here." + }, + { + "file": "src/node/routes/apps.ts", + "line": 12, + "description": "This provides a list of the applications registered with code-server." + }, + { + "file": "src/node/routes/domainProxy.ts", + "line": 18, + "description": "code-server provides a built-in proxy to help in developing web-based applications. This is the code for the domain-based proxy." + }, + { + "file": "src/node/routes/pathProxy.ts", + "line": 19, + "description": "Here is the path-based version of the proxy." + }, + { + "file": "src/node/proxy.ts", + "line": 4, + "description": "Both the domain and path proxy use the single proxy instance created here." + }, + { + "file": "src/node/routes/health.ts", + "line": 5, + "description": "A simple endpoint that lets you see if code-server is up." + }, + { + "file": "src/node/routes/login.ts", + "line": 46, + "description": "code-server supports a password-based login here." + }, + { + "file": "src/node/routes/static.ts", + "line": 16, + "description": "This serves static assets. Anything under the code-server directory can be fetched. Anything outside requires authentication." + }, + { + "file": "src/node/routes/update.ts", + "line": 10, + "description": "This endpoint lets you query for the latest code-server version. It's used to power the update popup you see in VS Code." + }, + { + "file": "src/node/routes/vscode.ts", + "line": 15, + "description": "This is the endpoint that serves VS Code's HTML, handles VS Code's websockets, and handles a few VS Code-specific endpoints for fetching static files." + }, + { + "file": "src/node/vscode.ts", + "line": 13, + "description": "The actual VS Code spawn and initialization is handled here. VS Code runs in a separate child process. We communicate via IPC and by passing it web sockets." + }, + { + "file": "src/browser/serviceWorker.ts", + "line": 1, + "description": "The service worker only exists to provide PWA functionality." + }, + { + "file": "src/browser/pages", + "line": 1, + "description": "HTML, CSS, and JavaScript for each page lives here. Currently our HTML uses a simple search and replace template system with variables that {{LOOK_LIKE_THIS}}." + }, + { + "file": "src/browser/pages/vscode.html", + "line": 1, + "description": "The VS Code HTML is based off VS Code's own `workbench.html`." + }, + { + "file": "src/browser/media", + "line": 1, + "description": "Static images and the manifest live here." }, { "file": "ci/dev/vscode.patch", "line": 1, - "description": "In v1 of code-server, we had a patch of VS Code that split the codebase into a front-end and a server. The front-end consisted of all UI code, while the server ran the extensions and exposed an API to the front-end for file access and all UI needs.\n\nOver time, Microsoft added support to VS Code to run it on the web. They have made the front-end open source, but not the server. As such, code-server v2 (and later) uses the VS Code front-end and implements the server. You can find this here." + "description": "code-server makes use of VS Code's frontend web/remote support. Most of the patch implements the remote server since that portion of the code is closed source and not released with VS Code.\n\nWe also have a few bug fixes and have added some features (like client-side extensions). See CONTRIBUTING.md for a list.\n\nWe make an effort to keep the patch as small as possible." } ], "ref": "master" -} \ No newline at end of file +} From 5610431310a0947c3cb3de9bbc7da02329fe294e Mon Sep 17 00:00:00 2001 From: Ben Date: Wed, 9 Dec 2020 09:20:34 -0800 Subject: [PATCH 3/9] add link to docs --- .tours/contributing.tour | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.tours/contributing.tour b/.tours/contributing.tour index 25ca6ad1e..5a3f393e1 100644 --- a/.tours/contributing.tour +++ b/.tours/contributing.tour @@ -50,7 +50,7 @@ { "file": "src/node/heart.ts", "line": 7, - "description": "code-server's heart beats to indicate recent activity." + "description": "code-server's heart beats to indicate recent activity.\n\nAlso documented here: [https://github.com/cdr/code-server/blob/master/doc/FAQ.md#heartbeat-file](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#heartbeat-file)" }, { "file": "src/node/socket.ts", @@ -80,12 +80,12 @@ { "file": "src/node/routes/domainProxy.ts", "line": 18, - "description": "code-server provides a built-in proxy to help in developing web-based applications. This is the code for the domain-based proxy." + "description": "code-server provides a built-in proxy to help in developing web-based applications. This is the code for the domain-based proxy.\n\nAlso documented here: [https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services)" }, { "file": "src/node/routes/pathProxy.ts", "line": 19, - "description": "Here is the path-based version of the proxy." + "description": "Here is the path-based version of the proxy.\n\nAlso documented here: [https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#how-do-i-securely-access-web-services)" }, { "file": "src/node/proxy.ts", @@ -95,7 +95,7 @@ { "file": "src/node/routes/health.ts", "line": 5, - "description": "A simple endpoint that lets you see if code-server is up." + "description": "A simple endpoint that lets you see if code-server is up.\n\nAlso documented here: [https://github.com/cdr/code-server/blob/master/doc/FAQ.md#healthz-endpoint](https://github.com/cdr/code-server/blob/master/doc/FAQ.md#healthz-endpoint)" }, { "file": "src/node/routes/login.ts", From db8b41b058b87d1911671b63073df1cef331887b Mon Sep 17 00:00:00 2001 From: Ben Date: Wed, 9 Dec 2020 09:22:19 -0800 Subject: [PATCH 4/9] make tour work on all branches --- .tours/contributing.tour | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.tours/contributing.tour b/.tours/contributing.tour index 5a3f393e1..1c5368eae 100644 --- a/.tours/contributing.tour +++ b/.tours/contributing.tour @@ -147,6 +147,5 @@ "line": 1, "description": "code-server makes use of VS Code's frontend web/remote support. Most of the patch implements the remote server since that portion of the code is closed source and not released with VS Code.\n\nWe also have a few bug fixes and have added some features (like client-side extensions). See CONTRIBUTING.md for a list.\n\nWe make an effort to keep the patch as small as possible." } - ], - "ref": "master" + ] } From 63029bec913f0c00f6df3e4c9377ff1db26a8976 Mon Sep 17 00:00:00 2001 From: Ben Date: Wed, 9 Dec 2020 13:16:27 -0800 Subject: [PATCH 5/9] add development tour with commands --- .tours/start-development.tour | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 .tours/start-development.tour diff --git a/.tours/start-development.tour b/.tours/start-development.tour new file mode 100644 index 000000000..b72811dd4 --- /dev/null +++ b/.tours/start-development.tour @@ -0,0 +1,26 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Start Development", + "steps": [ + { + "file": "package.json", + "line": 31, + "description": "## Commands\n\nTo start developing, make sure you have Node 12+ installed. Then, run the following commands:\n\n1. Install dependencies:\n>> yarn\n\n2. Clone, patch, and install VS Code:\n>> yarn vscode\n\n3. Start development mode (and watch for changes):\n>> yarn watch" + }, + { + "file": "src/node/app.ts", + "line": 68, + "description": "## Visit the web server\n\nIf all goes well, you should see something like this in your terminal. code-server should be live in development mode.\n\n---\n```bash\n[2020-12-09T21:03:37.156Z] info code-server 3.7.4 development\n[2020-12-09T21:03:37.157Z] info Using user-data-dir ~/.local/share/code-server\n[2020-12-09T21:03:37.165Z] info Using config file ~/.config/code-server/config.yaml\n[2020-12-09T21:03:37.165Z] info HTTP server listening on http://127.0.0.1:8080 \n[2020-12-09T21:03:37.165Z] info - Authentication is enabled\n[2020-12-09T21:03:37.165Z] info - Using password from ~/.config/code-server/config.yaml\n[2020-12-09T21:03:37.165Z] info - Not serving HTTPS\n```\n\n---\n\nIf you have the default configuration, you can access it at [http://localhost:8080](http://localhost:8080)." + }, + { + "file": "src/browser/pages/login.html", + "line": 26, + "description": "## Make a change\n\nThis is the login page, let's make a change and see it update on our web server! Perhaps change the text :)\n\n```html\n
Modifying the login page 👨🏼‍💻
\n```\n\nReminder, you can likely preview at [http://localhost:8080](http://localhost:8080)" + }, + { + "file": "src/node/app.ts", + "line": 62, + "description": "## That's it!\n\n\nThat's all there is to it! When this tour ends, your terminal session may stop, but just use `yarn watch` to start developing from here on out!\n\n\nIf you haven't already, be sure to check out these resources:\n- [Tour: Contributing](command:codetour.startTourByTitle?[\"Contributing\")\n- [Docs: FAQ.md](https://github.com/cdr/code-server/blob/master/doc/FAQ.md)\n- [Docs: CONTRIBUTING.md](https://github.com/cdr/code-server/blob/master/doc/CONTRIBUTING.md)\n- [Community: GitHub Discussions](https://github.com/cdr/code-server/discussions)\n- [Community: Slack](https://community.coder.com)" + } + ] +} \ No newline at end of file From 8d1c8041e92e32ae8e6c679753adf716b7a5fc0c Mon Sep 17 00:00:00 2001 From: Ben Date: Wed, 9 Dec 2020 22:02:07 -0800 Subject: [PATCH 6/9] change to directory --- .tours/contributing.tour | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.tours/contributing.tour b/.tours/contributing.tour index 1c5368eae..736fe7a39 100644 --- a/.tours/contributing.tour +++ b/.tours/contributing.tour @@ -3,7 +3,7 @@ "title": "Contributing", "steps": [ { - "file": "src", + "directory": "src", "line": 1, "description": "Hello world! code-server's source code lives here. It's broadly arranged into browser code, Node code, and code shared between both." }, From fa7d3fd4c23dcd927895cae22fe89c190cf13cde Mon Sep 17 00:00:00 2001 From: Asher Date: Thu, 10 Dec 2020 10:45:31 -0600 Subject: [PATCH 7/9] Change tour directories from `file` to `directory` `file` doesn't seem to work without a specific git reference, but adding a reference makes the explorer not follow the tour. Unfortunately `directory` doesn't show the directory contents so I added the directory name and "see the explorer" to the comment. --- .tours/contributing.tour | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.tours/contributing.tour b/.tours/contributing.tour index 736fe7a39..9353ded5e 100644 --- a/.tours/contributing.tour +++ b/.tours/contributing.tour @@ -5,7 +5,7 @@ { "directory": "src", "line": 1, - "description": "Hello world! code-server's source code lives here. It's broadly arranged into browser code, Node code, and code shared between both." + "description": "Hello world! code-server's source code lives here in `src` (see the explorer). It's broadly arranged into browser code, Node code, and code shared between both." }, { "file": "src/node/entry.ts", @@ -58,9 +58,9 @@ "description": "We pass sockets to child processes, however we can't pass TLS sockets so when code-server is handling TLS (via --cert) we use this to create a proxy that can be passed to the child." }, { - "file": "src/node/routes", + "directory": "src/node/routes", "line": 1, - "description": "code-server's routes live here." + "description": "code-server's routes live here in `src/node/routes` (see the explorer)." }, { "file": "src/node/routes/index.ts", @@ -128,9 +128,9 @@ "description": "The service worker only exists to provide PWA functionality." }, { - "file": "src/browser/pages", + "directory": "src/browser/pages", "line": 1, - "description": "HTML, CSS, and JavaScript for each page lives here. Currently our HTML uses a simple search and replace template system with variables that {{LOOK_LIKE_THIS}}." + "description": "HTML, CSS, and JavaScript for each page lives in here `src/browser/pages` (see the explorer). Currently our HTML uses a simple search and replace template system with variables that {{LOOK_LIKE_THIS}}." }, { "file": "src/browser/pages/vscode.html", @@ -138,9 +138,9 @@ "description": "The VS Code HTML is based off VS Code's own `workbench.html`." }, { - "file": "src/browser/media", + "directory": "src/browser/media", "line": 1, - "description": "Static images and the manifest live here." + "description": "Static images and the manifest live here in `src/browser/media` (see the explorer)." }, { "file": "ci/dev/vscode.patch", From bc1fe207d19174ebc1db8ea13f87ae2eb17a23fe Mon Sep 17 00:00:00 2001 From: Asher Date: Thu, 10 Dec 2020 10:50:32 -0600 Subject: [PATCH 8/9] Link CONTRIBUTING.md from the tour For now it has to be a full link but in the future it would be nice to open it relatively in the editor. --- .tours/contributing.tour | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.tours/contributing.tour b/.tours/contributing.tour index 9353ded5e..7a92c71bb 100644 --- a/.tours/contributing.tour +++ b/.tours/contributing.tour @@ -145,7 +145,7 @@ { "file": "ci/dev/vscode.patch", "line": 1, - "description": "code-server makes use of VS Code's frontend web/remote support. Most of the patch implements the remote server since that portion of the code is closed source and not released with VS Code.\n\nWe also have a few bug fixes and have added some features (like client-side extensions). See CONTRIBUTING.md for a list.\n\nWe make an effort to keep the patch as small as possible." + "description": "code-server makes use of VS Code's frontend web/remote support. Most of the patch implements the remote server since that portion of the code is closed source and not released with VS Code.\n\nWe also have a few bug fixes and have added some features (like client-side extensions). See [https://github.com/cdr/code-server/blob/master/doc/CONTRIBUTING.md#vs-code-patch](https://github.com/cdr/code-server/blob/master/doc/CONTRIBUTING.md#vs-code-patch) for a list.\n\nWe make an effort to keep the patch as small as possible." } ] } From 704f34ed5fdcd9df7ed020d9f9bc319f174c7e5b Mon Sep 17 00:00:00 2001 From: Asher Date: Thu, 10 Dec 2020 10:53:47 -0600 Subject: [PATCH 9/9] Add VS Code reqs link to development tour --- .tours/start-development.tour | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.tours/start-development.tour b/.tours/start-development.tour index b72811dd4..8f79ea40a 100644 --- a/.tours/start-development.tour +++ b/.tours/start-development.tour @@ -5,7 +5,7 @@ { "file": "package.json", "line": 31, - "description": "## Commands\n\nTo start developing, make sure you have Node 12+ installed. Then, run the following commands:\n\n1. Install dependencies:\n>> yarn\n\n2. Clone, patch, and install VS Code:\n>> yarn vscode\n\n3. Start development mode (and watch for changes):\n>> yarn watch" + "description": "## Commands\n\nTo start developing, make sure you have Node 12+ and the [required dependencies](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites) installed. Then, run the following commands:\n\n1. Install dependencies:\n>> yarn\n\n2. Clone and patch VS Code and install its dependencies:\n>> yarn vscode\n\n3. Start development mode (and watch for changes):\n>> yarn watch" }, { "file": "src/node/app.ts", @@ -23,4 +23,4 @@ "description": "## That's it!\n\n\nThat's all there is to it! When this tour ends, your terminal session may stop, but just use `yarn watch` to start developing from here on out!\n\n\nIf you haven't already, be sure to check out these resources:\n- [Tour: Contributing](command:codetour.startTourByTitle?[\"Contributing\")\n- [Docs: FAQ.md](https://github.com/cdr/code-server/blob/master/doc/FAQ.md)\n- [Docs: CONTRIBUTING.md](https://github.com/cdr/code-server/blob/master/doc/CONTRIBUTING.md)\n- [Community: GitHub Discussions](https://github.com/cdr/code-server/discussions)\n- [Community: Slack](https://community.coder.com)" } ] -} \ No newline at end of file +}