Document tree-sitter contribution guidelines

CONTRIBUTING.md

@@ -1,2 +1,19 @@
-TODO: document tree-sitter generation rules (with old ABI version)
+- TODO: document VSCode extension development practices
-TODO: document VSCode extension development practices
+- TODO: document Helix Kerolox language setup
+- TODO: document licensing and attribution guidelines
+
+# Contributing to the Tree-sitter Grammar
+
+The Kerolox tooling makes use of a custom [tree-sitter](https://github.com/tree-sitter/tree-sitter) grammar for fast incremental parsing.
+
+The tree-sitter grammar lives in the `tree-sitter-kerolox` directory in the repository. The main file of interest is `grammar.js`, which defines the actual Kerolox grammar. The [tree-sitter documentation](https://tree-sitter.github.io/tree-sitter/creating-parsers/index.html) has very useful documentation on how to work with this grammar definition.
+
+Any time the grammar is modified, the tree-sitter parser needs to be regenerated using the [tree-sitter CLI](https://github.com/tree-sitter/tree-sitter/blob/master/crates/cli/README.md). Otherwise, the changes to the grammar won't actually be compiled. To regenerate the parser from the grammar, ensure the CLI is installed, and run this command in the `tree-sitter-kerolox` directory:
+
+```bash
+tree-sitter generate --abi 14
+```
+
+We use an [ABI version](https://tree-sitter.github.io/tree-sitter/using-parsers/7-abi-versions.html) of 14 because it's known to work with older versions of [Helix](https://helix-editor.com), Marceline's preferred text editor. This is a deliberately overly cautious policy, but we're open to changing it if there's a good reason to.
+
+The generated files should be committed and pushed as normal, since it's conventional for third-party tools to pull and compile pregenerated tree-sitter parsers directly from their upstream repositories.

README.md

@@ -6,6 +6,7 @@
 - TODO: automatic documentation checking
 - TODO: automatically publish crate docs?
 - TODO: use coverage to drive test cases, particularly in the parse stage
+- TODO: consider switching to [tree-house](https://github.com/helix-editor/tree-house) for improved parsing and semantic highlighting logic
 
 # Kerolox