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

# clone vscode
/src> git clone https://github.com/Microsoft/vscode

# install minimal npm deps for vscode
/src/vscode> npm run monaco-editor-setup

# start the compiler in the background
/src/vscode> gulp watch-client

# 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> 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. Publish

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