From 962b3a78c0891ede2cfb93c9e026d57684668a24 Mon Sep 17 00:00:00 2001 From: sharkdp Date: Sat, 2 Jan 2021 10:21:02 +0100 Subject: [PATCH] Add step-by-step guide to add syntax tests, see #1211 --- doc/assets.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) 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