From cc6de1e08229d89475f512f4a03c2635aa743d5c Mon Sep 17 00:00:00 2001 From: Marceline Cramer Date: Fri, 1 May 2026 18:30:30 -0600 Subject: [PATCH] Document tree-sitter contribution guidelines --- CONTRIBUTING.md | 21 +++++++++++++++++++-- README.md | 1 + 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b929e9..3567f4c 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 5dd9b43..1af9862 100644 --- a/README.md +++ b/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