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-12-17 07:56:44 +08:00
- [Pull Requests ](#pull-requests )
- [Requirements ](#requirements )
- [Development Workflow ](#development-workflow )
- [Build ](#build )
- [Structure ](#structure )
- [Modifications to VS Code ](#modifications-to-vs-code )
- [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)
2020-12-09 02:04:07 +08:00
- Have [yarn ](https://classic.yarnpkg.com/en/ ) installed (which is used to install JS packages and run development scripts)
2020-10-30 05:21:47 +08:00
- 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
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 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
## 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
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-12-17 02:48:43 +08:00
Most of the meaty parts are in the VS Code portion of the codebase under [./lib/vscode ](./lib/vscode ), which we described next.
2020-05-18 04:53:08 +08:00
2020-12-17 05:56:14 +08:00
### Modifications to VS Code
2020-05-18 04:53:08 +08:00
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
2020-12-17 07:50:35 +08:00
the VS Code front-end and implements the server. We do this by using a git subtree to fork and modify VS Code. This code lives under [./lib/vscode ](./lib/vscode ).
2020-05-18 04:53:08 +08:00
2020-12-17 07:50:35 +08:00
Some noteworthy changes in our version of VS Code:
2020-05-18 04:53:08 +08:00
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
2020-12-17 07:50:35 +08:00
eliminate our modifications. In the meantime, upgrading the VS Code version requires
us to ensure that our changes are still applied and work as intended. In the future,
2020-10-30 05:21:47 +08:00
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
**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
