Skip to content

Commit c145008

Browse files
author
Katie Horne
authored
Merge pull request #3756 from cdr/docs-edits
refactor(docs): clean up and restructure
2 parents a96e16e + 66b6590 commit c145008

13 files changed

+1199
-1038
lines changed

‎docs/CONTRIBUTING.md

+108-84
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,16 @@
22
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
33
# Contributing
44

5-
- [Pull Requests](#pull-requests)
6-
- [Commits](#commits)
75
- [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)
6+
- [Creating pull requests](#creating-pull-requests)
7+
- [Commits and commit history](#commits-and-commit-history)
8+
- [Development workflow](#development-workflow)
9+
- [Updates to VS Code](#updates-to-vs-code)
10+
- [Build](#build)
11+
- [Test](#test)
12+
- [Unit tests](#unit-tests)
13+
- [Integration tests](#integration-tests)
14+
- [End-to-end tests](#end-to-end-tests)
1615
- [Structure](#structure)
1716
- [Modifications to VS Code](#modifications-to-vs-code)
1817
- [Currently Known Issues](#currently-known-issues)
@@ -21,41 +20,49 @@
2120

2221
- [Detailed CI and build process docs](../ci)
2322

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-
3623
## Requirements
3724

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:
25+
The prerequisites for contributing to code-server are almost the same as those
26+
for [VS
27+
Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
28+
Here is what is needed:
4129

4230
- `node` v14.x
4331
- `git` v2.x or greater
4432
- [`yarn`](https://classic.yarnpkg.com/en/)
45-
- used to install JS packages and run scripts
33+
- Used to install JS packages and run scripts
4634
- [`nfpm`](https://classic.yarnpkg.com/en/)
47-
- used to build `.deb` and `.rpm` packages
35+
- Used to build `.deb` and `.rpm` packages
4836
- [`jq`](https://stedolan.github.io/jq/)
49-
- used to build code-server releases
37+
- Used to build code-server releases
5038
- [`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
39+
- All commits must be signed and verified; see GitHub's [Managing commit
40+
signature
41+
verification](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification)
42+
or follow [this tutorial](https://joeprevite.com/verify-commits-on-github)
43+
- `build-essential` (Linux only - used by VS Code)
44+
- Get this by running `apt-get install -y build-essential`
5545
- `rsync` and `unzip`
56-
- used for code-server releases
46+
- Used for code-server releases
47+
48+
## Creating pull requests
5749

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

6067
```shell
6168
yarn
@@ -65,36 +72,38 @@ yarn watch
6572

6673
`yarn watch` will live reload changes to the source.
6774

68-
### Updating VS Code
75+
### Updates to VS Code
6976

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.
77+
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. To
78+
install, run `dnf install git-subtree` or `yum install git-subtree`.
7279

73-
To update VS Code, follow these steps:
80+
To update VS Code:
7481

7582
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
83+
2. Enter a version (e.g., `1.53`)
84+
3. This will open a draft pull request for you.
85+
4. There will be merge conflicts. Commit them first, since it will be impossible
86+
for us to review your PR if you don't.
87+
5. Fix the conflicts. Then, test code-server locally to make sure everything
88+
works.
89+
6. Check the Node.js version that's used by Electron (which is shipped with VS
90+
Code. If necessary, update your version of Node.js to match.
8491

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`
92+
> Watch for updates to
93+
> `lib/vscode/src/vs/code/browser/workbench/workbench.html`. You may need to
94+
> make changes to `src/browser/pages/vscode.html`.
8695
87-
## Build
96+
### Build
8897

89-
You can build using:
98+
You can build as follows:
9099

91100
```shell
92101
yarn build
93102
yarn build:vscode
94103
yarn release
95104
```
96105

97-
Run your build with:
106+
Run your build:
98107

99108
```shell
100109
cd release
@@ -111,73 +120,88 @@ yarn test:standalone-release
111120
yarn package
112121
```
113122

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.
123+
> On Linux, the currently running distro will become the minimum supported
124+
> version. In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
125+
> If you need your builds to support older distros, run the build commands
126+
> inside a Docker container with all the build requirements installed.
118127
119-
## Testing
128+
### Test
120129

121130
There are three kinds of tests in code-server:
122131

123-
1. unit tests
124-
2. integration tests
125-
3. end-to-end tests
132+
1. Unit tests
133+
2. Integration tests
134+
3. End-to-end tests
126135

127-
### Unit Tests
136+
### Unit tests
128137

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

131141
These live under [test/unit](../test/unit).
132142

133143
We use unit tests for functions and things that can be tested in isolation.
134144

135-
### Integration Tests
145+
### Integration tests
136146

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.
147+
These are a work in progress. We build code-server and run a script called
148+
[test-standalone-release.sh](../ci/build/test-standalone-release.sh), which
149+
ensures that code-server's CLI is working.
139150

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.
151+
Our integration tests look at components that rely on one another. For example,
152+
testing the CLI requires us to build and package code-server.
141153

142-
### End-to-End Tests
154+
### End-to-end tests
143155

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

146159
These live under [test/e2e](../test/e2e).
147160

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.
161+
Before the e2e tests run, we run `globalSetup`, which eliminates the need to log
162+
in before each test by preserving the authentication state.
149163

150-
Take a look at `codeServer.test.ts` to see how you use it (look at `test.use`).
164+
Take a look at `codeServer.test.ts` to see how you would use it (see
165+
`test.use`).
151166

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.
167+
We also have a model where you can create helpers to use within tests. See
168+
[models/CodeServer.ts](../test/e2e/models/CodeServer.ts) for an example.
153169

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.
170+
Generally speaking, e2e means testing code-server while running in the browser
171+
and interacting with it in a way that's similar to how a user would interact
172+
with it. When running these tests with `yarn test:e2e`, you must have
173+
code-server running locally. In CI, this is taken care of for you.
155174

156175
## Structure
157176

158-
The `code-server` script serves an HTTP API for login and starting a remote VS Code process.
177+
The `code-server` script serves as an HTTP API for login and starting a remote VS
178+
Code process.
159179

160-
The CLI code is in [src/node](../src/node) and the HTTP routes are implemented in
161-
[src/node/routes](../src/node/routes).
180+
The CLI code is in [src/node](../src/node) and the HTTP routes are implemented
181+
in [src/node/routes](../src/node/routes).
162182

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

165186
### Modifications to VS Code
166187

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.
188+
In v1 of code-server, we had a patch of VS Code that split the codebase into a
189+
front-end and a server. The front-end consisted of the UI code, while the server
190+
ran the extensions and exposed an API to the front-end for file access and all
191+
UI needs.
170192

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

175-
Some noteworthy changes in our version of VS Code:
199+
Some noteworthy changes in our version of VS Code include:
176200

177201
- Adding our build file, which includes our code and VS Code's web code
178202
- 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)
203+
- Modifying the loader, WebSocket, webview, service worker, and asset requests to
204+
use the URL of the page as a base (and TLS, if necessary for the WebSocket)
181205
- Sending client-side telemetry through the server
182206
- Allowing modification of the display language
183207
- Making it possible for us to load code on the client
@@ -191,7 +215,7 @@ us to ensure that our changes are still applied and work as intended. In the fut
191215
we'd like to run VS Code unit tests against our builds to ensure that features
192216
work as expected.
193217

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

0 commit comments

Comments
 (0)