Merge pull request #149 from ckipp01/contribute

docs: add some basic contributing docs

Author: ckipp01

CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to tree-sitter-scala
+
+First off, thanks for being willing to contribute to making syntax highlighting
+in Scala better! This document will hopefully help you get set up, understand
+how to work on the codebase, or link to places to help you understand
+tree-sitter.
+
+## Requirements
+
+- 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)
+for more details and specifics.
+
+If you use nix you can enter a nix-shell (`nix-shell .`) which will install them
+for you.
+
+## Getting Started
+
+To get started with contributing to the grammar you'll first need to install the
+project's dependencies:
+
+```sh
+npm install
+```
+
+The general flow will often start with adding a test case to `./corpus`. You can
+find details on how testing works with tree-sitter
+[here](https://tree-sitter.github.io/tree-sitter/creating-parsers#command-test).
+
+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
+```
+
+Then adjust as necessary. Note that depending on your change you may also have
+to touch the `/src/scanner.c` file if you need more advanced features like
+look-ahead.
+
+## Syntax highlighting
+
+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`.
+
+### 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:
+
+```sh
+tree-sitter highlight some/scala/file.scala
+```
+
+And see the syntax highlighting spit out. This is also the format used for
+testing, so it provides an easy way to get the output we use for testing.
+
+## Generation
+
+In order to help not cause conflicts with multiple prs being open at the same
+time, we don't check in the parser on each pr. Instead, just check in the
+changes to the `grammar.js` and the CI will take care of the rest. Each night if
+changes are detected it will automatically be generated.
+
+## Smoke testing
+
+You'll noticed that there is a part of CI that checks parsing against the Scala
+2 and Scala 3 repositories to ensure we don't introduce unexpected regressions.
+The script for this is in `script/smoke_test.sh`. If you're change is increasing
+the coverage in either the library or compiler, please do update the expected
+percentages at the top of the file.
+
+## Obtaining an error reproduction
+
+_With Neovim_
+
+When creating an issue you'll want to ensure to include the `ERROR` node in it's
+context. There's a couple ways to do this. If you're using Neovim and utilizing
+treesitter, you can see the tree with `:lua vim.treesitter.show_tree()`. You can
+copy it directly from the open panel.
+
+_Manually_
+
+A manual way to get this would be to ensure that when you're in the repo you
+have the latest parser with
+
+```sh
+npm run build
+```
+
+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>
+```
+
+Then the tree will be printed out for you to copy.
+

README.md

@@ -2,32 +2,20 @@
 
 [![Test the grammar](https://github.com/tree-sitter/tree-sitter-scala/actions/workflows/ci.yml/badge.svg)](https://github.com/tree-sitter/tree-sitter-scala/actions/workflows/ci.yml)
 
-Scala grammar for [tree-sitter](https://github.com/tree-sitter/tree-sitter).
+Scala grammar for [tree-sitter](https://github.com/tree-sitter/tree-sitter)
+covering both Scala 2 and 3.
 
-References
+## References
 
-- [The Scala Language Specification](https://www.scala-lang.org/files/archive/spec/2.13/)
-- [Scala Syntax Summary](https://www.scala-lang.org/files/archive/spec/2.13/13-syntax-summary.html)
+_Scala 2_
+- [The Scala 2 Language Specification](https://www.scala-lang.org/files/archive/spec/2.13/)
+- [Scala 2 Syntax Summary](https://www.scala-lang.org/files/archive/spec/2.13/13-syntax-summary.html)
 
-## Development
+_Scala 3_
 
-Requirements:
+- [Scala 3 Syntax Summary](https://docs.scala-lang.org/scala3/reference/syntax.html)
 
-- Node.js version 6.0 or greater
-- C Compiler
+## Development and Contributing
 
-Refer to the [tree-sitter documentation](https://tree-sitter.github.io/tree-sitter/creating-parsers#dependencies) for more details. If you use nix you can enter a nix-shell (`nix-shell .`) which will install them for you.
-
-Then, install the project's dependencies:
-
-```sh
-npm install
-```
-
-Add a test case to `./corpus`, make the required changes to `grammar.js`,
-regenerate and recompile the parser, and run the tests:
-
-```sh
-npm run build
-npm test
-```
+Please refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on
+getting set up.