2020-06-04 00:07:42 +08:00
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE - RUN doctoc TO UPDATE -->
2020-02-19 08:07:01 +08:00
# Contributing
2020-08-26 19:08:02 +08:00
- [Pull Requests ](#pull-requests )
2020-06-04 00:07:42 +08:00
- [Requirements ](#requirements )
- [Development Workflow ](#development-workflow )
- [Build ](#build )
- [Structure ](#structure )
- [VS Code Patch ](#vs-code-patch )
2020-10-30 05:21:47 +08:00
- [Currently Known Issues ](#currently-known-issues )
2020-06-04 00:07:42 +08:00
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2020-04-30 19:52:54 +08:00
- [Detailed CI and build process docs ](../ci )
2020-08-26 19:08:02 +08:00
## Pull Requests
2020-10-30 05:21:47 +08:00
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.
2020-08-26 19:08:02 +08:00
2020-10-30 05:21:47 +08:00
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).
2020-08-26 19:08:02 +08:00
2020-05-13 11:11:31 +08:00
## Requirements
2020-10-30 05:21:47 +08:00
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:
2020-05-13 11:11:31 +08:00
2020-10-30 05:21:47 +08:00
- 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
2020-02-19 08:07:01 +08:00
2020-10-30 05:21:47 +08:00
The [CI container ](../ci/images/debian8/Dockerfile ) is a useful reference for all
of the dependencies code-server uses.
2020-05-13 11:11:31 +08:00
## Development Workflow
2020-02-19 08:07:01 +08:00
```shell
yarn
yarn vscode
2020-05-18 04:53:08 +08:00
yarn watch
2020-10-30 05:21:47 +08:00
# Visit http://localhost:8080 once the build is completed.
2020-02-19 08:07:01 +08:00
```
2020-10-30 05:21:47 +08:00
To develop inside an isolated Docker container:
2020-04-15 06:22:52 +08:00
```shell
2020-09-03 14:16:57 +08:00
./ci/dev/image/run.sh yarn
./ci/dev/image/run.sh yarn vscode
./ci/dev/image/run.sh yarn watch
2020-04-15 06:22:52 +08:00
```
2020-08-28 03:39:24 +08:00
`yarn watch` will live reload changes to the source.
2020-02-19 08:07:01 +08:00
2020-10-30 05:21:47 +08:00
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` .
2020-02-19 08:07:01 +08:00
## Build
2020-10-30 05:21:47 +08:00
You can build using:
2020-08-27 01:29:42 +08:00
```shell
2020-09-03 14:16:57 +08:00
./ci/dev/image/run.sh ./ci/steps/release.sh
2020-08-27 01:29:42 +08:00
```
Run your build with:
2020-10-30 05:21:47 +08:00
```shell
2020-08-27 01:29:42 +08:00
cd release
yarn --production
# Runs the built JavaScript with Node.
node .
```
2020-10-30 05:21:47 +08:00
Build the release packages (make sure that you run `./ci/steps/release.sh` first):
2020-08-27 01:29:42 +08:00
2020-10-30 05:21:47 +08:00
```shell
2020-09-15 22:41:47 +08:00
IMAGE=centos7 ./ci/dev/image/run.sh ./ci/steps/release-packages.sh
2020-08-27 01:29:42 +08:00
# The standalone release is in ./release-standalone
# .deb, .rpm and the standalone archive are in ./release-packages
```
2020-10-30 05:21:47 +08:00
The `release.sh` script is equal to running:
2020-08-27 01:29:42 +08:00
2020-02-19 08:07:01 +08:00
```shell
yarn
2020-02-27 04:48:08 +08:00
yarn vscode
2020-02-19 08:07:01 +08:00
yarn build
2020-04-30 19:52:54 +08:00
yarn build:vscode
yarn release
2020-02-19 08:07:01 +08:00
```
2020-05-13 11:11:31 +08:00
2020-10-30 05:21:47 +08:00
And `release-packages.sh` is equal to:
2020-05-13 11:11:31 +08:00
2020-10-30 05:21:47 +08:00
```shell
2020-05-28 04:39:17 +08:00
yarn release:standalone
yarn test:standalone-release
2020-05-13 11:11:31 +08:00
yarn package
```
2020-10-30 05:21:47 +08:00
For a faster release build, you can run instead:
2020-10-08 01:26:57 +08:00
2020-10-30 05:21:47 +08:00
```shell
2020-10-08 01:26:57 +08:00
KEEP_MODULES=1 ./ci/steps/release.sh
node ./release
```
2020-05-18 04:53:08 +08:00
## Structure
2020-10-30 05:21:47 +08:00
The `code-server` script serves an HTTP API for login and starting a remote VS Code process.
2020-05-18 04:53:08 +08:00
The CLI code is in [./src/node ](./src/node ) and the HTTP routes are implemented in
[./src/node/app ](./src/node/app ).
2020-10-30 05:21:47 +08:00
Most of the meaty parts are in the VS Code patch, which we described next.
2020-05-18 04:53:08 +08:00
### VS Code Patch
2020-10-30 05:21:47 +08:00
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.
2020-05-18 04:53:08 +08:00
2020-10-30 05:21:47 +08:00
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 implements the server. You can find this in
2020-05-18 04:53:08 +08:00
[./ci/dev/vscode.patch ](../ci/dev/vscode.patch ) under the path `src/vs/server` .
Other notable changes in our patch include:
2020-10-30 05:21:47 +08:00
- 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
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.
2020-05-18 04:53:08 +08:00
2020-10-30 05:21:47 +08:00
To generate a new patch, run `yarn vscode:diff`
2020-05-18 04:53:08 +08:00
2020-10-30 05:21:47 +08:00
**Note**: We have [extension docs ](../ci/README.md ) on the CI and build system.
2020-05-18 04:53:08 +08:00
2020-10-30 05:21:47 +08:00
If the functionality you're working on does NOT depend on code from VS Code, please
move it out and into code-server.
2020-05-18 04:53:08 +08:00
2020-10-30 05:21:47 +08:00
### Currently Known Issues
2020-05-18 04:53:08 +08:00
2020-10-30 05:21:47 +08:00
- Creating custom VS Code extensions and debugging them doesn't work
- Extension profiling and tips are currently disabled
