monaco-editor/CONTRIBUTING.md

Contributing & Maintaining

A brief explanation on the source code structure

This repository contains source code only for Monaco Editor Languages, the core editor source lives in the vscode repository.

repository	npm module	explanation
vscode	monaco-editor-core	editor core functionality (language agnostic) is shipped out of vscode.
monaco-editor	monaco-editor	the Monaco Editor.

Contributing a new tokenizer / a new language

• create $/src/basic-languages/myLang/myLang.contribution.ts
• create $/src/basic-languages/myLang/myLang.ts
• create $/src/basic-languages/myLang/myLang.test.ts
• edit $/src/basic-languages/monaco.contribution.ts and register your new language

import './myLang/myLang.contribution';

Updating TypeScript

• change typescript's version in package.json.
• execute npm install .
• execute npm run import-typescript
• adopt new APIs

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

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

# compile and bundle all plugins
/src/monaco-editor> npm run release

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

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

Running the editor tests

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

# run unit tests
/src/monaco-editor> npm run test

# compile the webpack plugin
/src/monaco-editor> npm run compile --prefix webpack-plugin

# package using the webpack plugin
/src/monaco-editor> npm run smoketest --prefix webpack-plugin

# run the smoketest
/src/monaco-editor> npm run smoketest-debug

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> yarn gulp editor-distro
• publish npm package /src/vscode/out-monaco-editor-core> npm publish

2. Adopt new monaco-editor-core version

• edit /src/monaco-editor/package.json and update the version of monaco-editor-core

# fetch latest deps
/src/monaco-editor> npm install .

4. Generate and try out the local release

• run the editor smoketest via CI or manually.

5. Update release note.

• API Changes / Breaking Changes / 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 origin v0.50.0

7. Update Website

• /src/monaco-editor> npm run website

8. Publish new webpack plugin

• TBD
• https://github.com/microsoft/monaco-editor/tree/main/webpack-plugin
• 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