Skip to main content

Contributing

Welcome! So glad you've decided to help make Cursorless better. Once you've learned how to set up and run / test a local copy of the extension, you may want to check out the Cursorless API docs to learn more about how Cursorless works. You may also find the VSCode API docs helpful to learn about VSCode extension development.

Initial setup​

Prerequisites​

  • Git
  • Node.js
  • yarn
  • [VSCode][https://code.visualstudio.com/]; minimum version for local development is 1.72.0 in order to support settings profiles for sandboxed development. Please file an issue if that is a problem.

Steps​

  1. Clone cursorless

  2. Open the newly created cursorless directory in VSCode. If you're on Windows, don't use WSL (see #919 for discussion / workaround).

  3. Add the following to your VSCode settings.json (can be opened by saying "show settings json" with a recent install of knausj)

    "workbench.experimental.settingsProfiles.enabled": true

    This setting allows you to debug the Cursorless extension in a clean, sandboxed version of VSCode, with its own extensions and settings, using the experimental VSCode settings profile feature.

  4. Run the following in the terminal:

    yarn
    yarn compile
    yarn init-launch-sandbox

    The yarn init-launch-sandbox command creates a local VSCode settings profile that acts as a sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. This approach is suggested by the VSCode documentation. If you'd like to use additional extensions when debugging locally, you can use the following command:

    code --profile=cursorlessDevelopment --install-extension some.extension

    where some.extension is the id of the extension you'd like to install into the sandbox

  5. Copy / symlink cursorless-talon-dev into your Talon user directory for some useful voice commands for developing Cursorless.

Running / testing extension locally​

In order to test out your local version of the extension or to run unit tests locally, you need to run the extension in debug mode. To do so you need to run the workbench.action.debug.selectandstart command in VSCode and then select either "Run Extension" or "Extension Tests".

Running a subset of tests​

The entire test suite takes a little while to run (1-2 mins), so if you'd like to run just a subset of the tests, you can edit the constant in runTestSubset to a string supported by mocha grep and use the "Run Test Subset" launch config instead of the usual "Extension Tests".

Code formatting​

We use pre-commit to automate autoformatting. Autoformatters will automatically run on PRs in CI, but you can also run them locally or install pre-commit hooks as described in the pre-commit documentation.

Running docs site locally​

Run the workbench.action.debug.selectandstart command and then select "Docusaurus Start (Debug)".

Adding tests​

See test-case-recorder.md.

Parse tree support​

Adding a new programming language​

See docs.

Adding syntactic scope types to an existing language​

See parse-tree-patterns.md.

Testing Cursorless with a local version of the VSCode parse tree extension​

First bundle the parse tree extension into a .vsix, using something like the following:

cd ../vscode-parse-tree
vsce package -o bundle.vsix

Once you have your package then you can install it into the sandbox using the following command:

code --profile=cursorlessDevelopment --install-extension bundle.vsix

Changing SVGs​

SVG preprocessing script​

You'll probably want to run the following to make sure the SVGs have everything they need:

yarn run compile && node ./out/scripts/preprocessSvgHats.js

This script will add dummy width, height and fill attributes as necessary to appease the regex in Decorations.ts

Adding hat adjustments at finish​

While tweaking, the easiest approach is probably to use the cursorless.individualHatAdjustments setting in your settings.json to change size / alignment so you don't need to refresh every time. Once you're done, you can paste the settings into scripts/hatAdjustments/add.ts and run the following to get your updates:

yarn run compile && node ./out/scripts/hatAdjustments/add.js

If instead, you want to average your adjustments with those in main and see the differences to get to yours and main, you can paste the settings into scripts/hatAdjustments/average.ts and run:

yarn run compile && node ./out/scripts/hatAdjustments/average.js