Skip to content

Latest commit

 

History

History
88 lines (56 loc) · 3.48 KB

CONTRIBUTING.adoc

File metadata and controls

88 lines (56 loc) · 3.48 KB
Raw

Contributing

This guide describes how to develop changes for this Visual Studio Code plugin and how to test them locally.

Prerequisites

Before developing changes, install the following prerequisites:

Developing Changes and Testing the Extension

  1. Clone the repository from GitHub.

    $ git clone https://github.com/asciidoctor/asciidoctor-vscode.git

  2. Open the folder within Visual Studio Code.

  3. Download NPM package dependencies.

    $ npm install

  4. Make changes (ideally on a separate branch).

Testing is done differently on the desktop client and the web client.

Running the Desktop version

  1. With the folder open in Visual Studio code, from the menu bar, select Run > 'Start Debugging' (or click the Run and Debug icon on the left sidebar and click on the green 'Run Extension' play button)

  2. A new Visual Studio Code instance will open with '[Extension Development Host]' in the header.

  3. You can use the first Visual Studio Code instance to:

    • Apply breakpoints in the code (by clicking on a line number).

    • Access the Debug Console.

    • See errors in the Terminal window.

  4. You can find helpful debug information in:

    • The extension logs — Go to the Command Palette and select the option 'Developer: Open Extension Logs Folder'.

    • The web view developer tools — Go to the Command Palette and select the option 'Developer: Open Webview Developer Tools'.

To run the tests suite, select 'Run Extension Tests' in the 'Run' view then, click on the green play button or run the 'Start Debbuging' command.

You can also run the tests suite from a terminal using:

$ npm t
Note

In that case, you must close your Visual Studio code instance otherwise you will get an error:

Running extension tests from the command line is currently only supported if no other instance of Code is running.

Running the Web version

On Linux to test the extension run the following command within the repository folder from the command line:

$ npm run build-web && npm run build-preview && npx @vscode/test-web --browserType=chromium --extensionDevelopmentPath=${PWD}
Important
 In development, you will need to disable security because resources are loaded through http://localhost:3000/static/devextensions
Tip
 Looking at the browser’s Web Developer tools can often help locate errors.

Updating The Grammar

This package now uses the Atom language package to generate a grammar.

This can be updated manually using the following process:

  1. Install the cson npm package

    npm install --global cson

  2. Retrieve and convert the grammar:

    curl https://raw.githubusercontent.com/asciidoctor/atom-language-asciidoc/master/grammars/language-asciidoc.cson | cson2json > ./syntaxes/Asciidoctor.json

  3. Now manually edit and change the scope name from "scopeName": "source.asciidoc" to "scopeName": "text.asciidoc"

Because this package has diverged slightly from upstream it may be best to cherry-pick commits after the original conversion or do before/after comparisons and account for each change.

Where possible it is recommended to do PRs upstream and then use that result here.