Skip to content

Commit 0c0a221

Browse files
author
Katie Horne
committed
refactor(docs): clean up and restructure
1 parent a96e16e commit 0c0a221

13 files changed

+1221
-1060
lines changed

‎docs/CONTRIBUTING.md

+113-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+
- [Updates to VS Code](#updates-to-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+
- [Modifications to VS Code](#modifications-to-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,38 @@ yarn watch
6573

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

68-
### Updating VS Code
76+
### Updates to 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 subtree` is not included by default and needs to be installed separately. To
79+
install, run `dnf install git-subtree` or `yum install git-subtree`.
7280

73-
To update VS Code, follow these steps:
81+
To update VS Code:
7482

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

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

89-
You can build using:
99+
You can build as follows:
90100

91101
```shell
92102
yarn build
93103
yarn build:vscode
94104
yarn release
95105
```
96106

97-
Run your build with:
107+
Run your build:
98108

99109
```shell
100110
cd release
@@ -111,73 +121,88 @@ yarn test:standalone-release
111121
yarn package
112122
```
113123

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

121131
There are three kinds of tests in code-server:
122132

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

127-
### Unit Tests
137+
### Unit tests
128138

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

131142
These live under [test/unit](../test/unit).
132143

133144
We use unit tests for functions and things that can be tested in isolation.
134145

135-
### Integration Tests
146+
### Integration tests
136147

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

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

142-
### End-to-End Tests
155+
### End-to-end tests
143156

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

146160
These live under [test/e2e](../test/e2e).
147161

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

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

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

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

156176
## Structure
157177

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

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

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

165187
### Modifications to VS Code
166188

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

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

175-
Some noteworthy changes in our version of VS Code:
200+
Some noteworthy changes in our version of VS Code include:
176201

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

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

0 commit comments

Comments
 (0)