Skip to content

Commit 4d6bbab

Browse files
author
Katie Horne
committed
Edit code-server docs
1 parent c5bfe6d commit 4d6bbab

13 files changed

+1163
-1022
lines changed

‎docs/CONTRIBUTING.md

+114-88
Original file line numberDiff line numberDiff line change
@@ -2,60 +2,68 @@
22
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
33
# Contributing
44

5-
- [Pull Requests](#pull-requests)
6-
- [Commits](#commits)
7-
- [Requirements](#requirements)
8-
- [Development Workflow](#development-workflow)
9-
- [Updating VS Code](#updating-vs-code)
10-
- [Notes about Changes](#notes-about-changes)
11-
- [Build](#build)
12-
- [Testing](#testing)
13-
- [Unit Tests](#unit-tests)
14-
- [Integration Tests](#integration-tests)
15-
- [End-to-End Tests](#end-to-end-tests)
16-
- [Structure](#structure)
17-
- [Modifications to VS Code](#modifications-to-vs-code)
18-
- [Currently Known Issues](#currently-known-issues)
5+
- [Contributing](#contributing)
6+
- [Requirements](#requirements)
7+
- [Creating pull requests](#creating-pull-requests)
8+
- [Commits and commit history](#commits-and-commit-history)
9+
- [Development workflow](#development-workflow)
10+
- [Update VS Code](#update-vs-code)
11+
- [Build](#build)
12+
- [Test](#test)
13+
- [Unit tests](#unit-tests)
14+
- [Integration Tests](#integration-tests)
15+
- [End-to-end tests](#end-to-end-tests)
16+
- [Structure](#structure)
17+
- [Modifying VS Code](#modifying-vs-code)
18+
- [Currently Known Issues](#currently-known-issues)
1919

2020
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2121

2222
- [Detailed CI and build process docs](../ci)
2323

24-
## Pull Requests
25-
26-
Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) to address any issue. You can skip this if the proposed fix is minor.
27-
28-
In your Pull Requests (PR), link to the issue that the PR solves.
29-
30-
Please ensure that the base of your PR is the **main** branch.
31-
32-
### Commits
33-
34-
We prefer a clean commit history. This means you should squash all fixups and fixup-type commits before asking for review (cleanup, squash, force-push). If you need help with this, feel free to leave a comment in your PR and we'll guide you.
35-
3624
## Requirements
3725

38-
The prerequisites for contributing to code-server are almost the same as those for
39-
[VS Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
40-
There are several differences, however. Here is what is needed:
26+
The prerequisites for contributing to code-server are almost the same as those
27+
for [VS
28+
Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
29+
Here is what is needed:
4130

4231
- `node` v14.x
4332
- `git` v2.x or greater
4433
- [`yarn`](https://classic.yarnpkg.com/en/)
45-
- used to install JS packages and run scripts
34+
- Used to install JS packages and run scripts
4635
- [`nfpm`](https://classic.yarnpkg.com/en/)
47-
- used to build `.deb` and `.rpm` packages
36+
- Used to build `.deb` and `.rpm` packages
4837
- [`jq`](https://stedolan.github.io/jq/)
49-
- used to build code-server releases
38+
- Used to build code-server releases
5039
- [`gnupg`](https://gnupg.org/index.html)
51-
- all commits must be signed and verified
52-
- see GitHub's ["Managing commit signature verification"](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification) or follow [this tutorial](https://joeprevite.com/verify-commits-on-github)
53-
- `build-essential` (Linux)
54-
- `apt-get install -y build-essential` - used by VS Code
40+
- All commits must be signed and verified; see GitHub's [Managing commit
41+
signature
42+
verification](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification)
43+
or follow [this tutorial](https://joeprevite.com/verify-commits-on-github)
44+
- `build-essential` (Linux only - used by VS Code)
45+
- Get this by running `apt-get install -y build-essential`
5546
- `rsync` and `unzip`
56-
- used for code-server releases
47+
- Used for code-server releases
48+
49+
## Creating pull requests
5750

58-
## Development Workflow
51+
Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) that
52+
includes context for issues that you see. You can skip this if the proposed fix
53+
is minor.
54+
55+
In your pull requests (PR), link to the issue that the PR solves.
56+
57+
Please ensure that the base of your PR is the **main** branch.
58+
59+
### Commits and commit history
60+
61+
We prefer a clean commit history. This means you should squash all fixups and
62+
fixup-type commits before asking for a review (e.g., clean up, squash, then force
63+
push). If you need help with this, feel free to leave a comment in your PR, and
64+
we'll guide you.
65+
66+
## Development workflow
5967

6068
```shell
6169
yarn
@@ -65,36 +73,39 @@ yarn watch
6573

6674
`yarn watch` will live reload changes to the source.
6775

68-
### Updating VS Code
76+
### Update VS Code
6977

70-
Updating VS Code requires `git subtree`. On some rpm-based Linux distros, `git subtree` is not included by default, and needs to be installed separately.
71-
To install, run `dnf install git-subtree` or `yum install git-subtree` as necessary.
78+
Updating VS Code requires `git subtree`. On some RPM-based Linux distros, `git
79+
subtree` is not included by default and needs to be installed separately. To
80+
install, run `dnf install git-subtree` or `yum install git-subtree`.
7281

73-
To update VS Code, follow these steps:
82+
To update VS Code:
7483

7584
1. Run `yarn update:vscode`.
76-
2. Enter a version. Ex. 1.53
77-
3. This will open a draft PR for you.
78-
4. There will be merge conflicts. First commit them.
79-
1. We do this because if we don't, it will be impossible to review your PR.
80-
5. Once they're all fixed, test code-server locally and make sure it all works.
81-
6. Check the version of Node.js that the version of Electron shipped with VSCode uses, and update the version of Node.js if necessary.
82-
83-
#### Notes about Changes
85+
2. Enter a version (e.g., `1.53`)
86+
3. This will open a draft pull request for you.
87+
4. There will be merge conflicts. Commit them first, since it will be impossible
88+
for us to review your PR if you don't.
89+
5. Fix the conflicts. Then, test code-server locally to make sure everything
90+
works.
91+
6. Check the Node.js version that's used by Electron (which is shipped with VS
92+
Code. If necessary, update your version of Node.js to match.
8493

85-
- watch out for updates to `lib/vscode/src/vs/code/browser/workbench/workbench.html`. You may need to make changes to `src/browser/pages/vscode.html`
94+
> Watch for updates to
95+
> `lib/vscode/src/vs/code/browser/workbench/workbench.html`. You may need to
96+
> make changes to `src/browser/pages/vscode.html`.
8697
87-
## Build
98+
### Build
8899

89-
You can build using:
100+
You can build as follows:
90101

91102
```shell
92103
yarn build
93104
yarn build:vscode
94105
yarn release
95106
```
96107

97-
Run your build with:
108+
Run your build:
98109

99110
```shell
100111
cd release
@@ -111,73 +122,88 @@ yarn test:standalone-release
111122
yarn package
112123
```
113124

114-
NOTE: On Linux, the currently running distro will become the minimum supported version.
115-
In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
116-
If you need your builds to support older distros, run the build commands
117-
inside a Docker container with all the build requirements installed.
125+
> On Linux, the currently running distro will become the minimum supported
126+
> version. In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
127+
> If you need your builds to support older distros, run the build commands
128+
> inside a Docker container with all the build requirements installed.
118129
119-
## Testing
130+
### Test
120131

121132
There are three kinds of tests in code-server:
122133

123-
1. unit tests
124-
2. integration tests
125-
3. end-to-end tests
134+
1. Unit tests
135+
2. Integration tests
136+
3. End-to-end tests
126137

127-
### Unit Tests
138+
### Unit tests
128139

129-
Our unit tests are written in TypeScript and run using [Jest, the testing framework](https://jestjs.io/).
140+
Our unit tests are written in TypeScript and run using
141+
[Jest](https://jestjs.io/), the testing framework].
130142

131143
These live under [test/unit](../test/unit).
132144

133145
We use unit tests for functions and things that can be tested in isolation.
134146

135147
### Integration Tests
136148

137-
These are a work-in-progress. We build code-server and run a script called [test-standalone-release.sh`](../ci/build/test-standalone-release.sh)
138-
which ensures that code-server's CLI is working.
149+
These are a work in progress. We build code-server and run a script called
150+
[test-standalone-release.sh](../ci/build/test-standalone-release.sh), which
151+
ensures that code-server's CLI is working.
139152

140-
Integration for us means testing things that integrate and rely on each other. For instance, testing the CLI which requires that code-server be built and packaged.
153+
Our integration tests look at components that rely on one another. For example,
154+
testing the CLI requires us to build and package code-server.
141155

142-
### End-to-End Tests
156+
### End-to-end tests
143157

144-
The end-to-end (e2e) are written in TypeScript and run using [Playwright](https://playwright.dev/).
158+
The end-to-end (e2e) tests are written in TypeScript and run using
159+
[Playwright](https://playwright.dev/).
145160

146161
These live under [test/e2e](../test/e2e).
147162

148-
Before the e2e tests run, we have a `globalSetup` that runs which makes it so you don't have to login before each test and can reuse the authentication state.
163+
Before the e2e tests run, we run `globalSetup`, which eliminates the need to log
164+
in before each test by preserving the authentication state.
149165

150-
Take a look at `codeServer.test.ts` to see how you use it (look at `test.use`).
166+
Take a look at `codeServer.test.ts` to see how you would use it (see
167+
`test.use`).
151168

152-
We also have a model where you can create helpers to use within tests. Take a look at [models/CodeServer.ts](../test/e2e/models/CodeServer.ts) to see an example.
169+
We also have a model where you can create helpers to use within tests. See
170+
[models/CodeServer.ts](../test/e2e/models/CodeServer.ts) for an example.
153171

154-
Generally speaking, e2e means testing code-server running in the browser, similar to how a user would interact with it. When running these tests with `yarn test:e2e`, you must have code-server running locally. In CI, this is taken care of for you.
172+
Generally speaking, e2e means testing code-server while running in the browser
173+
and interacting with it in a way that's similar to how a user would interact
174+
with it. When running these tests with `yarn test:e2e`, you must have
175+
code-server running locally. In CI, this is taken care of for you.
155176

156177
## Structure
157178

158-
The `code-server` script serves an HTTP API for login and starting a remote VS Code process.
179+
The `code-server` script serves as an HTTP API for login and starting a remote VS
180+
Code process.
159181

160-
The CLI code is in [src/node](../src/node) and the HTTP routes are implemented in
161-
[src/node/routes](../src/node/routes).
182+
The CLI code is in [src/node](../src/node) and the HTTP routes are implemented
183+
in [src/node/routes](../src/node/routes).
162184

163-
Most of the meaty parts are in the VS Code portion of the codebase under [lib/vscode](../lib/vscode), which we described next.
185+
Most of the meaty parts are in the VS Code portion of the codebase under
186+
[lib/vscode](../lib/vscode), which we describe next.
164187

165-
### Modifications to VS Code
188+
### Modifying VS Code
166189

167-
In v1 of code-server, we had a patch of VS Code that split the codebase into a front-end
168-
and a server. The front-end consisted of all UI code, while the server ran the extensions
169-
and exposed an API to the front-end for file access and all UI needs.
190+
In v1 of code-server, we had a patch of VS Code that split the codebase into a
191+
front-end and a server. The front-end consisted of the UI code, while the server
192+
ran the extensions and exposed an API to the front-end for file access and all
193+
UI needs.
170194

171-
Over time, Microsoft added support to VS Code to run it on the web. They have made
172-
the front-end open source, but not the server. As such, code-server v2 (and later) uses
173-
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).
195+
Over time, Microsoft added support to VS Code to run it on the web. They have
196+
made the front-end open source, but not the server. As such, code-server v2 (and
197+
later) uses the VS Code front-end and implements the server. We do this by using
198+
a Git subtree to fork and modify VS Code. This code lives under
199+
[lib/vscode](../lib/vscode).
174200

175-
Some noteworthy changes in our version of VS Code:
201+
Some noteworthy changes in our version of VS Code include:
176202

177203
- Adding our build file, which includes our code and VS Code's web code
178204
- Allowing multiple extension directories (both user and built-in)
179-
- Modifying the loader, websocket, webview, service worker, and asset requests to
180-
use the URL of the page as a base (and TLS, if necessary for the websocket)
205+
- Modifying the loader, WebSocket, webview, service worker, and asset requests to
206+
use the URL of the page as a base (and TLS, if necessary for the WebSocket)
181207
- Sending client-side telemetry through the server
182208
- Allowing modification of the display language
183209
- Making it possible for us to load code on the client
@@ -191,7 +217,7 @@ us to ensure that our changes are still applied and work as intended. In the fut
191217
we'd like to run VS Code unit tests against our builds to ensure that features
192218
work as expected.
193219

194-
**Note**: We have [extension docs](../ci/README.md) on the CI and build system.
220+
> We have [extension docs](../ci/README.md) on the CI and build system.
195221
196222
If the functionality you're working on does NOT depend on code from VS Code, please
197223
move it out and into code-server.

0 commit comments

Comments
 (0)