CONTRIBUTING.md

Contributing & Maintaining

This guide contains the lightweight setup version (that only requires you to have node.js installed). If you wish to be able to run vscode from source, please see VSCode's How to Contribute.

A brief explanation on the source code structure

This repository contains no source code, it only contains the scripts to package everything together and ship the monaco-editor npm module:

These packages are described in the root file called metadata.js and it is possible to create an editor distribution that contains only certain plugins by editing that file.

repository	npm module	explanation
vscode	monaco-editor-core	editor core functionality (language agnostic) is shipped out of vscode.
monaco-languages	monaco-languages	plugin that adds colorization and basic supports for dozens of languages.
monaco-typescript	monaco-typescript	plugin that adds rich language support for JavaScript and TypeScript.
monaco-css	monaco-css	plugin that adds rich language support for CSS, LESS and SCSS.
monaco-json	monaco-json	plugin that adds rich language support for JSON.
monaco-html	monaco-html	plugin that adds rich language support for HTML.

Running the editor from source

You need to have all the build setup of being able to build VS Code to be able to build the Monaco Editor.

• Install all the prerequisites: https://github.com/Microsoft/vscode/wiki/How-to-Contribute#installing-prerequisites

OS X and Linux

/src> git clone https://github.com/microsoft/vscode
/src> cd vscode
# install npm deps for vscode
/src/vscode> ./scripts/npm.sh install
# start the compiler in the background
/src/vscode> npm run watch

Windows

/src> git clone https://github.com/microsoft/vscode
/src> cd vscode
# install npm deps for vscode
/src/vscode> scripts\npm.bat install
# start the compiler in the background
/src/vscode> npm run watch

• For the monaco editor test pages:

# clone monaco-editor (note the folders must be siblings!)
/src> git clone https://github.com/Microsoft/monaco-editor

# install npm deps for monaco-editor
/src/monaco-editor> npm install .

# start a local http server in the background
/src/monaco-editor> npm run simpleserver

Open http://localhost:8080/monaco-editor/test/?editor=dev to run.

Running a plugin from source (e.g. monaco-typescript)

# clone monaco-typescript
/src> git clone https://github.com/Microsoft/monaco-typescript

# install npm deps for monaco-typescript
/src/monaco-typescript> npm install .

# start the compiler in the background
/src/monaco-typescript> npm run watch

Open http://localhost:8080/monaco-editor/test/?editor=dev&monaco-typescript=dev to run.

Running the editor tests

/src/vscode> npm run monaco-editor-test
# or run a test page http://localhost:8080/monaco-editor/test/?editor=dev

Tip: All folders must be cloned as siblings.

Tip: When running the test pages, use the control panel in the top right corner to switch between running from source, running from npm or running from the local release:

Running the website

# create a local release
/src/monaco-editor> npm run release

# open http://localhost:8080/monaco-editor/website/

# build the website
/src/monaco-editor> npm run website

# open http://localhost:8080/monaco-editor-website/

# publish the website
/src/monaco-editor-website> git push origin gh-pages --force

---

Shipping a new monaco-editor npm module

1. Ship a new monaco-editor-core npm module

• bump version in /src/vscode/build/monaco/package.json
• [important] push all local changes to the remote to get a good public commit id.
• generate npm package /src/vscode> node_modules/.bin/gulp editor-distro
• publish npm package /src/vscode/out-monaco-editor-core> npm publish

2. Adopt new monaco-editor-core in plugins

• if there are breaking API changes that affect the language plugins, adopt the new API in:
  • repo - monaco-typescript
  • repo - monaco-languages
  • repo - monaco-css
  • repo - monaco-json
  • repo - monaco-html
• publish new versions of those plugins to npm as necessary.

3. Update package.json

• edit /src/monaco-editor/package.json and update the version (as necessary):
  • npm - monaco-editor-core
  • npm - monaco-typescript
  • npm - monaco-languages
  • npm - monaco-css
  • npm - monaco-json
  • npm - monaco-html
• [important] fetch latest deps by running /src/monaco-editor> npm install .

4. Generate and try out the local release

• /src/monaco-editor> npm run release
• try as many test pages as you think are relevant. e.g.:
  • open http://localhost:8080/monaco-editor/test/?editor=releaseDev
  • open http://localhost:8080/monaco-editor/test/?editor=releaseMin
  • open http://localhost:8080/monaco-editor/test/smoketest.html?editor=releaseDev
  • open http://localhost:8080/monaco-editor/test/smoketest.html?editor=releaseMin

5. Update release note.

• API Change/Breaking Change/New and noteworthy
• Thank you

6. Publish

• /src/monaco-editor> npm version minor
• /src/monaco-editor/release> npm publish
• /src/monaco-editor> git push --tags