Skip to content

Update CONTRIBUTING.md #456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 6, 2025
Merged

Update CONTRIBUTING.md #456

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6b8b5f9
Update CONTRIBUTING.md
jonshea Mar 4, 2025
3eef52e
Change test command from `npm test` to `tree-sitter test`.
jonshea Mar 4, 2025
32b6e0d
Clarify that `tree-sitter test` also runs highlight tests
jonshea Mar 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,12 @@ tree-sitter.

## Requirements

- [tree-sitter CLI](https://github.com/tree-sitter/tree-sitter/tree/master/cli)
- Node.js version 18.0 or greater
- C Compiler

Refer to the [tree-sitter
documentation](https://tree-sitter.github.io/tree-sitter/creating-parsers#dependencies)
documentation](https://tree-sitter.github.io/tree-sitter/creating-parsers/1-getting-started.html)
for more details and specifics.

If you use nix you can enter a nix-shell (`nix-shell .`) which will install them
Expand All @@ -26,16 +27,16 @@ project's dependencies:
npm install
```

The general flow will often start with adding a test case to `./corpus`. You can
The general flow will often start with adding a test case to `./test/corpus`. You can
find details on how testing works with tree-sitter
[here](https://tree-sitter.github.io/tree-sitter/creating-parsers#command-test).
[here](https://tree-sitter.github.io/tree-sitter/creating-parsers/5-writing-tests.html).

Once you've added your test case you'll want to then make the required changes
to `grammar.js`, regenerate and recompile the parser, and run the tests:

```sh
npm run build
npm test
tree-sitter generate
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the command to use now? I see it is used in CI (https://github.com/tree-sitter/tree-sitter-scala/blob/master/.github/workflows/sync.yml#L27), but I’m not sure if anything else also needs to be called?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the main testing CI script is https://github.com/tree-sitter/parser-test-action/blob/master/action.yml, and looks like it should be

tree-sitter generate
tree-sitter test

I think.

tree-sitter test
```

Then adjust as necessary. Note that depending on your change you may also have
Expand All @@ -48,15 +49,18 @@ Right now the most common use-case for syntax highlight using tree-sitter is
[nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter), which
means much of our testing is in relation to it. You can find the syntax
highlighting tests in `test/highlight/*.scala`. You can read more about this
type of testing
[here](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#unit-testing). These test will be automatically ran with `npm run test`.
type of testing
[here](https://tree-sitter.github.io/tree-sitter/3-syntax-highlighting.html#unit-testing).
These test will be run automatically with `tree-sitter test`.

### tree-sitter highlight

Another way to test your syntax highlighting locally is to use the `tree-sitter
highlight` command. Note that you'll need to have `tree-sitter` installed
globally for this to work. Once you have it installed you'll want to follow the
instructions [here](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#per-user-configuration) to setup a local config that points towards this repo to be used as a parser. Once done you can then do the following:
instructions [here](https://tree-sitter.github.io/tree-sitter/3-syntax-highlighting.html#overview)
to setup a local config that points towards this repo to be used as a parser.
Once done you can then do the following:

```sh
tree-sitter highlight some/scala/file.scala
Expand Down Expand Up @@ -102,8 +106,7 @@ Then you can copy your Scala code in a file and pass that file into `npm run
parse`:

```
npm run parse <path/to/your/file.scala>
tree-sitter parse <path/to/your/file.scala>
```

Then the tree will be printed out for you to copy.

Loading