Add step-by-step guide to add syntax tests, see
@@ -23,9 +23,43 @@ in the `.sublime-syntax` format.
5. Use `bat --list-languages` to check if the new languages are available.
-6. If you send a pull request with your changes, please do *not* include the changed `syntaxes.bin`
+6. Add a syntax test for the new language. See [#Syntax-tests](below) for details.
+
+7. If you send a pull request with your changes, please do *not* include the changed `syntaxes.bin`
file. A new binary cache file will be created once before every new release of `bat`.
+### Syntax tests
+
+`bat` has a set of syntax highlighting regression tests in `tests/syntax-tests`. The main idea is
+make sure that we do not run into issues we had in the past where either (1) syntax highlighting
+for some language is suddenly not working anymore or (2) `bat` suddenly crashes for some input (due
+to `regex` incompatibilities between `syntect` and Sublime Text).
+
+In order to add a new test file, please follow these steps (let's take "Ruby" as an example):
+
+1. Make sure that you are running the **latest version of `bat`** and that `bat` is available on
+ the path.
+2. Find an example Ruby source file or write one yourself. If possible, the file should aim to be
+ "comprehensive" (i.e. include a lot of the possible syntax), but this is not strictly necessary.
+ A simple file is better than none at all. Also, the files shouldn't be gigantic.
+3. Save the file in `tests/syntax-tests/source/Ruby` (adapt for your language). The file name could
+ be `test.rb` (adapt extension) but can also be adapted if that is necessary in order for `bat` to
+ highlight it correctly (e.g. `Makefile`).
+4. If you have copied the file from somewhere else, please make sure that the file *may* be copied
+ under the respective license and that the license is compatible with `bat`s license. If it
+ requires attribution, please add a `LICENSE.md` in the same folder with a text like this:
+ ```
+ The `test.rb` file has been added from [enter source here] under the following license:
+
+ [add license text here]
+ ```
+5. Go to `tests/syntax-tests` and run the `update.sh` Bash script. A new file should be generated
+ in the `highlighted` folder (e.g. `highlighted/Ruby/test.rb`).
+6. Use `cat` or `bat --language=txt` to display the content of this file and make sure that the
+ syntax highlighting looks correct.
+7. `git add` the new files in the `source` folder as well as the autogenerated files in the
+ `highlighted` folder.
+
### Troubleshooting
Make sure that the local cache does not interfere with the internally stored syntaxes and
