improve CONTRIBUTING docs

.vscode/launch.json

@@ -2,7 +2,7 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Debug Extension (TS LSP Enabled)",
+      "name": "Debug Extension (Glint + TS)",
       "type": "extensionHost",
       "request": "launch",
       "preLaunchTask": "npm: build",
@@ -18,7 +18,7 @@
       ]
     },
     {
-      "name": "Debug Extension (TS LSP Disabled)",
+      "name": "Debug Extension (Glint Only, No TS)",
       "type": "extensionHost",
       "request": "launch",
       "preLaunchTask": "npm: build",

CONTRIBUTING.md

@@ -17,3 +17,41 @@ Glint is a family of packages which all live in this repo as a Yarn workspace. T
 - Read the project’s [ARCHITECTURE.md](./ARCHITECTURE.md) to understand the basics of how the code base works.
 
 Once you have made changes and added tests to confirm they work correctly, you can then open a PR and we'll work with you to polish it up and get it landed!
+
+# Common Debugging Scenarios
+
+## How to run glint-language-server locally?
+
+If you would like to connect your editor to a locally running version of the Glint language server, first start the `tsc` compiler in watch mode from the root folder of the Glint repo:
+
+```
+tsc --build --watch
+```
+
+Then you can configure your editor to point to the absolute path of the `./packages/core` folder within this repo when launching the language server. For VSCode users, this means opening your user preferences (after having already installed the Glint VSCode extension) and setting "Glint: Library Path" (aka `glint.libraryPath`) to the absolute path of the `packages/core` folder, e.g. `/Users/machty/code/glint/packages/core`.
+
+With the running `tsc --build --watch` command, the language server will rebuild when any source code files change. _Important_: after any source code file change and subsequent rebuild, you will need to restart the language server from within your editor in order for the changes to be reflected in your editor. In VSCode, this means running "Glint: Restart Glint Server" from the Command Palette.
+
+_NOTE_: these instructions only apply to debugging the language server in a live-rebuilding manner; if you are interested in testing out the VSCode extension code, see below.
+
+## How to test out the VSCode extension locally?
+
+Firstly, there is an entire suite of integration tests that will spin up instances of VSCode and test out the VSCode Glint extension. These can be run from the `packages/vscode` directory via:
+
+```
+yarn run test
+```
+
+If you would like a more interactive environment in which to test out the extension, there are a few VSCode Launch Configurations within `./vscode/launch.json` that can be used.
+
+- Both of them spin up a new VSCode window in "Development Extension Host" mode to test out the extension code
+- Additionally, both will enable the TS/JS debugger on the language server, meaning the debug breakpoints will pause execution to allow you to debug things like text completions
+- Debug Extension (Glint + TS)
+  - This spins up a VSCode window with both Glint and the built-in TS language server running.
+  - In this mode, both language servers will provide duplicate completions and suggestions, which can be useful for testing out feature parity between Glint and TS
+- Debug Extension (Glint Only)
+  - This is useful for testing out the "takeover" mode of running Glint, where Glint is responsible for providing all of the language features (debugging, diagnostics, etc); this is the ideal way to run Glint, but at the time of writing we have not yet achieved feature parity with built-in TS
+
+
+These launch configurations can be run via the Run and Debug tab in VSCode.
+