Development Workflow

Relevant source files

• .prettierignore
• .prettierrc.yaml
• ci/build/build-code-server.sh
• ci/build/update-repo.sh
• ci/build/update-vscode.sh
• ci/dev/doctoc.sh
• ci/dev/watch.ts
• ci/lib.sh
• docs/CODE_OF_CONDUCT.md
• install.sh
• patches/csp-hashes.diff
• tsconfig.json

This page documents the day-to-day development workflow for contributors working on code-server. It covers the development iteration cycle using watch mode, managing VS Code patches with quilt, code formatting, and linting tools.

Development Iteration Cycle

The primary development workflow uses npm run watch to enable rapid iteration. This script launches a watcher process that orchestrates multiple compilers and a development web server.

Watch Mode Implementation

The watch mode is implemented in ci/dev/watch.ts. It manages several child processes simultaneously to handle different parts of the stack.

Watcher Orchestration Diagram

Implementation Details:

• Compilers: The Watcher class initializes compilers for code-server (using tsc), VS Code (using internal npm scripts), and optional plugins ci/dev/watch.ts46-53
• Line Parsing: It monitors the stdout of these processes. When tsc outputs "Watching for file changes" or VS Code outputs "Finished compilation", the watcher triggers a server reload via reloadWebServer ci/dev/watch.ts90-93 ci/dev/watch.ts101-104
• Web Server: The development server is spawned using the compiled entry point out/node/entry.js and inherits CLI arguments passed to the watch script ci/dev/watch.ts31-33

Sources: ci/dev/watch.ts13-40 ci/dev/watch.ts46-53 ci/dev/watch.ts85-105

TypeScript Configuration

The build and watch processes rely on tsconfig.json settings.

Setting	Value	Purpose
outDir	./out	Destination for compiled JavaScript tsconfig.json11
incremental	true	Enables faster subsequent builds via .cache/tsbuildinfo tsconfig.json17-18
target	es6	Target ECMAScript version tsconfig.json3
module	commonjs	Module system used by the Node.js backend tsconfig.json5

Sources: tsconfig.json1-30

Patch Management with Quilt

Code-server modifies the VS Code source code (located in lib/vscode) using quilt. This allows maintaining a clean separation between upstream VS Code and code-server's specific changes.

Patch Integration Flow

Quilt Operations Diagram

Key Concepts:

• The Series File: Located at patches/series, this file defines the order in which patches are applied.
• The .pc Directory: A hidden directory used by quilt to track which patches are applied and the state of original files. This is explicitly ignored by version control tsconfig.json29 .prettierignore7
• Refresh Cycle: After modifying files in lib/vscode, developers must run quilt refresh to update the patch files in the patches/ directory.

VS Code Update and Patch Refreshing

The ci/build/update-vscode.sh script automates the maintenance of patches when the upstream VS Code version changes. It includes functions for:

• unapply_patches: Uses quilt pop -af to revert the VS Code submodule to a clean state ci/build/update-vscode.sh5-16
• apply_patches: Uses quilt push -a to apply all patches in the series ci/build/update-vscode.sh18-29
• refresh_patches: Iteratively pushes and refreshes patches to resolve conflicts during updates ci/build/update-vscode.sh42-53
• update_csp: Regenerates Content Security Policy hashes for webviews and worker extension hosts, storing them in patches/csp-hashes.diff ci/build/update-vscode.sh85-107 patches/csp-hashes.diff1-26

Sources: ci/build/update-vscode.sh5-107 patches/csp-hashes.diff1-26

Code Quality and Formatting

The project enforces strict code quality standards through automated tools.

Formatting with Prettier

Prettier is used to ensure consistent code style. The configuration is defined in .prettierrc.yaml.

• Configuration: Uses a printWidth of 120, no semicolons (semi: false), and double quotes .prettierrc.yaml1-7
• Ignored Paths: Several directories are excluded from formatting, including lib (VS Code source), release, and .pc (quilt state) .prettierignore1-8

Documentation Management

The ci/dev/doctoc.sh script is used to maintain Tables of Contents in Markdown files like docs/CONTRIBUTING.md and docs/CODE_OF_CONDUCT.md ci/dev/doctoc.sh7-15

Build Preparation

The ci/build/build-code-server.sh script handles the final steps of the build, including:

1. Running tsc to compile the source ci/build/build-code-server.sh9
2. Adding the Node.js shebang to out/node/entry.js and making it executable ci/build/build-code-server.sh13-16

Sources: .prettierrc.yaml1-6 .prettierignore1-8 ci/dev/doctoc.sh7-15 ci/build/build-code-server.sh9-16

Development Workflow Summary

The standard iteration cycle for a developer follows this sequence:

1. Preparation: Ensure patches are applied to the VS Code submodule using quilt push -a.
2. Execution: Run npm run watch to start the compilers and dev server.
3. Modification:
   • If changing code-server: Edit files in src/. tsc --watch will recompile to out/ ci/dev/watch.ts47
   • If changing VS Code: Edit files in lib/vscode/. The VS Code watch task will recompile ci/dev/watch.ts48
4. Verification: The watcher detects the "Finished compilation" output and restarts the web server via reloadWebServer() ci/dev/watch.ts92
5. Finalization: Run quilt refresh if lib/vscode was modified, and ensure formatting complies with .prettierrc.yaml.

Sources: ci/dev/watch.ts26-40 ci/dev/watch.ts85-105 .prettierrc.yaml1-6