docs: update CONTRIBUTING.md

1 files changed, 46 insertions, 19 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 473a26cb5..b7ecb5690 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,22 +9,53 @@ The main goal of `nvim-treesitter` is to provide a framework to easily install p
 
 Depending on which part of the plugin you want to contribute to, please read the appropriate section.
 
-## Style Checks and Tests
+## Parsers
 
-We haven't implemented any functional tests yet. Feel free to contribute.
-However, we check code style with `luacheck` and `stylua`!
-Please install luacheck and activate our `pre-push` hook to automatically check style before
-every push:
+To add a new parser, edit the following files:
 
-```bash
-luarocks install luacheck
-cargo install stylua
-ln -s ../../scripts/pre-push .git/hooks/pre-push
+1. In `lua/parsers.lua`, add an entry to the `M.configs` table of the following form:
+
+```lua
+zimbu = {
+  install_info = {
+    url = 'https://github.com/zimbulang/tree-sitter-zimbu', -- local path or git repo
+    files = { 'src/parser.c' }, -- note that some parsers also require src/scanner.c or src/scanner.cc
+    -- optional entries:
+    branch = 'develop', -- only needed if different from default branch
+    location = 'parser', -- only needed if the parser is in subdirectory of a "monorepo"
+    revision = 'v2.1', -- tag or commit hash; bypasses automated updates
+    requires_generate_from_grammar = true, -- only needed if repo does not contain pre-generated src/parser.c
+    generate_requires_npm = true, -- only needed if parser has npm dependencies
+  },
+  maintainers = { '@me' }, -- the _query_ maintainers
+  tier = 3, -- community-contributed parser
+  -- optional entries:
+  requires = { 'vim' }, -- if the queries inherit from another language
+  readme_note = "an example language", -- if the 
+}
+```
+
+**Note:** The "maintainers" here refers to the person maintaining the **queries** in `nvim-treesitter`, not the parser maintainers (who likely don't use Neovim). The maintainers' duty is to review issues and PRs related to the query and to keep them updated with respect to parser changes.
+
+2. In `lockfile.json`, add an entry for the current commit your queries are compatible with:
+
+```json
+  "zimbu": {
+    "revision": "0d08703e4c3f426ec61695d7617415fff97029bd"
+  },
 ```
 
-## Parser configurations
+3. If the parser name is not the same as the Vim filetype, add an entry to the `filetypes` table in `plugin/filetypes.lua`:
+
+```lua
+  zimbu = { 'zu' },
+```
+
+**Note: We only support external scanners written in C (preferably) and C++03 for portability reasons.**
+
+## Queries
 
-Contributing to parser configurations is basically modifying one of the `runtime/queries/*/*.scm`.
+Contributing to queries for an existing parser is basically modifying one of the `runtime/queries/*/*.scm`.
 Each of these `scheme` files contains a _tree-sitter query_ for a given purpose.
 Before going any further, we highly suggest that you [read more about tree-sitter queries](https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries).
 
@@ -40,19 +71,15 @@ For now these are the types of queries used by `nvim-treesitter`:
 For these types there is a _norm_ you will have to follow so that features work fine.
 Here are some global advices:
 
-- If your language is listed [here](https://github.com/nvim-treesitter/nvim-treesitter#supported-languages),
-  you can debug and experiment with your queries there.
-- If not, you should consider installing the [tree-sitter CLI](https://github.com/tree-sitter/tree-sitter/tree/master/cli),
-  you should then be able to open a local playground using `tree-sitter build-wasm && tree-sitter web-ui` within the
-  parsers repo.
 - Examples of queries can be found in [runtime/queries/](runtime/queries/)
-- Matches in the bottom will override queries that are above of them.
+- Note that (unlike tree-sitter) all matching patterns are applied, with the last one determining the visible highlight.
+- If the [parser is included in `nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter/SUPPORTED_LANGUAGES.md`) and installed with `:TSInstall`, you can use Neovim's developer tools (`:checkhealth`, `:InspectTree`, `:EditQuery`, `:Inspect`) to test your queries.
 
 #### Inheriting languages
 
 If your language is an extension of a language (TypeScript is an extension of JavaScript for
 example), you can include the queries from your base language by adding the following _as the first
-line of your file_.
+line of your file_:
 
 ```query
 ; inherits: lang1,(optionallang)
@@ -298,7 +325,7 @@ Note that nvim-treesitter uses more specific subcaptures for definitions and
 @local.reference             ; identifier reference
 ```
 
-#### Definition Scope
+#### Definition scope
 
 You can set the scope of a definition by setting the `scope` property on the definition.