a/code-server
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
6a2740f57e
code-server/docs/CONTRIBUTING.md
Joe Previte 16a5f2e171
docs: update CONTRIBUTING with new flow (#4502)
2021-11-15 11:37:16 -07:00

17 KiB
Raw Blame History

Contributing

Requirements

The prerequisites for contributing to code-server are almost the same as those for VS Code. Here is what is needed:

  • node v14.x
  • git v2.x or greater
  • git-lfs
  • yarn
    • Used to install JS packages and run scripts
  • nfpm
    • Used to build .deb and .rpm packages
  • jq
    • Used to build code-server releases
  • gnupg
  • rsync and unzip
    • Used for code-server releases
  • bats
    • Used to run script unit tests

Linux-specific requirements

If you're developing code-server on Linux, make sure you have installed or install the following dependencies:

sudo apt-get install build-essential g++ libx11-dev libxkbfile-dev libsecret-1-dev python-is-python3

These are required by VS Code. See their Wiki for more information.

Creating pull requests

Please create a GitHub Issue 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

The current development workflow is a bit tricky because we have this repo and we use our cdr/vscode fork inside it with yarn link.

Here are these steps you should follow to get your dev environment setup:

  1. git clone https://github.com/cdr/code-server.git - Clone code-server
  2. git clone https://github.com/cdr/vscode.git - Clone vscode
  3. cd vscode && git checkout code-server-v2 - checkout the branch we use (not the default)
  4. cd vscode && yarn install - install the dependencies in the vscode repo
  5. cd code-server && yarn install - install the dependencies in the code-server repo
  6. cd vscode && yarn link - use yarn to create a symlink to the vscode repo (code-oss-dev package)
  7. cd code-server && yarn link code-oss-dev --modules-folder vendor/modules - links your local vscode repo (code-oss-dev package) inside your local version of code-server
  8. cd code-server && yarn watch - this will spin up code-server on localhost:8080 which you can start developing. It will live reload changes to the source.

Updates to VS Code

If changes are made and merged into code-server-v2 in the cdr/vscode repo, then you'll need to update the version in the code-server repo by following these steps:

  1. Update the package tag listed in vendor/package.json:
{
  "devDependencies": {
    "vscode": "cdr/vscode#X.XX.X-code-server"
  }
}
  1. From the code-server project root, run yarn install. Then, test code-server locally to make sure everything works.
  2. 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.
  3. Open a PR

Watch for updates to vendor/modules/code-oss-dev/src/vs/code/browser/workbench/workbench.html. You may need to make changes to src/browser/pages/vscode.html.

Build

You can build as follows:

yarn build
yarn build:vscode
yarn release

Run your build:

cd release
yarn --production
# Runs the built JavaScript with Node.
node .

Build the release packages (make sure that you run yarn release first):

yarn release:standalone
yarn test:standalone-release
yarn package

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.

Help

If you get stuck or need help, you can always start a new GitHub Discussion here. One of the maintainers will respond and help you out.

Test

There are four kinds of tests in code-server:

  1. Unit tests
  2. Script tests
  3. Integration tests
  4. End-to-end tests

Unit tests

Our unit tests are written in TypeScript and run using Jest, the testing framework].

These live under test/unit.

We use unit tests for functions and things that can be tested in isolation. The file structure is modeled closely after /src so it's easy for people to know where test files should live.

Script tests

Our script tests are written in bash and run using bats.

These tests live under test/scripts.

We use these to test anything related to our scripts (most of which live under ci).

Integration tests

These are a work in progress. We build code-server and run a script called test-standalone-release.sh, which ensures that code-server's CLI is working.

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

The end-to-end (e2e) tests are written in TypeScript and run using Playwright.

These live under test/e2e.

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 would use it (see test.use).

We also have a model where you can create helpers to use within tests. See models/CodeServer.ts for an example.

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 as an HTTP API for login and starting a remote VS Code process.

The CLI code is in src/node and the HTTP routes are implemented in src/node/routes.

Most of the meaty parts are in the VS Code portion of the codebase under vendor/modules/code-oss-dev, 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 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 vendor/modules/code-oss-dev.

Some noteworthy changes in our version of VS Code include:

As the web portion of VS Code matures, we'll be able to shrink and possibly 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, we'd like to run VS Code unit tests against our builds to ensure that features work as expected.

We have extension docs 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.

Currently Known Issues

  • Creating custom VS Code extensions and debugging them doesn't work
  • Extension profiling and tips are currently disabled