Skip to content

refactor(docs): clean up and restructure #3756

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 12, 2021
Merged

refactor(docs): clean up and restructure #3756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 108 additions & 84 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,16 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# Contributing

- [Pull Requests](#pull-requests)
- [Commits](#commits)
- [Requirements](#requirements)
- [Development Workflow](#development-workflow)
- [Updating VS Code](#updating-vs-code)
- [Notes about Changes](#notes-about-changes)
- [Build](#build)
- [Testing](#testing)
- [Unit Tests](#unit-tests)
- [Integration Tests](#integration-tests)
- [End-to-End Tests](#end-to-end-tests)
- [Creating pull requests](#creating-pull-requests)
- [Commits and commit history](#commits-and-commit-history)
- [Development workflow](#development-workflow)
- [Updates to VS Code](#updates-to-vs-code)
- [Build](#build)
- [Test](#test)
- [Unit tests](#unit-tests)
- [Integration tests](#integration-tests)
- [End-to-end tests](#end-to-end-tests)
- [Structure](#structure)
- [Modifications to VS Code](#modifications-to-vs-code)
- [Currently Known Issues](#currently-known-issues)
Expand All @@ -21,41 +20,49 @@

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

## Pull Requests

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.

In your Pull Requests (PR), link to the issue that the PR solves.

Please ensure that the base of your PR is the **main** branch.

### Commits

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.

## Requirements

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. Here is what is needed:
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).
Here is what is needed:

- `node` v14.x
- `git` v2.x or greater
- [`yarn`](https://classic.yarnpkg.com/en/)
- used to install JS packages and run scripts
- Used to install JS packages and run scripts
- [`nfpm`](https://classic.yarnpkg.com/en/)
- used to build `.deb` and `.rpm` packages
- Used to build `.deb` and `.rpm` packages
- [`jq`](https://stedolan.github.io/jq/)
- used to build code-server releases
- Used to build code-server releases
- [`gnupg`](https://gnupg.org/index.html)
- all commits must be signed and verified
- 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)
- `build-essential` (Linux)
- `apt-get install -y build-essential` - used by VS Code
- All commits must be signed and verified; 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)
- `build-essential` (Linux only - used by VS Code)
- Get this by running `apt-get install -y build-essential`
- `rsync` and `unzip`
- used for code-server releases
- Used for code-server releases

## Creating pull requests

## Development Workflow
Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) that
includes context for issues that you see. You can skip this if the proposed fix
is minor.

In your pull requests (PR), link to the issue that the PR solves.

Please ensure that the base of your PR is the **main** branch.

### Commits and commit history

We prefer a clean commit history. This means you should squash all fixups and
fixup-type commits before asking for a review (e.g., clean up, squash, then force
push). If you need help with this, feel free to leave a comment in your PR, and
we'll guide you.

## Development workflow

```shell
yarn
Expand All @@ -65,36 +72,38 @@ yarn watch

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

### Updating VS Code
### Updates to VS Code

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 install, run `dnf install git-subtree` or `yum install git-subtree` as necessary.
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
install, run `dnf install git-subtree` or `yum install git-subtree`.

To update VS Code, follow these steps:
To update VS Code:

1. Run `yarn update:vscode`.
2. Enter a version. Ex. 1.53
3. This will open a draft PR for you.
4. There will be merge conflicts. First commit them.
1. We do this because if we don't, it will be impossible to review your PR.
5. Once they're all fixed, test code-server locally and make sure it all works.
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.

#### Notes about Changes
2. Enter a version (e.g., `1.53`)
3. This will open a draft pull request for you.
4. There will be merge conflicts. Commit them first, since it will be impossible
for us to review your PR if you don't.
5. Fix the conflicts. Then, test code-server locally to make sure everything
works.
6. Check the Node.js version that's used by Electron (which is shipped with VS
Code. If necessary, update your version of Node.js to match.

- 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`
> Watch for updates to
> `lib/vscode/src/vs/code/browser/workbench/workbench.html`. You may need to
> make changes to `src/browser/pages/vscode.html`.

## Build
### Build

You can build using:
You can build as follows:

```shell
yarn build
yarn build:vscode
yarn release
```

Run your build with:
Run your build:

```shell
cd release
Expand All @@ -111,73 +120,88 @@ yarn test:standalone-release
yarn package
```

NOTE: On Linux, the currently running distro will become the minimum supported version.
In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
If you need your builds to support older distros, run the build commands
inside a Docker container with all the build requirements installed.
> On Linux, the currently running distro will become the minimum supported
> version. In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
> If you need your builds to support older distros, run the build commands
> inside a Docker container with all the build requirements installed.

## Testing
### Test

There are three kinds of tests in code-server:

1. unit tests
2. integration tests
3. end-to-end tests
1. Unit tests
2. Integration tests
3. End-to-end tests

### Unit Tests
### Unit tests

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

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

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

### Integration Tests
### Integration tests

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)
which ensures that code-server's CLI is working.
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), which
ensures that code-server's CLI is working.

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

### End-to-End Tests
### End-to-end tests

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

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

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

Take a look at `codeServer.test.ts` to see how you use it (look at `test.use`).
Take a look at `codeServer.test.ts` to see how you would use it (see
`test.use`).

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

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.
Generally speaking, e2e means testing code-server while running in the browser
and interacting with it in a way that's 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.

## Structure

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

The CLI code is in [src/node](../src/node) and the HTTP routes are implemented in
[src/node/routes](../src/node/routes).
The CLI code is in [src/node](../src/node) and the HTTP routes are implemented
in [src/node/routes](../src/node/routes).

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

### Modifications to VS Code

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.
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 the UI code, while the server
ran the extensions and exposed an API to the front-end for file access and all
UI needs.

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. We do this by using a git subtree to fork and modify VS Code. This code lives under [lib/vscode](../lib/vscode).
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. We do this by using
a Git subtree to fork and modify VS Code. This code lives under
[lib/vscode](../lib/vscode).

Some noteworthy changes in our version of VS Code:
Some noteworthy changes in our version of VS Code include:

- 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)
- 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
Expand All @@ -191,7 +215,7 @@ us to ensure that our changes are still applied and work as intended. In the fut
we'd like to run VS Code unit tests against our builds to ensure that features
work as expected.

**Note**: We have [extension docs](../ci/README.md) on the CI and build system.
> We have [extension docs](../ci/README.md) on the CI and build system.

If the functionality you're working on does NOT depend on code from VS Code, please
move it out and into code-server.
Expand Down
Loading