a
/
code-server
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs copyedits: README.md + CONTRIBUTING.md (#2242) 

* Edit README

* Edit CONTRIBUTING

* Format CONTRIBUTING.MD

* Incorporate feedback

* Revert movement of CONTRIBUTING.MD and format
This commit is contained in:
Katie Horne 2020-10-29 16:21:47 -05:00 committed by GitHub
parent 7e1e9d1249
commit 860c99e3b8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 79 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
README.md
View File

@ -6,72 +6,58 @@ Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and a
## Highlights ## Highlights
- **Code everywhere** - Code on any device with a consistent development environment
- Code on your Chromebook, tablet, and laptop with a consistent development environment. - Use cloud servers to speed up tests, compilations, downloads, and more
- Develop on a Linux machine and pick up from any device with a web browser. - Preserve battery life when you're on the go; all intensive tasks run on your server
- **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.
## Getting Started ## 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) for instructions applicable to most use cases
We have a [script](./install.sh) to install code-server for Linux, macOS and FreeBSD. If you choose to use the install script, you can preview what occurs during the install process:
It tries to use the system package manager if possible.
First run to print out the install process:
```bash ```bash
curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
``` ```
Now to actually install: To install, run:
```bash ```bash
curl -fsSL https://code-server.dev/install.sh | sh curl -fsSL https://code-server.dev/install.sh | sh
``` ```
The install script will print out how to run and start using code-server. When done, the install script prints out instructions for running and starting code-server.
### Manual Install We also have an in-depth [setup and configuration](./doc/guide.md) guide.
Docs on the install script, manual installation and docker image are at [./doc/install.md](./doc/install.md).
### Alpha Program 🐣 ### 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 - TLS
- Authentication - Authentication
- Port Forwarding - Port Forwarding
consider [joining our alpha program](https://codercom.typeform.com/to/U4IKyv0W).
## FAQ ## FAQ
See [./doc/FAQ.md](./doc/FAQ.md). See [./doc/FAQ.md](./doc/FAQ.md).
## Contributing ## Want to help?
See [./doc/CONTRIBUTING.md](./doc/CONTRIBUTING.md). See [CONTRIBUTING](./doc/CONTRIBUTING.md) for details.
## Hiring ## Hiring
We ([@cdr](https://github.com/cdr)) are looking for engineers to help maintain We ([@cdr](https://github.com/cdr)) are looking for engineers to help [maintain
code-server, innovate on open source and streamline dev workflows. 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 Our main office is in Austin, Texas. Remote is ok as long as
you're in North America or Europe. you're in North America or Europe.
Please get in [touch](mailto:jobs@coder.com) with your resume/github if interested. 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).
## For Organizations ## For Organizations

127
doc/CONTRIBUTING.md
View File

@ -8,6 +8,7 @@
- [Build](#build) - [Build](#build)
- [Structure](#structure) - [Structure](#structure)
- [VS Code Patch](#vs-code-patch) - [VS Code Patch](#vs-code-patch)
- [Currently Known Issues](#currently-known-issues)
<!-- END doctoc generated TOC please keep comment here to allow auto update --> <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@ -15,24 +16,26 @@
## Pull Requests ## Pull Requests
Please link to the issue each PR solves. Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) for each issue
If there is no existing issue, please first create one unless the fix is minor. 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 In your Pull Requests (PR), link to the issue that the PR solves.
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 Please ensure that the base of your PR is the **master** branch. (Note: The default
features. GitHub branch is the latest release branch, though you should point all of your changes to be merged into
master).
## Requirements ## 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. The [CI container](../ci/images/debian8/Dockerfile) is a useful reference for all
- We use [nfpm](https://github.com/goreleaser/nfpm) to build `.deb` and `.rpm` packages. of the dependencies code-server uses.
- 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.
## Development Workflow ## Development Workflow
@ -40,10 +43,10 @@ Differences:
yarn yarn
yarn vscode yarn vscode
yarn watch 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 ```shell
./ci/dev/image/run.sh yarn ./ci/dev/image/run.sh yarn
@ -53,12 +56,12 @@ To develop inside of an isolated docker container:
`yarn watch` will live reload changes to the source. `yarn watch` will live reload changes to the source.
If changes are made to the patch and you've built previously you must manually If you introduce changes to the patch and you've previously built, you
reset VS Code then run `yarn vscode:patch`. must (1) manually reset VS Code and (2) run `yarn vscode:patch`.
## Build ## Build
You can build with: You can build using:
```shell ```shell
./ci/dev/image/run.sh ./ci/steps/release.sh ./ci/dev/image/run.sh ./ci/steps/release.sh
@ -66,22 +69,22 @@ You can build with:
Run your build with: Run your build with:
``` ```shell
cd release cd release
yarn --production yarn --production
# Runs the built JavaScript with Node. # Runs the built JavaScript with Node.
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 IMAGE=centos7 ./ci/dev/image/run.sh ./ci/steps/release-packages.sh
# The standalone release is in ./release-standalone # The standalone release is in ./release-standalone
# .deb, .rpm and the standalone archive are in ./release-packages # .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 ```shell
yarn yarn
@ -91,73 +94,69 @@ yarn build:vscode
yarn release yarn release
``` ```
And `release-packages.sh` is: And `release-packages.sh` is equal to:
``` ```shell
yarn release:standalone yarn release:standalone
yarn test:standalone-release yarn test:standalone-release
yarn package 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 KEEP_MODULES=1 ./ci/steps/release.sh
node ./release node ./release
``` ```
## Structure ## 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 The CLI code is in [./src/node](./src/node) and the HTTP routes are implemented in
[./src/node/app](./src/node/app). [./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 ### VS Code Patch
Back in v1 of code-server, we had an extensive patch of VS Code that split the codebase In v1 of code-server, we had a patch of VS Code that split the codebase into a front-end
into a frontend and server. The frontend consisted of all UI code and the server ran and a server. The front-end consisted of all UI code, while the server ran the extensions
the extensions and exposed an API to the frontend for file access and everything else and exposed an API to the front-end for file access and all UI needs.
that the UI needed.
This worked but eventually Microsoft added support to VS Code to run it in the web. Over time, Microsoft added support to VS Code to run it on the web. They have made
They have open sourced the frontend but have kept the server closed source. 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 in
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
[./ci/dev/vscode.patch](../ci/dev/vscode.patch) under the path `src/vs/server`. [./ci/dev/vscode.patch](../ci/dev/vscode.patch) under the path `src/vs/server`.
Other notable changes in our patch include: Other notable changes in our patch include:
- Add our own build file which includes our code and VS Code's web code. - Adding our build file, which includes our code and VS Code's web code
- Allow multiple extension directories (both user and built-in). - Allowing multiple extension directories (both user and built-in)
- Modify the loader, websocket, webview, service worker, and asset requests to - 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). use the URL of the page as a base (and TLS, if necessary for the websocket)
- Send client-side telemetry through the server. - Sending client-side telemetry through the server
- Allow modification of the display language. - Allowing modification of the display language
- Make it possible for us to load code on the client. - Making it possible for us to load code on the client
- Make extensions work in the browser. - Making extensions work in the browser
- Make it possible to install extensions of any kind. - Making it possible to install extensions of any kind
- Fix getting permanently disconnected when you sleep or hibernate for a while. - Fixing issue with getting disconnected when your machine sleeps or hibernates
- Add connection type to web socket query parameters. - Adding connection type to web socket query parameters
Some known issues presently: 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
- Creating custom VS Code extensions and debugging them doesn't work. us to ensure that the patch is applied and works as intended. In the future,
- Extension profiling and tips are currently disabled. we'd like to run VS Code unit tests against our builds to ensure that features
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`.
**note**: We have extension docs on the CI and build system at [./ci/README.md](../ci/README.md)
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.
In the future we'd like to run VS Code unit tests against our builds to ensure features
work as expected. work as expected.
To generate a new patch, run `yarn vscode:diff`
**Note**: We have [extension docs](../ci/README.md) on the CI and build system.
If the functionality you're working on does NOT depend on code from VS Code, please
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