diff --git a/.prettierignore b/.prettierignore index 3b95f68ba1..ca94ac3fec 100644 --- a/.prettierignore +++ b/.prettierignore @@ -7,5 +7,3 @@ pnpm-lock.yaml .github/PULL_REQUEST_TEMPLATE.md -# Formatting breaks code blocks nested within tabs -packages/cursorless-org-docs/src/docs/contributing/CONTRIBUTING.mdx diff --git a/packages/cursorless-org-docs/src/docs/contributing/CONTRIBUTING.mdx b/packages/cursorless-org-docs/src/docs/contributing/CONTRIBUTING.mdx index 8136b1fce1..138dddc06e 100644 --- a/packages/cursorless-org-docs/src/docs/contributing/CONTRIBUTING.mdx +++ b/packages/cursorless-org-docs/src/docs/contributing/CONTRIBUTING.mdx @@ -17,81 +17,102 @@ Welcome! So glad you've decided to help make Cursorless better. You'll want to s ### Steps -1. Clone [`cursorless`](https://github.com/cursorless-dev/cursorless) locally. Note that it doesn't matter where you clone it, as long as you _**do not**_ clone it into your Talon user directory. -2. Open the newly created `cursorless` directory in VSCode. If you're on Windows, don't use WSL (see [#919](https://github.com/cursorless-dev/cursorless/issues/919) for discussion / workaround). -3. Run the following in the terminal: - - ```bash - pnpm install - pnpm compile - ``` - -4. Run the following in the terminal: - - - - ```bash - code --profile=cursorlessDevelopment - ``` - - - ```bash - codium --profile=cursorlessDevelopment - ``` - - - - and then close the window that opens (eg say `"window close"`). This step is necessary to create the [VSCode settings profile](https://code.visualstudio.com/updates/v1_72#_settings-profiles) 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. Once https://github.com/microsoft/vscode/issues/172046 is resolved, we will be able to remove this step, as the profile can then automatically be created. - -5. Run the following in the terminal: - - - - ```bash - pnpm init-vscode-sandbox - ``` - - - ```bash - pnpm init-vscode-sandbox --codium - ``` - - VSCodium users will also need to - manually download and install the `jrieken:vscode-tree-sitter-query` - extension, as it is [currently not - avalible](https://github.com/jrieken/vscode-tree-sitter-query/issues/28) - on the OpenVSX Marketplace. Instructions on how to manually download the - extension can be found [in this Stack Overflow - post](https://stackoverflow.com/a/79565372) - ([archived](https://web.archive.org/web/20250421130639/https://stackoverflow.com/questions/79359919/how-can-i-manually-download-vsix-files-now-that-the-vs-code-marketplace-no-long/79565372#79565372)), - while manual installation instructions can be found directly - below—replace `some.extension` with the acquired `.vsix` file's path - instead of an extension id. - - - - Said command adds extensions to the aforementioned 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](https://code.visualstudio.com/updates/v1_72#_extension-debugging-in-a-clean-environment) by the VSCode documentation. If you need to update any of the extension dependencies in the sandbox, you can add `--force` to the command. If you'd like to use additional extensions when debugging locally, you can use the following command: - - - - ```bash - code --profile=cursorlessDevelopment --install-extension some.extension - ``` - - - ```bash - codium --profile=cursorlessDevelopment --install-extension some.extension - ``` - - - - where `some.extension` is the id of the extension you'd like to install into the sandbox. - - Note that you do not need to install the Cursorless extension into the `cursorlessDevelopment` profile. A local development version of Cursorless will be automatically installed there every time you debug the extension, as described below. - - Also note that if you are adding support for a new language that isn't in the default list of [language identifiers](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) supported by VSCode, you may need to add an extension dependency. See [Adding a new language](./adding-a-new-language.md#2-ensure-file-type-is-supported-by-vscode) for more details. - -6. Copy / symlink [`cursorless-talon-dev`](../../cursorless-talon-dev) into your Talon user directory for some useful voice commands for developing Cursorless. +1. Clone [`cursorless`](https://github.com/cursorless-dev/cursorless) locally. Note that it doesn't matter where you clone it, as long as you _**do not**_ clone it into your Talon user directory. +2. Open the newly created `cursorless` directory in VSCode. If you're on Windows, don't use WSL (see [#919](https://github.com/cursorless-dev/cursorless/issues/919) for discussion / workaround). +3. Run the following in the terminal: + + ```bash + pnpm install + pnpm compile + ``` + +4. Run the following in the terminal: + + + + + + ```bash + code --profile=cursorlessDevelopment + ``` + + + + + + ```bash + codium --profile=cursorlessDevelopment + ``` + + + + + + and then close the window that opens (eg say `"window close"`). This step is necessary to create the [VSCode settings profile](https://code.visualstudio.com/updates/v1_72#_settings-profiles) 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. Once https://github.com/microsoft/vscode/issues/172046 is resolved, we will be able to remove this step, as the profile can then automatically be created. + +5. Run the following in the terminal: + + + + + + ```bash + pnpm init-vscode-sandbox + ``` + + + + + + ```bash + pnpm init-vscode-sandbox --codium + ``` + + VSCodium users will also need to + manually download and install the `jrieken:vscode-tree-sitter-query` + extension, as it is [currently not + avalible](https://github.com/jrieken/vscode-tree-sitter-query/issues/28) + on the OpenVSX Marketplace. Instructions on how to manually download the + extension can be found [in this Stack Overflow + post](https://stackoverflow.com/a/79565372) + ([archived](https://web.archive.org/web/20250421130639/https://stackoverflow.com/questions/79359919/how-can-i-manually-download-vsix-files-now-that-the-vs-code-marketplace-no-long/79565372#79565372)), + while manual installation instructions can be found directly + below—replace `some.extension` with the acquired `.vsix` file's path + instead of an extension id. + + + + + + Said command adds extensions to the aforementioned 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](https://code.visualstudio.com/updates/v1_72#_extension-debugging-in-a-clean-environment) by the VSCode documentation. If you need to update any of the extension dependencies in the sandbox, you can add `--force` to the command. If you'd like to use additional extensions when debugging locally, you can use the following command: + + + + + + ```bash + code --profile=cursorlessDevelopment --install-extension some.extension + ``` + + + + + + ```bash + codium --profile=cursorlessDevelopment --install-extension some.extension + ``` + + + + + + where `some.extension` is the id of the extension you'd like to install into the sandbox. + + Note that you do not need to install the Cursorless extension into the `cursorlessDevelopment` profile. A local development version of Cursorless will be automatically installed there every time you debug the extension, as described below. + + Also note that if you are adding support for a new language that isn't in the default list of [language identifiers](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) supported by VSCode, you may need to add an extension dependency. See [Adding a new language](./adding-a-new-language.md#2-ensure-file-type-is-supported-by-vscode) for more details. + +6. Copy / symlink [`cursorless-talon-dev`](../../cursorless-talon-dev) into your Talon user directory for some useful voice commands for developing Cursorless. ## Running / testing extension locally @@ -150,14 +171,18 @@ Once you have your package then you can install it into the sandbox using the fo + ```bash code --profile=cursorlessDevelopment --install-extension bundle.vsix ``` + + ```bash codium --profile=cursorlessDevelopment --install-extension bundle.vsix ``` +