monaco-editor/CONTRIBUTING.md

Contributing & Maintaining

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 VS Code to be able to build the Monaco Editor.

• Install all the prerequisites

OS X and Linux

# clone vscode-loc repository for localized string resources
/src> git clone https://github.com/microsoft/vscode-loc
# clone VS Code repository
/src> git clone https://github.com/microsoft/vscode
/src> cd vscode
# install npm deps for vscode
/src/vscode> yarn
# start the compiler in the background
/src/vscode> yarn run watch

Windows

# clone vscode-loc repository for localized string resources
/src> git clone https://github.com/microsoft/vscode-loc
# clone VS Code repository
/src> git clone https://github.com/microsoft/vscode
/src> cd vscode
# install npm deps for vscode
/src/vscode> yarn
# start the compiler in the background
/src/vscode> yarn 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=src 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=src&monaco-typescript=src 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=src

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 locally

Note: The website is published automatically when pushing to the master branch.

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

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

# start local webserver
/src/monaco-editor> npm run simpleserver

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

Shipping a new monaco-editor npm module

0.

• make sure you have https://github.com/microsoft/vscode-loc checked out next to the vscode folder.

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 (use this tool)

6. Publish

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

7. Update Website

• /src/monaco-editor> npm run website

8. Publish new webpack plugin

• https://github.com/microsoft/monaco-editor-webpack-plugin
• update to latest monaco-editor
• npm install .
• npm run import-editor
• if there are no changes generated after the script:
  • update the peer dependency in package.json and use the || format e.g. "monaco-editor": "0.27.x || 0.28.x"
  • update the version matrix in the README.md and add the new editor version to the plugin's current major version
  • use npm version minor
  • publish using npm publish
• if there are any changes generated after the script:
  • update the peer dependency in package.json e.g. "monaco-editor": "0.29.x"
  • update the version matrix in the README.md and add a new row with the new major version
  • use npm version major
  • publish using npm publish
• remember to push tags upstream