Add step-by-step guide to add syntax tests, see #1211

1 files changed, 35 insertions, 1 deletions

diff --git a/doc/assets.md b/doc/assets.md
index a435a32f..2cf3d2d4 100644
--- a/doc/assets.md
+++ b/doc/assets.md
@@ -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