From 056e6694a3bedeb29b73d66f84cccb60cbc0a710 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 27 Oct 2020 11:34:32 -0500 Subject: [PATCH 1/5] Edit README --- README.md | 46 ++++++++++++++++------------------------------ 1 file changed, 16 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 8e68c3e1682a..966bbb9bd990 100644 --- a/README.md +++ b/README.md @@ -6,72 +6,58 @@ Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and a ## Highlights -- **Code everywhere** - - Code on your Chromebook, tablet, and laptop with a consistent development environment. - - Develop on a Linux machine and pick up from any device with a web browser. -- **Server-powered** - - Take advantage of large cloud servers to speed up tests, compilations, downloads, and more. - - Preserve battery life when you're on the go as all intensive tasks run on your server. - - Make use of a spare computer you have lying around and turn it into a full development environment. +- Code on any device with a consistent development environment +- Use cloud servers to speed up tests, compilations, downloads, and more +- Preserve battery life when you're on the go; all intensive tasks run on your server ## Getting Started -For a full setup and walkthrough, please see [./doc/guide.md](./doc/guide.md). +There are two ways to get started: -### Quick Install +1. Using the [install script](./install.sh), which automates most of the process. The script uses the system package manager (if possible) +2. Manually installing code-server; see [Installation](./doc/install.md#quick-install) for instructions applicable to most use cases -We have a [script](./install.sh) to install code-server for Linux, macOS and FreeBSD. - -It tries to use the system package manager if possible. - -First run to print out the install process: +If you choose to use the install script, you can preview what occurs during the install process: ```bash curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run ``` -Now to actually install: +To install, run: ```bash curl -fsSL https://code-server.dev/install.sh | sh ``` -The install script will print out how to run and start using code-server. - -### Manual Install +When done, the install script prints out instructions for running and starting code-server. -Docs on the install script, manual installation and docker image are at [./doc/install.md](./doc/install.md). +We also have an in-depth [setup and configuration](./doc/guide.md) guide. ### Alpha Program 🐣 -We're working on a cloud platform to make deploying and managing code-server easier. If you don't want to worry about +We're working on a cloud platform that makes deploying and managing code-server easier. Consider [joining our alpha program](https://codercom.typeform.com/to/U4IKyv0W) if you don't want to worry about - TLS - Authentication - Port Forwarding -consider [joining our alpha program](https://codercom.typeform.com/to/U4IKyv0W). - ## FAQ See [./doc/FAQ.md](./doc/FAQ.md). -## Contributing +## Want to help? -See [./doc/CONTRIBUTING.md](./doc/CONTRIBUTING.md). +See [CONTRIBUTING](./doc/CONTRIBUTING.md) for additional details. ## Hiring -We ([@cdr](https://github.com/cdr)) are looking for engineers to help maintain -code-server, innovate on open source and streamline dev workflows. +We ([@cdr](https://github.com/cdr)) are looking for engineers to help [maintain +code-server](https://jobs.lever.co/coder/e40becde-2cbd-4885-9029-e5c7b0a734b8), innovate on open source, and streamline dev workflows. Our main office is in Austin, Texas. Remote is ok as long as you're in North America or Europe. -Please get in [touch](mailto:jobs@coder.com) with your resume/github if interested. - -We're also hiring someone specifically to help maintain code-server. -See the listing [here](https://jobs.lever.co/coder/e40becde-2cbd-4885-9029-e5c7b0a734b8). +Please get in [touch](mailto:jobs@coder.com) with your resume/GitHub if interested. ## For Organizations From ce363da4adcd92186e7f90d6709e41706d9db16c Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 27 Oct 2020 12:06:02 -0500 Subject: [PATCH 2/5] Edit CONTRIBUTING --- doc/CONTRIBUTING.md | 130 ++++++++++++++++++++++---------------------- 1 file changed, 64 insertions(+), 66 deletions(-) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 62c20f915639..4f2a57251f1b 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -2,12 +2,14 @@ # Contributing -- [Pull Requests](#pull-requests) -- [Requirements](#requirements) -- [Development Workflow](#development-workflow) -- [Build](#build) -- [Structure](#structure) - - [VS Code Patch](#vs-code-patch) +- [Contributing](#contributing) + - [Pull Requests](#pull-requests) + - [Requirements](#requirements) + - [Development Workflow](#development-workflow) + - [Build](#build) + - [Structure](#structure) + - [VS Code Patch](#vs-code-patch) + - [Currently Known Issues](#currently-known-issues) @@ -15,24 +17,26 @@ ## Pull Requests -Please link to the issue each PR solves. -If there is no existing issue, please first create one unless the fix is minor. +Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) for each issue +you'd like to address unless the proposed fix is minor. -Please make sure the base of your PR is the master branch. We keep the GitHub -default branch the latest release branch to avoid confusion as the -documentation is on GitHub and we don't want users to see docs on unreleased -features. +In your Pull Requests (PR), link to the issue that the PR solves. + +Please ensure that the base of your PR is the **master** branch. (Note: The default +GitHub branch is the latest release branch, though you should point all of your changes to be merged into +master). ## Requirements -Please refer to [VS Code's prerequisites](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites). +The prerequisites for contributing to code-server are almost the same as those for +[VS Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites). +There are several differences, however. You must: -Differences: +- Use Node.js version 12.x (or greater) +- Have [nfpm](https://github.com/goreleaser/nfpm) (which is used to build `.deb` and `.rpm` packages and [jq](https://stedolan.github.io/jq/) (used to build code-server releases) installed -- We require a minimum of node v12 but later versions should work. -- We use [nfpm](https://github.com/goreleaser/nfpm) to build `.deb` and `.rpm` packages. -- We use [jq](https://stedolan.github.io/jq/) to build code-server releases. -- The [CI container](../ci/images/debian10/Dockerfile) is a useful reference for all our dependencies. +The [CI container](../ci/images/debian8/Dockerfile) is a useful reference for all +of the dependencies code-server uses. ## Development Workflow @@ -40,10 +44,10 @@ Differences: yarn yarn vscode yarn watch -# Visit http://localhost:8080 once the build completed. +# Visit http://localhost:8080 once the build is completed. ``` -To develop inside of an isolated docker container: +To develop inside an isolated Docker container: ```shell ./ci/dev/image/run.sh yarn @@ -53,12 +57,12 @@ To develop inside of an isolated docker container: `yarn watch` will live reload changes to the source. -If changes are made to the patch and you've built previously you must manually -reset VS Code then run `yarn vscode:patch`. +If you introduce changes to the patch and you've previously built, you +must (1) manually reset VS Code and (2) run `yarn vscode:patch`. ## Build -You can build with: +You can build using: ```shell ./ci/dev/image/run.sh ./ci/steps/release.sh @@ -66,22 +70,22 @@ You can build with: Run your build with: -``` +```shell cd release yarn --production # Runs the built JavaScript with Node. node . ``` -Build release packages (make sure you run `./ci/steps/release.sh` first): +Build the release packages (make sure that you run `./ci/steps/release.sh` first): -``` +```shell IMAGE=centos7 ./ci/dev/image/run.sh ./ci/steps/release-packages.sh # The standalone release is in ./release-standalone # .deb, .rpm and the standalone archive are in ./release-packages ``` -The `release.sh` script is the equivalent of: +The `release.sh` script is equal to running: ```shell yarn @@ -91,73 +95,67 @@ yarn build:vscode yarn release ``` -And `release-packages.sh` is: +And `release-packages.sh` is equal to: -``` +```shell yarn release:standalone yarn test:standalone-release yarn package ``` -For a faster release build you can also run: +For a faster release build, you can run instead: -``` +```shell KEEP_MODULES=1 ./ci/steps/release.sh node ./release ``` ## Structure -The `code-server` script serves an HTTP API to login and start a remote VS Code process. +The `code-server` script serves an HTTP API for login and starting a remote VS Code process. The CLI code is in [./src/node](./src/node) and the HTTP routes are implemented in [./src/node/app](./src/node/app). -Most of the meaty parts are in our VS Code patch which is described next. +Most of the meaty parts are in the VS Code patch, which we described next. ### VS Code Patch -Back in v1 of code-server, we had an extensive patch of VS Code that split the codebase -into a frontend and server. The frontend consisted of all UI code and the server ran -the extensions and exposed an API to the frontend for file access and everything else -that the UI needed. +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. -This worked but eventually Microsoft added support to VS Code to run it in the web. -They have open sourced the frontend but have kept the server closed source. - -So in interest of piggy backing off their work, v2 and beyond use the VS Code -web frontend and fill in the server. This is contained in our +Over 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 fills in with the server. You can find this in [./ci/dev/vscode.patch](../ci/dev/vscode.patch) under the path `src/vs/server`. Other notable changes in our patch include: -- Add our own build file which includes our code and VS Code's web code. -- Allow multiple extension directories (both user and built-in). -- Modify the loader, websocket, webview, service worker, and asset requests to - use the URL of the page as a base (and TLS if necessary for the websocket). -- Send client-side telemetry through the server. -- Allow modification of the display language. -- Make it possible for us to load code on the client. -- Make extensions work in the browser. -- Make it possible to install extensions of any kind. -- Fix getting permanently disconnected when you sleep or hibernate for a while. -- Add connection type to web socket query parameters. - -Some known issues presently: +- Adding our build file, which includes our code and VS Code's web code +- Allowing multiple extension directories (both user and built-in) +- Modifying the loader, websocket, webview, service worker, and asset requests to + use the URL of the page as a base (and TLS, if necessary for the websocket) +- Sending client-side telemetry through the server +- Allowing modification of the display language +- Making it possible for us to load code on the client +- Making extensions work in the browser +- Making it possible to install extensions of any kind +- Fixing issue with getting disconnected when your machine sleeps or hibernates +- Adding connection type to web socket query parameters -- Creating custom VS Code extensions and debugging them doesn't work. -- Extension profiling and tips are currently disabled. +As the web portion of VS Code matures, we'll be able to shrink and possibly +eliminate our patch. In the meantime, upgrading the VS Code version requires us to ensure that the patch is applied and works as intended. In the future, we'd like to run VS +Code unit tests against our builds to ensure that features work as expected. -As the web portion of VS Code matures, we'll be able to shrink and maybe even entirely -eliminate our patch. In the meantime, however, upgrading the VS Code version requires -ensuring that the patch still applies and has the intended effects. +To generate a new patch, run `yarn vscode:diff` -To generate a new patch run `yarn vscode:diff`. +**Note**: We have [extension docs](../ci/README.md) on the CI and build system. -**note**: We have extension docs on the CI and build system at [./ci/README.md](../ci/README.md) +If the functionality you're working on does NOT depend on code from VS Code, please +move it out and into code-server. -If functionality doesn't depend on code from VS Code then it should be moved -into code-server otherwise it should be in the patch. +### Currently Known Issues -In the future we'd like to run VS Code unit tests against our builds to ensure features -work as expected. +- Creating custom VS Code extensions and debugging them doesn't work +- Extension profiling and tips are currently disabled \ No newline at end of file From ce93e21fb56535c2209713b2a2dd4ae3568c189c Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 28 Oct 2020 10:18:39 -0500 Subject: [PATCH 3/5] Format CONTRIBUTING.MD --- doc/CONTRIBUTING.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 4f2a57251f1b..e1e418829558 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -2,14 +2,13 @@ # Contributing -- [Contributing](#contributing) - - [Pull Requests](#pull-requests) - - [Requirements](#requirements) - - [Development Workflow](#development-workflow) - - [Build](#build) - - [Structure](#structure) - - [VS Code Patch](#vs-code-patch) - - [Currently Known Issues](#currently-known-issues) +- [Pull Requests](#pull-requests) +- [Requirements](#requirements) +- [Development Workflow](#development-workflow) +- [Build](#build) +- [Structure](#structure) + - [VS Code Patch](#vs-code-patch) + - [Currently Known Issues](#currently-known-issues) @@ -158,4 +157,4 @@ move it out and into code-server. ### Currently Known Issues - Creating custom VS Code extensions and debugging them doesn't work -- Extension profiling and tips are currently disabled \ No newline at end of file +- Extension profiling and tips are currently disabled From 568ade7e3cfac32ba47b014b4bd140a8b0da24b6 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Thu, 29 Oct 2020 10:07:49 -0500 Subject: [PATCH 4/5] Incorporate feedback --- README.md | 4 ++-- doc/CONTRIBUTING.md | 23 +++++++++++++---------- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 966bbb9bd990..ee0b8700bf3f 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and a There are two ways to get started: 1. Using the [install script](./install.sh), which automates most of the process. The script uses the system package manager (if possible) -2. Manually installing code-server; see [Installation](./doc/install.md#quick-install) for instructions applicable to most use cases +2. Manually installing code-server; see [Installation](./doc/install.md) for instructions applicable to most use cases If you choose to use the install script, you can preview what occurs during the install process: @@ -47,7 +47,7 @@ See [./doc/FAQ.md](./doc/FAQ.md). ## Want to help? -See [CONTRIBUTING](./doc/CONTRIBUTING.md) for additional details. +See [CONTRIBUTING](./doc/CONTRIBUTING.md) for details. ## Hiring diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index e1e418829558..6ec0868fbb3d 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -2,13 +2,14 @@ # Contributing -- [Pull Requests](#pull-requests) -- [Requirements](#requirements) -- [Development Workflow](#development-workflow) -- [Build](#build) -- [Structure](#structure) - - [VS Code Patch](#vs-code-patch) - - [Currently Known Issues](#currently-known-issues) +- [Contributing](#contributing) + - [Pull Requests](#pull-requests) + - [Requirements](#requirements) + - [Development Workflow](#development-workflow) + - [Build](#build) + - [Structure](#structure) + - [VS Code Patch](#vs-code-patch) + - [Currently Known Issues](#currently-known-issues) @@ -126,7 +127,7 @@ and exposed an API to the front-end for file access and all UI needs. Over 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 fills in with the server. You can find this in +the VS Code front-end and implements the server. You can find this in [./ci/dev/vscode.patch](../ci/dev/vscode.patch) under the path `src/vs/server`. Other notable changes in our patch include: @@ -144,8 +145,10 @@ Other notable changes in our patch include: - Adding connection type to web socket query parameters As the web portion of VS Code matures, we'll be able to shrink and possibly -eliminate our patch. In the meantime, upgrading the VS Code version requires us to ensure that the patch is applied and works as intended. In the future, we'd like to run VS -Code unit tests against our builds to ensure that features work as expected. +eliminate our patch. In the meantime, upgrading the VS Code version requires +us to ensure that the patch is applied and works as intended. In the future, +we'd like to run VS Code unit tests against our builds to ensure that features +work as expected. To generate a new patch, run `yarn vscode:diff` From e166ae8be16b4bcc49b998ce0285c154d812b47e Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Thu, 29 Oct 2020 15:41:27 -0500 Subject: [PATCH 5/5] Revert movement of CONTRIBUTING.MD and format --- doc/CONTRIBUTING.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 6ec0868fbb3d..52b4153a5148 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -2,14 +2,13 @@ # Contributing -- [Contributing](#contributing) - - [Pull Requests](#pull-requests) - - [Requirements](#requirements) - - [Development Workflow](#development-workflow) - - [Build](#build) - - [Structure](#structure) - - [VS Code Patch](#vs-code-patch) - - [Currently Known Issues](#currently-known-issues) +- [Pull Requests](#pull-requests) +- [Requirements](#requirements) +- [Development Workflow](#development-workflow) +- [Build](#build) +- [Structure](#structure) + - [VS Code Patch](#vs-code-patch) + - [Currently Known Issues](#currently-known-issues)